rcf-lite 0.18.0 → 0.19.0

package/src/blueprint/loader.js

@@ -26,6 +26,24 @@ const CONTRIBUTABLE_KINDS = new Set(['req', 'us', 'tac', 'adr', 'ts', 'cn']);
 const ROOT_SINGLETON_KINDS = new Set(['prd', 'tad', 'bs']);
 const EXCLUDED_KINDS = new Set(['fbs']);
 
+// Role name grammar for providesRoles[] and suggestedCompanions[].role.
+// Lower camelCase: starts with a lowercase letter, contains only letters
+// and digits, no separators. Same shape as global-topic strings by
+// design (a role name IS the topic name the paired ADR claims, per
+// core-companions spec section 2.2), so `providesRoles: ["logging"]`
+// and the ADR contribution `{"scope":"global","topic":"logging"}`
+// co-locate the two facts on one string.
+const ROLE_NAME_RE = /^[a-z][a-zA-Z0-9]*$/;
+
+// Em-dash sentinel + emoji-ish detection for the suggestedCompanions
+// reason string, per the estate-wide banned-tells baseline. Em-dash
+// (U+2014) is refused outright; emojis approximated by a broad
+// symbols / pictographs range. Reason is operator-facing prose, so the
+// same discipline that applies to READMEs and guides applies here.
+// Refused shapes surface as a validation rcfError before apply.
+const EM_DASH = /—/;
+const EMOJI_RE = /[\u{1F300}-\u{1FAFF}\u{2600}-\u{27BF}\u{1F000}-\u{1F2FF}]/u;
+
 /**
  * @typedef {object} BlueprintContribution
  * @property {string} id           canonical id (bare or already namespaced)
@@ -33,6 +51,32 @@ const EXCLUDED_KINDS = new Set(['fbs']);
  * @property {string} path         relative to the blueprint's contributions/
  * @property {'global'} [scope]    ADR only; marks whole-project decisions
  * @property {string}   [topic]    ADR only when scope=global; conflict key
+ * @property {boolean}  [recommendedDefault] ADR only. Standards-derived
+ *                                  discipline (spec 3.2): marks a SHOULD
+ *                                  clause, or a choice-shaped MUST per
+ *                                  amendment A2 (Baz 2026-09-04T12:20:31Z).
+ * @property {boolean}  [elicited] ADR only. Marks a MAY clause: the
+ *                                  applying operator supplies the value
+ *                                  at apply.
+ * @property {string}   [standardsTraceClause] ADR only. Standard clause
+ *                                  identifier verbatim (`WSD-001 clause 3.1`,
+ *                                  `RFC 7807 section 3.1`) or the sentinel
+ *                                  `"generic enterprise practice"`. Required
+ *                                  on every ADR contribution when the
+ *                                  blueprint declares standardsTrace[].
+ */
+
+/**
+ * @typedef {object} SuggestedCompanion
+ * @property {string} role     lower camelCase role name
+ * @property {string} reason   one-sentence operator-facing reason string
+ *                             (no em-dashes, no emojis)
+ */
+
+/**
+ * @typedef {object} StandardsTraceEntry
+ * @property {string} id       standard identifier (e.g. `WSD-001`)
+ * @property {string} version  standard version (free-form)
  */
 
 /**
@@ -51,6 +95,12 @@ const EXCLUDED_KINDS = new Set(['fbs']);
  *                                  vocabulary, so a new category can be
  *                                  minted by adding it to the standard
  *                                  without a code change.
+ * @property {string[]} [providesRoles]        core-companions spec 2.1
+ * @property {SuggestedCompanion[]} [suggestedCompanions] core-companions spec 2.1
+ * @property {StandardsTraceEntry[]} [standardsTrace] standards-derived
+ *                                  discipline (spec 3.2). When set, every
+ *                                  ADR contribution MUST carry a non-null
+ *                                  standardsTraceClause.
  * @property {BlueprintContribution[]} contributions
  */
 
@@ -94,10 +144,33 @@ export async function loadBlueprint(source) {
     version: doc.version,
     source: root,
     ...(typeof doc.category === 'string' ? { category: doc.category } : {}),
-    contributions: Array.isArray(doc.contributions) ? doc.contributions : [],
+    ...(Array.isArray(doc.providesRoles) ? { providesRoles: doc.providesRoles.slice() } : {}),
+    ...(Array.isArray(doc.suggestedCompanions)
+      ? { suggestedCompanions: doc.suggestedCompanions.map((s) => ({ role: s.role, reason: s.reason })) }
+      : {}),
+    ...(Array.isArray(doc.standardsTrace)
+      ? { standardsTrace: doc.standardsTrace.map((s) => ({ id: s.id, version: s.version })) }
+      : {}),
+    contributions: Array.isArray(doc.contributions) ? doc.contributions.map(preserveAdrDisciplineFields) : [],
   };
 }
 
+// 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
+// re-loading the blueprint.json. Non-ADR contributions ignore these
+// fields; the loader does not enforce a kind gate on them because a
+// blueprint author can meaningfully attach recommendedDefault to any
+// ADR-flavoured contribution (the discipline is prose in section 8a,
+// not code, per amendment A2).
+function preserveAdrDisciplineFields(c) {
+  const out = { ...c };
+  if (out.recommendedDefault !== undefined) out.recommendedDefault = c.recommendedDefault === true;
+  if (out.elicited !== undefined) out.elicited = c.elicited === true;
+  if (typeof c.standardsTraceClause === 'string') out.standardsTraceClause = c.standardsTraceClause;
+  return out;
+}
+
 function validateMetadata(doc, metaPath) {
   if (typeof doc !== 'object' || doc === null) {
     return rcfError({ kind: 'validation', message: 'blueprint.json must be a JSON object', filePath: metaPath });
@@ -169,6 +242,175 @@ function validateMetadata(doc, metaPath) {
     if (c.scope === 'global' && typeof c.topic !== 'string') {
       return rcfError({ kind: 'validation', message: `blueprint.json: scope=global contribution ${c.id} requires a topic`, filePath: metaPath });
     }
+    // Standards-derived discipline (spec 3.2) per-ADR fields. Shape
+    // gates only; whether a MUST clause landed on an AC vs an ADR is
+    // prose in blueprint-authoring.md section 8a, not code (amendment
+    // A2 Baz 2026-09-04T12:20:31Z).
+    if (c.recommendedDefault !== undefined && typeof c.recommendedDefault !== 'boolean') {
+      return rcfError({ kind: 'validation', message: `blueprint.json: contribution ${c.id} recommendedDefault must be a boolean when set`, filePath: metaPath });
+    }
+    if (c.elicited !== undefined && typeof c.elicited !== 'boolean') {
+      return rcfError({ kind: 'validation', message: `blueprint.json: contribution ${c.id} elicited must be a boolean when set`, filePath: metaPath });
+    }
+    if (c.standardsTraceClause !== undefined) {
+      if (typeof c.standardsTraceClause !== 'string' || c.standardsTraceClause.trim().length === 0) {
+        return rcfError({ kind: 'validation', message: `blueprint.json: contribution ${c.id} standardsTraceClause must be a non-empty string when set`, filePath: metaPath });
+      }
+    }
+  }
+  // Companion-suggestion mechanism fields (core-companions spec 2.1).
+  const rolesError = validateProvidesRoles(doc, metaPath);
+  if (rolesError) return rolesError;
+  const suggestedError = validateSuggestedCompanions(doc, metaPath);
+  if (suggestedError) return suggestedError;
+  // Paired-ADR gate (spec 2.1): a blueprint declaring a role in
+  // providesRoles[] MUST carry a scope:global ADR whose topic string
+  // equals the role name. Enforced after per-contribution validation
+  // so a mis-authored contribution fails first with the more specific
+  // shape error.
+  const pairedError = validateProvidesRolesPairedAdrs(doc, metaPath);
+  if (pairedError) return pairedError;
+  // Standards-derived discipline (spec 3.3): if standardsTrace[] is
+  // set, every ADR contribution MUST carry a non-null
+  // standardsTraceClause. The loader does NOT cross-check clause
+  // severity to kind (per amendment A2); the discipline is prose.
+  const stError = validateStandardsTrace(doc, metaPath);
+  if (stError) return stError;
+  return null;
+}
+
+/**
+ * Validate providesRoles[] shape (spec 2.1). Optional; when present
+ * must be a non-empty array of lower camelCase strings on the pattern
+ * ^[a-z][a-zA-Z0-9]*$.
+ */
+function validateProvidesRoles(doc, metaPath) {
+  if (doc.providesRoles === undefined) return null;
+  if (!Array.isArray(doc.providesRoles) || doc.providesRoles.length === 0) {
+    return rcfError({ kind: 'validation', message: 'blueprint.json: providesRoles must be a non-empty array when set', filePath: metaPath });
+  }
+  for (let i = 0; i < doc.providesRoles.length; i += 1) {
+    const role = doc.providesRoles[i];
+    if (typeof role !== 'string' || !ROLE_NAME_RE.test(role)) {
+      return rcfError({
+        kind: 'validation',
+        message: `blueprint.json: providesRoles[${i}] '${role}' is not lower camelCase (^[a-z][a-zA-Z0-9]*$).`,
+        filePath: metaPath,
+      });
+    }
+  }
+  return null;
+}
+
+/**
+ * Validate suggestedCompanions[] shape (spec 2.1). Optional; when
+ * present must be a non-empty array of `{role, reason}` objects; role
+ * is a lower camelCase string; reason is a non-empty string with no
+ * em-dashes and no emojis (banned-tells baseline applies to operator-
+ * facing prose).
+ */
+function validateSuggestedCompanions(doc, metaPath) {
+  if (doc.suggestedCompanions === undefined) return null;
+  if (!Array.isArray(doc.suggestedCompanions) || doc.suggestedCompanions.length === 0) {
+    return rcfError({ kind: 'validation', message: 'blueprint.json: suggestedCompanions must be a non-empty array when set', filePath: metaPath });
+  }
+  for (let i = 0; i < doc.suggestedCompanions.length; i += 1) {
+    const entry = doc.suggestedCompanions[i];
+    if (typeof entry !== 'object' || entry === null) {
+      return rcfError({ kind: 'validation', message: `blueprint.json: suggestedCompanions[${i}] must be an object with role and reason`, filePath: metaPath });
+    }
+    if (typeof entry.role !== 'string' || !ROLE_NAME_RE.test(entry.role)) {
+      return rcfError({
+        kind: 'validation',
+        message: `blueprint.json: suggestedCompanions[${i}].role '${entry.role}' is not lower camelCase (^[a-z][a-zA-Z0-9]*$).`,
+        filePath: metaPath,
+      });
+    }
+    if (typeof entry.reason !== 'string' || entry.reason.trim().length === 0) {
+      return rcfError({
+        kind: 'validation',
+        message: `blueprint.json: suggestedCompanions[${i}].reason for role '${entry.role}' must be a non-empty string.`,
+        filePath: metaPath,
+      });
+    }
+    if (EM_DASH.test(entry.reason)) {
+      return rcfError({
+        kind: 'validation',
+        message: `blueprint.json: suggestedCompanions[${i}].reason for role '${entry.role}' contains an em-dash; use a comma, a full stop, or a colon.`,
+        filePath: metaPath,
+      });
+    }
+    if (EMOJI_RE.test(entry.reason)) {
+      return rcfError({
+        kind: 'validation',
+        message: `blueprint.json: suggestedCompanions[${i}].reason for role '${entry.role}' contains an emoji; operator-facing prose must be plain text.`,
+        filePath: metaPath,
+      });
+    }
+  }
+  return null;
+}
+
+/**
+ * Paired-ADR gate for providesRoles (spec 2.1). A blueprint that
+ * declares a role MUST also carry a scope:global ADR whose topic
+ * string equals the role name. The check runs after per-contribution
+ * shape validation so the more specific per-contribution message
+ * fires first on a mis-authored file.
+ */
+function validateProvidesRolesPairedAdrs(doc, metaPath) {
+  if (!Array.isArray(doc.providesRoles) || doc.providesRoles.length === 0) return null;
+  const globalTopics = new Set(
+    (doc.contributions ?? [])
+      .filter((c) => c.kind === 'adr' && c.scope === 'global' && typeof c.topic === 'string')
+      .map((c) => c.topic),
+  );
+  for (const role of doc.providesRoles) {
+    if (!globalTopics.has(role)) {
+      return rcfError({
+        kind: 'validation',
+        message: `blueprint.json: providesRoles[] names '${role}' but no scope:global ADR carries topic '${role}'.`,
+        filePath: metaPath,
+      });
+    }
+  }
+  return null;
+}
+
+/**
+ * Standards-derived-discipline gate (spec 3.3). If standardsTrace[]
+ * is declared, every ADR contribution MUST carry a non-null
+ * standardsTraceClause. No cross-check on severity-to-kind mapping
+ * (amendment A2 Baz 2026-09-04T12:20:31Z): the discipline is prose in
+ * blueprint-authoring.md section 8a, not code.
+ */
+function validateStandardsTrace(doc, metaPath) {
+  if (doc.standardsTrace === undefined) return null;
+  if (!Array.isArray(doc.standardsTrace)) {
+    return rcfError({ kind: 'validation', message: 'blueprint.json: standardsTrace must be an array when set', filePath: metaPath });
+  }
+  for (let i = 0; i < doc.standardsTrace.length; i += 1) {
+    const entry = doc.standardsTrace[i];
+    if (typeof entry !== 'object' || entry === null) {
+      return rcfError({ kind: 'validation', message: `blueprint.json: standardsTrace[${i}] must be an object with id and version`, filePath: metaPath });
+    }
+    if (typeof entry.id !== 'string' || entry.id.trim().length === 0) {
+      return rcfError({ kind: 'validation', message: `blueprint.json: standardsTrace[${i}].id must be a non-empty string`, filePath: metaPath });
+    }
+    if (typeof entry.version !== 'string' || entry.version.trim().length === 0) {
+      return rcfError({ kind: 'validation', message: `blueprint.json: standardsTrace[${i}].version must be a non-empty string`, filePath: metaPath });
+    }
+  }
+  const slug = doc.slug;
+  for (const c of doc.contributions ?? []) {
+    if (c.kind !== 'adr') continue;
+    if (typeof c.standardsTraceClause !== 'string' || c.standardsTraceClause.trim().length === 0) {
+      return rcfError({
+        kind: 'validation',
+        message: `blueprint '${slug}' declares standardsTrace but ADR contribution '${c.id}' has no standardsTraceClause; every ADR must reference a standard clause or the sentinel 'generic enterprise practice'.`,
+        filePath: metaPath,
+      });
+    }
   }
   return null;
 }

package/src/cli/blueprint.js

@@ -19,11 +19,20 @@ import {
   enrichRowsWithCategories,
   groupRowsByCategory,
   listBlueprints,
+  loadBlueprint,
   removeBlueprint,
   removeResolution,
   renderDiff,
   resolveBlueprintSource,
   supersedeBlueprintTopic,
+  readCompanionsFile,
+  setCompanionPin,
+  unsetCompanionPin,
+  resolveCompanions,
+  renderCompanionLines,
+  renderAmbiguousLibraryRefusal,
+  enumerateShelfProviders,
+  enumerateLibraryProviders,
 } from '../blueprint/index.js';
 import { conflictReportJson, renderConflictReport } from '../blueprint/conflicts.js';
 import { handleLibraryVerb, LIBRARY_HELP } from './blueprint-library.js';
@@ -81,6 +90,26 @@ Verbs:
                          names an ADR present on the tree but is no
                          longer on any resolutions[] entry, prints
                          "nothing to remove" and exits 0.
+  companions <slug>      Print the resolved companion set for the
+                         named applied service blueprint. Reads its
+                         source blueprint.json's suggestedCompanions[],
+                         walks the deterministic tier ladder (applied
+                         > registered library > core shelf, with
+                         rcf/companions.json pin overriding library +
+                         shelf), and prints one line per role. Refuses
+                         exit 3 when two or more registered libraries
+                         provide the same role with no pin. \`--json\`
+                         emits a machine-readable envelope.
+  companions set <role> <slug>
+                         Write a project-level pin to rcf/companions.json
+                         under roles.<role>.provider. <slug> accepts
+                         \`<libraryPrefix>:<slug>\` for a library provider
+                         or a bare kebab slug for a shelf provider.
+                         Refuses exit 2 when the named provider does
+                         not declare providesRoles containing <role>.
+  companions unset <role>
+                         Remove a pin from rcf/companions.json. Refuses
+                         exit 2 when no pin exists for <role>.
   library <verb>         Manage external blueprint libraries. Sub-verbs:
                          add, list, remove, refresh. See
                          'rcf define blueprint library --help' for the
@@ -102,6 +131,21 @@ Options:
   --reason <text>        (supersede, add --resolve) Optional operator
                          note attached to the manifest.resolutions[]
                          record.
+  --companion <role>=<slug>
+                         (add only, repeatable) Pin a companion
+                         provider at apply time; writes the pin to
+                         rcf/companions.json (schemaVersion 1, current
+                         pin per role) with pinnedAt. <slug> is
+                         \`<libraryPrefix>:<slug>\` for a library
+                         provider or a bare kebab slug for a shelf
+                         provider. Refuses exit 2 when the named
+                         provider does not declare providesRoles
+                         containing <role>.
+  --no-companion-suggestions
+                         (add only) Suppress both the --companion pin
+                         phase and the post-apply resolved suggestion
+                         block; every other apply behaviour is
+                         unchanged.
   --json                 (add only) Emit the result (or conflict
                          report) as a machine-readable JSON object.
                          Exit code is unchanged (0 on apply, 3 on
@@ -137,6 +181,9 @@ const OPTION_SPEC = {
   'dry-run': { type: 'boolean' },
   quiet: { type: 'boolean' },
   help: { type: 'boolean' },
+  // Companion-suggestion mechanism (core-companions spec section 2).
+  companion: { type: 'string', multiple: true },
+  'no-companion-suggestions': { type: 'boolean' },
 };
 
 /**
@@ -220,6 +267,25 @@ export async function main(argv, deps = {}) {
       stderr.write(`[error] blueprint add: ${resolveDeclarations.error}\n`);
       return 2;
     }
+    // Pre-flight --companion selectors (core-companions spec section
+    // 5). Validate BEFORE the apply so a bad selector refuses without
+    // side effects (the pin write and the applied contributions both
+    // stay untouched). --no-companion-suggestions suppresses the
+    // pre-flight too.
+    const companionSelectorsPre = parseCompanionOptions(parsed.values.companion);
+    if (companionSelectorsPre.error) {
+      stderr.write(`[error] blueprint add: ${companionSelectorsPre.error}\n`);
+      return 2;
+    }
+    if (!parsed.values['no-companion-suggestions']) {
+      for (const sel of companionSelectorsPre.value) {
+        const providerCheck = await validateCompanionProvider({ selector: sel, projectRoot, tree });
+        if (providerCheck.error) {
+          stderr.write(`[error] blueprint add: ${providerCheck.error}\n`);
+          return 2;
+        }
+      }
+    }
     const result = await applyBlueprint({
       projectRoot, tree, source,
       namespaceOverride: parsed.values.namespace,
@@ -288,6 +354,57 @@ export async function main(argv, deps = {}) {
     if (!parsed.values.quiet) {
       stdout.write(`[blueprint] applied '${result.slug}' at ${result.version} (${result.contributions.length} contribution(s)).\n`);
     }
+    // Companion-suggestion mechanism (spec 2.6). Runs AFTER the apply
+    // writes so a failed apply never produces a suggestion block.
+    // Composed of two phases: (a) --companion selectors record pins to
+    // rcf/companions.json (spec 2.4); (b) print the resolved
+    // suggestion block using the current tree + pins + libraries + shelf.
+    // Both phases are suppressed by --no-companion-suggestions.
+    if (!parsed.values['no-companion-suggestions']) {
+      // Re-walk the tree so applied writes are visible to the resolver.
+      const { tree: postTree } = await walkTree({ projectRoot });
+      // Phase (a): --companion selectors. Pre-flight validated the
+      // shape and provider gate before the apply; here we only write
+      // the pins.
+      for (const sel of companionSelectorsPre.value) {
+        const pinRes = await setCompanionPin({ projectRoot, role: sel.role, provider: sel.provider, now });
+        if (pinRes.kind) {
+          stderr.write(`[error] blueprint add: ${pinRes.message}\n`);
+          return 2;
+        }
+        if (pinRes.previousProvider && pinRes.previousProvider !== sel.provider) {
+          stderr.write(`[blueprint] companion pin for role '${sel.role}' updated: '${pinRes.previousProvider}' -> '${sel.provider}'\n`);
+        }
+      }
+      // Phase (b): print the resolved suggestion block for the just-
+      // applied service blueprint. Skipped if the applied blueprint
+      // declared no suggestedCompanions[].
+      if (Array.isArray(result.suggestedCompanions) && result.suggestedCompanions.length > 0) {
+        const pins = await readCompanionsFile(projectRoot);
+        const pinsClean = pins && pins.kind ? null : pins;
+        const resolved = await resolveCompanions({
+          projectRoot,
+          tree: postTree,
+          suggestedCompanions: result.suggestedCompanions,
+          pins: pinsClean,
+        });
+        // Surface ambiguous refusal as a hard exit-3 (spec 2.4).
+        const ambiguous = resolved.find((r) => r.origin === 'ambiguousLibraries');
+        if (ambiguous) {
+          stderr.write(renderAmbiguousLibraryRefusal({
+            role: ambiguous.role,
+            providers: ambiguous.ambiguousProviders,
+            serviceSlug: result.slug,
+          }));
+          return 3;
+        }
+        if (!parsed.values.quiet) {
+          stdout.write(`\nSuggested companions this blueprint recommends alongside it:\n`);
+          stdout.write(`${renderCompanionLines(resolved)}\n`);
+          stdout.write(`Apply either with: rcf define blueprint add <slug>\n`);
+        }
+      }
+    }
     return 0;
   }
 
@@ -405,11 +522,203 @@ export async function main(argv, deps = {}) {
     return 0;
   }
 
+  if (verb === 'companions') {
+    return handleCompanionsVerb({
+      rest,
+      parsed,
+      projectRoot,
+      tree,
+      now,
+      stdout,
+      stderr,
+    });
+  }
+
   stderr.write(`[error] blueprint: unknown verb '${verb}'\n`);
   stderr.write(HELP);
   return 2;
 }
 
+/**
+ * Parse `--companion <role>=<providerSlug>` occurrences. Slug accepts
+ * either `<libraryPrefix>:<slug>` for a library-qualified provider or a
+ * bare kebab slug for a shelf provider. Returns { value: [{role,
+ * provider}] } on success or { error: string }.
+ */
+function parseCompanionOptions(rawList) {
+  if (!Array.isArray(rawList) || rawList.length === 0) return { value: [] };
+  const out = [];
+  for (const raw of rawList) {
+    if (typeof raw !== 'string' || raw.length === 0) {
+      return { error: `--companion expects <role>=<slug>, got '${raw}'` };
+    }
+    const eq = raw.indexOf('=');
+    if (eq === -1) {
+      return { error: `--companion expects <role>=<slug>, got '${raw}' (missing '=')` };
+    }
+    const role = raw.slice(0, eq);
+    const provider = raw.slice(eq + 1);
+    if (!/^[a-z][a-zA-Z0-9]*$/.test(role)) {
+      return { error: `--companion role '${role}' is not lower camelCase (^[a-z][a-zA-Z0-9]*$).` };
+    }
+    if (provider.length === 0) {
+      return { error: `--companion provider slug is empty for role '${role}'` };
+    }
+    out.push({ role, provider });
+  }
+  return { value: out };
+}
+
+/**
+ * Validate a --companion selector: locate the named provider blueprint
+ * (library-qualified or shelf), load it, and refuse when its
+ * `providesRoles[]` does not contain the requested role. Message shape
+ * per spec 5.
+ */
+async function validateCompanionProvider({ selector, projectRoot, tree }) {
+  const { role, provider } = selector;
+  // Applied?
+  const applied = (tree?.manifest?.blueprints ?? []).find((bp) => bp.slug === provider);
+  if (applied && typeof applied.source === 'string' && !applied.source.includes(':')) {
+    const bp = await loadBlueprint(applied.source);
+    if (bp.kind) return { error: `--companion ${role}=${provider}: source blueprint failed to load: ${bp.message}` };
+    if (Array.isArray(bp.providesRoles) && bp.providesRoles.includes(role)) return { ok: true };
+    return { error: `--companion ${role}=${provider}: blueprint '${provider}' does not declare providesRoles containing '${role}'.` };
+  }
+  // Library-qualified?
+  if (provider.includes(':')) {
+    const libraries = await enumerateLibraryProviders({ projectRoot, role });
+    if (libraries.some((l) => `${l.libraryPrefix}:${l.slug}` === provider)) return { ok: true };
+    // Additional diagnostic: check if the library exists but the blueprint does not declare the role
+    return { error: `--companion ${role}=${provider}: blueprint '${provider}' does not declare providesRoles containing '${role}'.` };
+  }
+  // Shelf?
+  const shelfProviders = await enumerateShelfProviders(role);
+  if (shelfProviders.includes(provider)) return { ok: true };
+  return { error: `--companion ${role}=${provider}: blueprint '${provider}' does not declare providesRoles containing '${role}'.` };
+}
+
+/**
+ * `rcf define blueprint companions <slug>|set|unset` sub-verb
+ * dispatcher (spec 2.5). Read-only against the blueprint tree; set /
+ * unset only touch rcf/companions.json.
+ */
+async function handleCompanionsVerb({ rest, parsed, projectRoot, tree, now, stdout, stderr }) {
+  const asJson = parsed.values.json === true;
+  const quiet = parsed.values.quiet === true;
+  if (rest.length === 0) {
+    stderr.write('[error] blueprint companions: missing <slug> or sub-verb (set|unset)\n');
+    return 2;
+  }
+  const head = rest[0];
+  // set / unset sub-verbs.
+  if (head === 'set') {
+    if (rest.length < 3) {
+      stderr.write('[error] blueprint companions set: expected <role> <slug>\n');
+      return 2;
+    }
+    const role = rest[1];
+    const provider = rest[2];
+    const validation = await validateCompanionProvider({ selector: { role, provider }, projectRoot, tree });
+    if (validation.error) {
+      stderr.write(`[error] blueprint companions set: ${validation.error}\n`);
+      return 2;
+    }
+    const res = await setCompanionPin({ projectRoot, role, provider, now });
+    if (res.kind) {
+      stderr.write(`[error] blueprint companions set: ${res.message}\n`);
+      return 2;
+    }
+    if (asJson) {
+      stdout.write(`${JSON.stringify({ ok: true, role, provider, previousProvider: res.previousProvider, pinnedAt: now.toISOString() })}\n`);
+    } else if (!quiet) {
+      if (res.previousProvider && res.previousProvider !== provider) {
+        stdout.write(`[blueprint] companion pin for role '${role}' updated: '${res.previousProvider}' -> '${provider}'\n`);
+      } else {
+        stdout.write(`[blueprint] companion pin for role '${role}' set to '${provider}'\n`);
+      }
+    }
+    return 0;
+  }
+  if (head === 'unset') {
+    if (rest.length < 2) {
+      stderr.write('[error] blueprint companions unset: expected <role>\n');
+      return 2;
+    }
+    const role = rest[1];
+    const res = await unsetCompanionPin({ projectRoot, role });
+    if (res.kind) {
+      stderr.write(`[error] blueprint companions unset: ${res.message}\n`);
+      return 2;
+    }
+    if (asJson) {
+      stdout.write(`${JSON.stringify({ ok: true, role, removed: true })}\n`);
+    } else if (!quiet) {
+      stdout.write(`[blueprint] companion pin for role '${role}' removed\n`);
+    }
+    return 0;
+  }
+  // <slug> form: print the resolved companion set for an applied
+  // service blueprint (spec 2.5 first form).
+  const slug = head;
+  const applied = (tree?.manifest?.blueprints ?? []).find((bp) => bp.slug === slug);
+  if (!applied) {
+    stderr.write(`[error] blueprint companions: no applied blueprint with slug '${slug}' on this project.\n`);
+    return 2;
+  }
+  if (typeof applied.source !== 'string' || applied.source.length === 0) {
+    stderr.write(`[error] blueprint companions: applied blueprint '${slug}' has no readable source.\n`);
+    return 2;
+  }
+  if (applied.source.includes(':') && !applied.source.startsWith('/')) {
+    stderr.write(`[error] blueprint companions: applied blueprint '${slug}' has a library-qualified source '${applied.source}' the companions reader cannot resolve directly; refresh the library and retry, or supply the source path.\n`);
+    return 2;
+  }
+  const bp = await loadBlueprint(applied.source);
+  if (bp.kind) {
+    stderr.write(`[error] blueprint companions: applied blueprint '${slug}' source failed to load: ${bp.message}\n`);
+    return 2;
+  }
+  if (!Array.isArray(bp.suggestedCompanions) || bp.suggestedCompanions.length === 0) {
+    stderr.write(`[error] blueprint companions: applied blueprint '${slug}' declares no suggestedCompanions[].\n`);
+    return 2;
+  }
+  const pins = await readCompanionsFile(projectRoot);
+  const pinsClean = pins && pins.kind ? null : pins;
+  const resolved = await resolveCompanions({
+    projectRoot,
+    tree,
+    suggestedCompanions: bp.suggestedCompanions,
+    pins: pinsClean,
+  });
+  const ambiguous = resolved.find((r) => r.origin === 'ambiguousLibraries');
+  if (ambiguous && !asJson) {
+    stderr.write(renderAmbiguousLibraryRefusal({
+      role: ambiguous.role,
+      providers: ambiguous.ambiguousProviders,
+      serviceSlug: slug,
+    }));
+    return 3;
+  }
+  if (asJson) {
+    stdout.write(`${JSON.stringify({
+      slug,
+      suggestions: resolved.map((r) => ({
+        role: r.role,
+        reason: r.reason,
+        provider: r.provider,
+        origin: r.origin,
+        notes: r.notes,
+        ...(r.ambiguousProviders ? { ambiguousProviders: r.ambiguousProviders } : {}),
+      })),
+    }, null, 2)}\n`);
+    return ambiguous ? 3 : 0;
+  }
+  stdout.write(`${slug} suggests companions:\n`);
+  stdout.write(`${renderCompanionLines(resolved)}\n`);
+  return 0;
+}
+
 /**
  * Parse `--resolve <topic>=project:<ADR-id>` occurrences into a list
  * of declarations, attaching an optional shared `reason` (from the

package/src/cli/validate.js

@@ -6,6 +6,7 @@ import { parseArgs } from 'node:util';
 
 import { formatErrors } from '#core/errors';
 import { checkCodeNodeResolution, walkTree } from '#core/store';
+import { validateCompanionPinsResolvable } from '../blueprint/companions.js';
 import { findProjectRoot } from '../view/index.js';
 
 const OPTION_SPEC = {
@@ -126,6 +127,12 @@ export async function main(argv, deps = {}) {
     const staleErrors = await checkCodeNodeResolution({ projectRoot, tree });
     errors.push(...staleErrors);
   }
+  // Core-companions spec section 5: rcf/companions.json refusals ride
+  // the same exit path as schema / referential-integrity errors. An
+  // absent companions.json is not itself an error; a malformed file or
+  // a pin that names no known provider is exit 3.
+  const companionsErrors = await validateCompanionPinsResolvable({ projectRoot, tree });
+  errors.push(...companionsErrors);
   if (flags.json) {
     const issues = errors.map((e) => ({
       id: e.documentId ?? null,