rcf-lite 0.20.0 → 0.22.0

package/src/blueprint/capabilities.js

@@ -0,0 +1,357 @@
+// Capability-declaration mechanism (visual round T-5 spec section
+// 5.5.1, 5.5.2). Consumer blueprints gate their surfaces on the union
+// of currently-applied blueprints' `capabilities[]` declarations.
+//
+// Why source read-back. The applied-blueprint-record schema in
+// @stravica-ai/rcf-schemas is closed under additionalProperties:false
+// (0.6.0), so `appliedCapabilities[]` cannot land on the manifest
+// record without a schema bump. Rather than block the round on that
+// dependency, this file adopts the core-companions T-2 gate precedent:
+// read the source blueprint.json via manifest.blueprints[].source and
+// union its declared capabilities[]. Per-project answers (elicits) and
+// a per-project applied-capability snapshot are written to a sidecar
+// file at rcf/blueprints/${slug}.applied.json.
+//
+// This file is imported by apply.js at apply time and by the shipped
+// probe pack (blueprints/application-admin-console/probe-packs/) at
+// verify time.
+
+import { readFile, writeFile, mkdir, stat } from 'node:fs/promises';
+import { dirname, join, resolve, isAbsolute } from 'node:path';
+
+import { rcfError } from '../core/errors/index.js';
+
+/**
+ * Read a single applied blueprint's declared capabilities via
+ * source read-back. Silently ignores an applied blueprint whose
+ * source path no longer exists (the record's ownership fact is the
+ * slug on the manifest; the source file is provenance and can move).
+ *
+ * @param {{ slug: string, source: string }} appliedRecord
+ * @param {string} projectRoot
+ * @returns {Promise<string[]>}
+ */
+export async function readAppliedBlueprintCapabilities(appliedRecord, projectRoot) {
+  if (!appliedRecord || typeof appliedRecord.source !== 'string') return [];
+  const src = appliedRecord.source;
+  // A qualified typed ref (`wsd:auth-oauth2`) never resolves as a file
+  // path. Skip it; the library-resolved source blueprint is not on
+  // this local tree.
+  if (/^[a-z][a-z0-9-]*:[a-z]/i.test(src) && !src.startsWith('/') && !src.startsWith('.')) return [];
+  const abs = isAbsolute(src) ? src : resolve(projectRoot, src);
+  const metaPath = join(abs, 'blueprint.json');
+  let raw;
+  try {
+    raw = await readFile(metaPath, 'utf8');
+  } catch {
+    return [];
+  }
+  try {
+    const doc = JSON.parse(raw);
+    if (!Array.isArray(doc.capabilities)) return [];
+    return doc.capabilities.filter((s) => typeof s === 'string');
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Discover the union of applied capabilities across every applied
+ * blueprint on the tree.
+ *
+ * @param {Array<{ slug: string, source: string }>} appliedRecords
+ * @param {string} projectRoot
+ * @returns {Promise<{ union: string[], perSlug: Record<string, string[]> }>}
+ */
+export async function discoverAppliedCapabilities(appliedRecords, projectRoot) {
+  const perSlug = {};
+  const union = new Set();
+  for (const rec of appliedRecords ?? []) {
+    const caps = await readAppliedBlueprintCapabilities(rec, projectRoot);
+    perSlug[rec.slug] = caps;
+    for (const c of caps) union.add(c);
+  }
+  return { union: [...union].sort(), perSlug };
+}
+
+/**
+ * Build the refusal message for a requiresAppliedCapabilities gate.
+ * refusalMessageId maps to a known template; a message the loader
+ * accepts is used verbatim if the id is unknown (so a future
+ * blueprint can ship a bespoke refusal without a core code change).
+ *
+ * @param {object} args
+ * @param {string} args.slug        applying blueprint slug
+ * @param {string} args.refusalMessageId
+ * @param {string[]} args.requiredCapabilities
+ * @param {Array<{ slug: string, version: string }>} args.appliedRecords
+ * @param {string} args.allowSkipFlag  the CLI flag the operator can use to override
+ * @returns {string}
+ */
+export function buildRefusalMessage({ slug, refusalMessageId, requiredCapabilities, appliedRecords, allowSkipFlag }) {
+  // Applied blueprints list, one per line (indented 2 spaces per spec
+  // 5.5.1 formatting).
+  const appliedLines = (appliedRecords ?? [])
+    .map((r) => `  ${r.slug} v${r.version}`)
+    .join('\n');
+  const appliedBlock = appliedLines.length > 0 ? appliedLines : '  (none)';
+  if (refusalMessageId === 'application-admin-console-bare-spa') {
+    return [
+      `${slug} requires at least one applied security-auth-* blueprint,`,
+      `or an operator override with --${allowSkipFlag}.`,
+      '',
+      'Applied blueprints on this project:',
+      appliedBlock,
+      '',
+      'Suggested next steps:',
+      '  1. Apply an auth blueprint first:',
+      '       rcf define blueprint add security-auth-magic-link',
+      '     (or security-auth-clerk, security-auth-oauth2, security-auth-keycloak)',
+      `  2. Override for a scaffolding pass (surfaces will refuse at apply until an`,
+      `     auth blueprint is applied):`,
+      `       rcf define blueprint add ${slug} --${allowSkipFlag}`,
+    ].join('\n');
+  }
+  if (refusalMessageId === 'application-account-settings-bare-spa') {
+    return [
+      `${slug} requires at least one applied security-auth-* blueprint,`,
+      `or an operator override with --${allowSkipFlag}.`,
+      '',
+      'Applied blueprints on this project:',
+      appliedBlock,
+      '',
+      'Suggested next steps:',
+      '  1. Apply an auth blueprint first:',
+      '       rcf define blueprint add security-auth-magic-link',
+      '     (or security-auth-clerk, security-auth-oauth2, security-auth-keycloak)',
+      `  2. Override for a scaffolding pass (surfaces will refuse at apply until an`,
+      `     auth blueprint is applied):`,
+      `       rcf define blueprint add ${slug} --${allowSkipFlag}`,
+    ].join('\n');
+  }
+  if (refusalMessageId === 'object-storage-s3-no-secrets') {
+    return [
+      `[object-storage-s3-no-secrets] ${slug} requires an applied blueprint declaring`,
+      `at least one of: ${requiredCapabilities.join(', ')}.`,
+      `The shipped predecessor is security-secrets-management (v1.0.1+); the credential`,
+      `pair is a secretRef opaque string, never a value (infra round 5 spec 5.2, Baz`,
+      `decision 6).`,
+      '',
+      'Applied blueprints on this project:',
+      appliedBlock,
+      '',
+      'Suggested next steps:',
+      '  1. Apply security-secrets-management first:',
+      '       rcf define blueprint add security-secrets-management',
+      `  2. Or override for a scaffolding pass (records a note on source.notes so`,
+      `     later validation flags the surface as not-yet-activated):`,
+      `       rcf define blueprint add ${slug} --${allowSkipFlag}`,
+    ].join('\n');
+  }
+  // Generic fallback. Names the required capabilities and applied set;
+  // the operator has enough to diagnose without a bespoke template. The
+  // refusalMessageId is echoed on the first line as a stable dashboard-
+  // friendly tag downstream lint / dashboards can bind to.
+  const tag = refusalMessageId ? `[${refusalMessageId}] ` : '';
+  return [
+    `${tag}${slug} requires an applied blueprint declaring at least one of:`,
+    `  ${requiredCapabilities.join(', ')}`,
+    `or an operator override with --${allowSkipFlag}.`,
+    '',
+    'Applied blueprints on this project:',
+    appliedBlock,
+  ].join('\n');
+}
+
+/**
+ * Run the elicitation phase. Reads a bag of operator-supplied answers
+ * (`--answer <id>=<value>` merged with `--answers <file>` in the CLI),
+ * evaluates each elicit's `when` predicate against the discovered
+ * capability set, coerces the answer per kind, and returns a
+ * `{id: value}` map. A missing required answer for an elicit whose
+ * predicate fires refuses with a validation rcfError.
+ *
+ * @param {object} args
+ * @param {Array<object>} args.elicits         from loader
+ * @param {string[]} args.appliedCapabilities  discovered union
+ * @param {Record<string, string|boolean>} args.answers  operator bag
+ * @returns {{value: Record<string, string|boolean|null>} | import('../core/errors/index.js').RcfError}
+ */
+export function runElicitationPhase({ elicits, appliedCapabilities, answers }) {
+  if (!Array.isArray(elicits) || elicits.length === 0) {
+    return { value: {} };
+  }
+  const capSet = new Set(appliedCapabilities ?? []);
+  const bag = answers ?? {};
+  const out = {};
+  for (const e of elicits) {
+    const gated = e.when ? Array.isArray(e.when.requiresCapability) && !e.when.requiresCapability.some((c) => capSet.has(c)) : false;
+    if (gated) continue;
+    const raw = bag[e.id];
+    let coerced;
+    if (raw === undefined || raw === null || raw === '') {
+      if (e.default === undefined) {
+        return rcfError({
+          kind: 'validation',
+          message: `blueprint apply: elicit '${e.id}' is required (no default declared) and no answer was supplied. Pass --answer ${e.id}=<value> or --answers <file>.`,
+        });
+      }
+      coerced = e.default;
+    } else if (e.kind === 'boolean') {
+      if (typeof raw === 'boolean') coerced = raw;
+      else {
+        const s = String(raw).trim().toLowerCase();
+        if (s === 'y' || s === 'yes' || s === 'true' || s === '1') coerced = true;
+        else if (s === 'n' || s === 'no' || s === 'false' || s === '0') coerced = false;
+        else return rcfError({ kind: 'validation', message: `blueprint apply: elicit '${e.id}' expects a boolean; got '${raw}'.` });
+      }
+    } else if (e.kind === 'enum') {
+      const s = String(raw).trim();
+      if (!e.options.includes(s)) {
+        return rcfError({ kind: 'validation', message: `blueprint apply: elicit '${e.id}' expects one of [${e.options.join(', ')}]; got '${raw}'.` });
+      }
+      coerced = s;
+    } else {
+      coerced = String(raw).trim();
+    }
+    out[e.id] = coerced;
+  }
+  return { value: out };
+}
+
+/**
+ * Sidecar path for a blueprint's per-project apply-state (relative to
+ * the project root). One file per applied blueprint slug.
+ */
+export function sidecarRelPath(slug) {
+  return join('rcf', 'blueprints', `${slug}.applied.json`);
+}
+
+/**
+ * Write the sidecar. Overwrites the file so re-apply on the same
+ * version is idempotent.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {string} args.slug
+ * @param {string} args.version
+ * @param {string} args.appliedAt
+ * @param {string[]} args.appliedCapabilities
+ * @param {Record<string, string|boolean|null>} args.appliedElicitations
+ * @param {boolean} [args.allowNoAuthYet]
+ * @param {string} [args.notes]
+ */
+export async function writeSidecar({ projectRoot, slug, version, appliedAt, appliedCapabilities, appliedElicitations, allowNoAuthYet, notes }) {
+  const rel = sidecarRelPath(slug);
+  const abs = join(projectRoot, rel);
+  await mkdir(dirname(abs), { recursive: true });
+  const payload = { slug, version, appliedAt, appliedCapabilities: [...appliedCapabilities].sort(), appliedElicitations };
+  if (allowNoAuthYet === true) payload.allowNoAuthYet = true;
+  if (typeof notes === 'string' && notes.length > 0) payload.notes = notes;
+  await writeFile(abs, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+  return rel;
+}
+
+/**
+ * Read the sidecar. Missing file returns null (never throws).
+ */
+export async function readSidecar(projectRoot, slug) {
+  const abs = join(projectRoot, sidecarRelPath(slug));
+  try {
+    const raw = await readFile(abs, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Presence check for the sidecar file (does not parse).
+ */
+export async function sidecarExists(projectRoot, slug) {
+  try {
+    await stat(join(projectRoot, sidecarRelPath(slug)));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Custom-auth capability elicitation (visual round T-5 spec 5.5
+ * "Risks": custom auth elicits per capability). Runs BEFORE the
+ * requiresAppliedCapabilities refusal gate. Each elicit entry with
+ * a truthy `providesCapability` string is a boolean prompt asking
+ * whether the operator's own (non-shelf) auth blueprint provides
+ * the named capability. A truthy answer folds that capability into
+ * the effective applied set, so a project with no shelf auth
+ * blueprint can still pass the refusal gate without the allowNoAuthYet
+ * override, and the resulting sidecar records the operator-declared
+ * appliedCapabilities honestly.
+ *
+ * Interactive vs non-interactive:
+ *   - Non-interactive: only the elicits whose id appears in `answers`
+ *     resolve; the rest are treated as unanswered.
+ *   - Interactive (tty=true): unanswered custom-auth elicits are read
+ *     from stdin via readline with a `y/N` prompt; this branch is
+ *     driven synchronously by the CLI's `apply` wrapper when it
+ *     detects `process.stdin.isTTY === true`.
+ *
+ * A malformed boolean answer refuses with a validation rcfError.
+ *
+ * @param {object} args
+ * @param {Array<object>} args.elicits             from loader (may include non-providesCapability entries; they are ignored here)
+ * @param {Record<string, string|boolean>} args.answers  operator bag
+ * @param {(prompt: string) => Promise<string>} [args.readLine]  test seam for interactive input
+ * @returns {Promise<{ capsProvided: string[], answered: Record<string, boolean>, elicitsPresent: boolean, anyAnswered: boolean } | import('../core/errors/index.js').RcfError>}
+ */
+export async function runCustomAuthCapabilityElicits({ elicits, answers, readLine }) {
+  const capsProvided = new Set();
+  const answered = {};
+  let elicitsPresent = false;
+  const bag = answers ?? {};
+  for (const e of elicits ?? []) {
+    if (typeof e.providesCapability !== 'string' || e.providesCapability.length === 0) continue;
+    elicitsPresent = true;
+    const raw = bag[e.id];
+    let coerced;
+    if (raw === undefined || raw === null || raw === '') {
+      if (typeof readLine !== 'function') {
+        // Non-interactive branch, no answer supplied: skip. Default
+        // remains false in that case so a missing operator answer does
+        // not silently declare a capability.
+        continue;
+      }
+      const reply = await readLine(`Custom auth: does your auth provide '${e.providesCapability}'? [y/N]: `);
+      const s = String(reply ?? '').trim().toLowerCase();
+      if (s === '' || s === 'n' || s === 'no' || s === 'false' || s === '0') coerced = false;
+      else if (s === 'y' || s === 'yes' || s === 'true' || s === '1') coerced = true;
+      else {
+        return rcfError({
+          kind: 'validation',
+          message: `blueprint apply: elicit '${e.id}' expects a boolean; got '${reply}'.`,
+        });
+      }
+    } else if (typeof raw === 'boolean') {
+      coerced = raw;
+    } else {
+      const s = String(raw).trim().toLowerCase();
+      if (s === 'y' || s === 'yes' || s === 'true' || s === '1') coerced = true;
+      else if (s === 'n' || s === 'no' || s === 'false' || s === '0') coerced = false;
+      else {
+        return rcfError({
+          kind: 'validation',
+          message: `blueprint apply: elicit '${e.id}' expects a boolean; got '${raw}'.`,
+        });
+      }
+    }
+    answered[e.id] = coerced;
+    if (coerced === true) capsProvided.add(e.providesCapability);
+  }
+  return {
+    capsProvided: [...capsProvided].sort(),
+    answered,
+    elicitsPresent,
+    anyAnswered: Object.keys(answered).length > 0,
+  };
+}

package/src/blueprint/loader.js

@@ -151,10 +151,55 @@ export async function loadBlueprint(source) {
     ...(Array.isArray(doc.standardsTrace)
       ? { standardsTrace: doc.standardsTrace.map((s) => ({ id: s.id, version: s.version })) }
       : {}),
+    // Capability-declaration mechanism (visual round T-5 spec section
+    // 5.5.2). Blueprints declare identity or platform capabilities they
+    // provide (principalDirectory, roleModel, tenancy, auditLog); the
+    // vocabulary lives in the section 6a table in blueprint-authoring.md
+    // and the shape validation lives in this loader. Consumer blueprints
+    // gate surfaces on the union of currently-applied blueprints'
+    // capabilities via the apply-time source read-back (see apply.js).
+    ...(Array.isArray(doc.capabilities) ? { capabilities: doc.capabilities.slice() } : {}),
+    // Elicitation phase (visual round T-5 spec section 5.5, T-2 gate
+    // note d-2026-09-04-051). ADR-elicited fields on contributions are
+    // declarative only; a blueprint that needs apply-time answers
+    // declares them on this top-level list. Each entry has an id
+    // (kebab), a prompt (operator-facing), a kind (enum|string|boolean)
+    // with default and options, and an optional `when` predicate whose
+    // capability list gates whether the elicit fires.
+    ...(Array.isArray(doc.elicits) ? { elicits: doc.elicits.map((e) => normaliseElicit(e)) } : {}),
+    // Refusal gate (visual round T-5 spec section 5.5.1). A blueprint
+    // that requires at least one applied blueprint declaring a listed
+    // capability refuses at apply unless the CLI passes the named skip
+    // flag; the message and shape are validated on load, evaluated on
+    // apply.
+    ...(doc.requiresAppliedCapabilities !== undefined
+      ? {
+          requiresAppliedCapabilities: {
+            capabilities: doc.requiresAppliedCapabilities.capabilities.slice(),
+            allowSkipFlag: doc.requiresAppliedCapabilities.allowSkipFlag,
+            refusalMessageId: doc.requiresAppliedCapabilities.refusalMessageId,
+          },
+        }
+      : {}),
     contributions: Array.isArray(doc.contributions) ? doc.contributions.map(preserveAdrDisciplineFields) : [],
   };
 }
 
+// Shape-preserve an elicit entry. The loader's validator has already
+// vetted every field; this copy strips extra keys and freezes shape.
+function normaliseElicit(entry) {
+  const out = { id: entry.id, prompt: entry.prompt, kind: entry.kind };
+  if (entry.default !== undefined) out.default = entry.default;
+  if (Array.isArray(entry.options)) out.options = entry.options.slice();
+  if (entry.when !== undefined) {
+    out.when = { requiresCapability: entry.when.requiresCapability };
+  }
+  if (typeof entry.providesCapability === 'string') {
+    out.providesCapability = entry.providesCapability;
+  }
+  return out;
+}
+
 // Copy the standards-derived-discipline ADR fields (recommendedDefault,
 // elicited, standardsTraceClause) onto the returned contribution shape
 // verbatim so consumers (apply, tests, tooling) can read them without
@@ -276,6 +321,208 @@ function validateMetadata(doc, metaPath) {
   // severity to kind (per amendment A2); the discipline is prose.
   const stError = validateStandardsTrace(doc, metaPath);
   if (stError) return stError;
+  // Capability-declaration mechanism (visual round T-5, spec 5.5.2).
+  const capError = validateCapabilities(doc, metaPath);
+  if (capError) return capError;
+  const elicitError = validateElicits(doc, metaPath);
+  if (elicitError) return elicitError;
+  const requiresError = validateRequiresAppliedCapabilities(doc, metaPath);
+  if (requiresError) return requiresError;
+  return null;
+}
+
+// The kebab-slug grammar the elicit id uses (matches blueprint slug
+// and category shapes). Elicit ids must be slugs so the CLI's
+// --answer <id>=<value> flag has an unambiguous key vocabulary.
+const KEBAB_SLUG_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+
+// Set of legal elicit kinds. `enum` requires options[]; `string` and
+// `boolean` do not.
+const ELICIT_KINDS = new Set(['enum', 'string', 'boolean']);
+
+/**
+ * Validate capabilities[] shape (visual round T-5 spec 5.5.2). Optional;
+ * when present must be a non-empty array of lower camelCase strings on
+ * ^[a-z][a-zA-Z0-9]*$, matching the section 6a role convention.
+ */
+function validateCapabilities(doc, metaPath) {
+  if (doc.capabilities === undefined) return null;
+  if (!Array.isArray(doc.capabilities) || doc.capabilities.length === 0) {
+    return rcfError({ kind: 'validation', message: 'blueprint.json: capabilities must be a non-empty array when set', filePath: metaPath });
+  }
+  for (let i = 0; i < doc.capabilities.length; i += 1) {
+    const cap = doc.capabilities[i];
+    if (typeof cap !== 'string' || !ROLE_NAME_RE.test(cap)) {
+      return rcfError({
+        kind: 'validation',
+        message: `blueprint.json: capabilities[${i}] '${cap}' is not lower camelCase (^[a-z][a-zA-Z0-9]*$).`,
+        filePath: metaPath,
+      });
+    }
+  }
+  return null;
+}
+
+/**
+ * Validate elicits[] shape (visual round T-5 spec 5.5). Optional; when
+ * present must be a non-empty array of entries carrying id (kebab
+ * slug), prompt (non-empty string, no em-dashes, no emojis), kind
+ * (enum|string|boolean), an optional default matching the kind, an
+ * options[] array when kind is enum, and an optional when-predicate
+ * whose requiresCapability[] is a non-empty array of camelCase
+ * capability strings.
+ */
+function validateElicits(doc, metaPath) {
+  if (doc.elicits === undefined) return null;
+  if (!Array.isArray(doc.elicits) || doc.elicits.length === 0) {
+    return rcfError({ kind: 'validation', message: 'blueprint.json: elicits must be a non-empty array when set', filePath: metaPath });
+  }
+  const seenIds = new Set();
+  for (let i = 0; i < doc.elicits.length; i += 1) {
+    const entry = doc.elicits[i];
+    if (typeof entry !== 'object' || entry === null) {
+      return rcfError({ kind: 'validation', message: `blueprint.json: elicits[${i}] must be an object`, filePath: metaPath });
+    }
+    if (typeof entry.id !== 'string' || !KEBAB_SLUG_RE.test(entry.id)) {
+      return rcfError({
+        kind: 'validation',
+        message: `blueprint.json: elicits[${i}].id '${entry.id}' is not a kebab slug (^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$).`,
+        filePath: metaPath,
+      });
+    }
+    if (seenIds.has(entry.id)) {
+      return rcfError({ kind: 'validation', message: `blueprint.json: elicits[${i}].id '${entry.id}' duplicates an earlier entry`, filePath: metaPath });
+    }
+    seenIds.add(entry.id);
+    if (typeof entry.prompt !== 'string' || entry.prompt.trim().length === 0) {
+      return rcfError({ kind: 'validation', message: `blueprint.json: elicits[${i}] '${entry.id}' prompt must be a non-empty string`, filePath: metaPath });
+    }
+    if (EM_DASH.test(entry.prompt)) {
+      return rcfError({ kind: 'validation', message: `blueprint.json: elicits[${i}] '${entry.id}' prompt contains an em-dash; use a comma, a full stop, or a colon.`, filePath: metaPath });
+    }
+    if (EMOJI_RE.test(entry.prompt)) {
+      return rcfError({ kind: 'validation', message: `blueprint.json: elicits[${i}] '${entry.id}' prompt contains an emoji; operator-facing prose must be plain text.`, filePath: metaPath });
+    }
+    if (!ELICIT_KINDS.has(entry.kind)) {
+      return rcfError({
+        kind: 'validation',
+        message: `blueprint.json: elicits[${i}] '${entry.id}' kind '${entry.kind}' must be one of: ${[...ELICIT_KINDS].join(', ')}.`,
+        filePath: metaPath,
+      });
+    }
+    if (entry.kind === 'enum') {
+      if (!Array.isArray(entry.options) || entry.options.length === 0) {
+        return rcfError({ kind: 'validation', message: `blueprint.json: elicits[${i}] '${entry.id}' kind=enum requires a non-empty options[] array`, filePath: metaPath });
+      }
+      for (let j = 0; j < entry.options.length; j += 1) {
+        if (typeof entry.options[j] !== 'string' || entry.options[j].length === 0) {
+          return rcfError({ kind: 'validation', message: `blueprint.json: elicits[${i}] '${entry.id}' options[${j}] must be a non-empty string`, filePath: metaPath });
+        }
+      }
+      if (entry.default !== undefined && !entry.options.includes(entry.default)) {
+        return rcfError({ kind: 'validation', message: `blueprint.json: elicits[${i}] '${entry.id}' default '${entry.default}' is not in options[]`, filePath: metaPath });
+      }
+    } else if (entry.kind === 'boolean') {
+      if (entry.default !== undefined && typeof entry.default !== 'boolean') {
+        return rcfError({ kind: 'validation', message: `blueprint.json: elicits[${i}] '${entry.id}' kind=boolean default must be a boolean`, filePath: metaPath });
+      }
+    } else if (entry.kind === 'string') {
+      if (entry.default !== undefined && typeof entry.default !== 'string') {
+        return rcfError({ kind: 'validation', message: `blueprint.json: elicits[${i}] '${entry.id}' kind=string default must be a string`, filePath: metaPath });
+      }
+    }
+    if (entry.when !== undefined) {
+      if (typeof entry.when !== 'object' || entry.when === null) {
+        return rcfError({ kind: 'validation', message: `blueprint.json: elicits[${i}] '${entry.id}' when must be an object`, filePath: metaPath });
+      }
+      if (!Array.isArray(entry.when.requiresCapability) || entry.when.requiresCapability.length === 0) {
+        return rcfError({ kind: 'validation', message: `blueprint.json: elicits[${i}] '${entry.id}' when.requiresCapability must be a non-empty array`, filePath: metaPath });
+      }
+      for (let j = 0; j < entry.when.requiresCapability.length; j += 1) {
+        const cap = entry.when.requiresCapability[j];
+        if (typeof cap !== 'string' || !ROLE_NAME_RE.test(cap)) {
+          return rcfError({
+            kind: 'validation',
+            message: `blueprint.json: elicits[${i}] '${entry.id}' when.requiresCapability[${j}] '${cap}' is not lower camelCase.`,
+            filePath: metaPath,
+          });
+        }
+      }
+    }
+    // Custom-auth capability discovery (visual round T-5 spec 5.5
+    // "Risks"). An elicit that declares providesCapability is a
+    // boolean prompt asking the operator whether their custom auth
+    // provides the named capability; a truthy answer folds the
+    // capability into the effective applied set at apply time, so a
+    // project with no shelf auth blueprint can still satisfy a
+    // consumer blueprint's requiresAppliedCapabilities gate without
+    // the allowNoAuthYet override. Rules: kind MUST be boolean,
+    // when MUST be absent (custom-auth elicits fire pre-refusal,
+    // before any discovered-capability set exists), and the value
+    // MUST be lower camelCase (same grammar as capabilities[]).
+    if (entry.providesCapability !== undefined) {
+      if (entry.kind !== 'boolean') {
+        return rcfError({
+          kind: 'validation',
+          message: `blueprint.json: elicits[${i}] '${entry.id}' providesCapability requires kind=boolean (got '${entry.kind}').`,
+          filePath: metaPath,
+        });
+      }
+      if (entry.when !== undefined) {
+        return rcfError({
+          kind: 'validation',
+          message: `blueprint.json: elicits[${i}] '${entry.id}' providesCapability is incompatible with when (custom-auth elicits fire pre-refusal, before applied capabilities are discovered).`,
+          filePath: metaPath,
+        });
+      }
+      if (typeof entry.providesCapability !== 'string' || !ROLE_NAME_RE.test(entry.providesCapability)) {
+        return rcfError({
+          kind: 'validation',
+          message: `blueprint.json: elicits[${i}] '${entry.id}' providesCapability '${entry.providesCapability}' is not lower camelCase (^[a-z][a-zA-Z0-9]*$).`,
+          filePath: metaPath,
+        });
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Validate requiresAppliedCapabilities shape (visual round T-5 spec
+ * 5.5.1). Optional; when present must be an object with capabilities
+ * (non-empty array of lower camelCase strings), allowSkipFlag (kebab
+ * slug matching a CLI flag name), and refusalMessageId (non-empty
+ * string; the apply verb maps it to a message template).
+ */
+function validateRequiresAppliedCapabilities(doc, metaPath) {
+  if (doc.requiresAppliedCapabilities === undefined) return null;
+  const r = doc.requiresAppliedCapabilities;
+  if (typeof r !== 'object' || r === null) {
+    return rcfError({ kind: 'validation', message: 'blueprint.json: requiresAppliedCapabilities must be an object', filePath: metaPath });
+  }
+  if (!Array.isArray(r.capabilities) || r.capabilities.length === 0) {
+    return rcfError({ kind: 'validation', message: 'blueprint.json: requiresAppliedCapabilities.capabilities must be a non-empty array', filePath: metaPath });
+  }
+  for (let i = 0; i < r.capabilities.length; i += 1) {
+    const cap = r.capabilities[i];
+    if (typeof cap !== 'string' || !ROLE_NAME_RE.test(cap)) {
+      return rcfError({
+        kind: 'validation',
+        message: `blueprint.json: requiresAppliedCapabilities.capabilities[${i}] '${cap}' is not lower camelCase.`,
+        filePath: metaPath,
+      });
+    }
+  }
+  if (typeof r.allowSkipFlag !== 'string' || !KEBAB_SLUG_RE.test(r.allowSkipFlag)) {
+    return rcfError({
+      kind: 'validation',
+      message: `blueprint.json: requiresAppliedCapabilities.allowSkipFlag '${r.allowSkipFlag}' is not a kebab slug (matches a CLI flag name).`,
+      filePath: metaPath,
+    });
+  }
+  if (typeof r.refusalMessageId !== 'string' || r.refusalMessageId.trim().length === 0) {
+    return rcfError({ kind: 'validation', message: 'blueprint.json: requiresAppliedCapabilities.refusalMessageId must be a non-empty string', filePath: metaPath });
+  }
   return null;
 }