rcf-lite 0.17.0 → 0.19.0

package/src/cli/blueprint.js

@@ -19,10 +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';
@@ -66,6 +76,40 @@ Verbs:
   diff <topic>           Side-by-side view of every applied blueprint's
                          scope:global ADR on <topic>: id, path, title,
                          status, decision. Read-only.
+  remove-resolution <adr-id>
+                         Remove a single manifest.resolutions[] entry by
+                         its resolvedByAdrId (the id the doctor's
+                         probe-path-owner check names when a historical
+                         resolution has become redundant after a
+                         blueprint upgrade). Writes nothing else: the
+                         project-level ADR file at rcf/adrs/<adr-id>.json
+                         is left in place as historical context. Refuses
+                         exit 2 when <adr-id> is malformed or names no
+                         ADR on the project tree. Idempotent on re-run:
+                         when <adr-id> is a well-formed ADR id that
+                         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
@@ -87,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
@@ -122,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' },
 };
 
 /**
@@ -205,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,
@@ -273,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;
   }
 
@@ -364,11 +496,229 @@ export async function main(argv, deps = {}) {
     return 0;
   }
 
+  if (verb === 'remove-resolution') {
+    if (rest.length === 0) {
+      stderr.write('[error] blueprint remove-resolution: missing <adr-id>\n');
+      return 2;
+    }
+    const adrId = rest[0];
+    const result = await removeResolution({
+      projectRoot, tree, resolvedByAdrId: adrId,
+      dryRun: parsed.values['dry-run'] === true,
+    });
+    if (isRcfError(result)) {
+      stderr.write(`[error] blueprint remove-resolution: ${result.message}\n`);
+      return 2;
+    }
+    if (result.alreadyAbsent) {
+      if (!parsed.values.quiet) stdout.write(`[blueprint] nothing to remove: '${adrId}' is not on manifest.resolutions[].\n`);
+      return 0;
+    }
+    if (!parsed.values.quiet) {
+      const topicSuffix = result.topic ? ` (topic '${result.topic}')` : '';
+      const idSuffix = result.resolutionId ? `; dropped resolution ${result.resolutionId}` : '';
+      stdout.write(`[blueprint] removed resolution for '${adrId}'${topicSuffix}${idSuffix}.\n`);
+    }
+    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/doctor.js

@@ -76,6 +76,7 @@ const KNOWN_CHECKS = /** @type {const} */ ([
   'browser-present',
   'playwright-mcp-reachable',
   'playwright-mcp-redundant',
+  'probe-path-owner',
 ]);
 
 /** The four Playwright-related checks doctor runs conditionally for
@@ -102,7 +103,7 @@ Options:
                             Values: agent-instructions, gitignore,
                                     knowledge, identity, playwright-present,
                                     browser-present, playwright-mcp-reachable,
-                                    playwright-mcp-redundant.
+                                    playwright-mcp-redundant, probe-path-owner.
   --json                    Emit machine-readable envelope: { ok, drift, writes, notices }.
   --quiet                   Only summary line + first 3 drift items.
   --force                   Accept a legacy-markers --fix on hand-edited
@@ -247,6 +248,11 @@ export async function main(argv, deps = {}) {
       // API-only project even under an explicit --check ask.
       if (!ctx.browserFacing) continue;
       result = await runPlaywrightMcpRedundantCheck(ctx);
+    } else if (check === 'probe-path-owner') {
+      // Fires whenever more than one applied blueprint teaches probe paths.
+      // Runs on every project (not gated on browser-facing). Spec:
+      // projects/rcf-lite-wsd/specs/rcf-lite-probe-path-alignment-spec-2026-09-04.md section 9.
+      result = await runProbePathOwnerCheck(ctx);
     } else continue;
     for (const d of result.drift) drift.push({ check, ...d });
     for (const w of result.writes) writes.push(w);
@@ -705,6 +711,75 @@ async function runPlaywrightMcpRedundantCheck(ctx) {
   return { drift, writes: [] };
 }
 
+/* ------------------------------------------------------------------ */
+/* Check: probe-path-owner (probe-path alignment spec section 9)      */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Fires when more than one applied blueprint teaches probe paths. Reads
+ * `rcf/manifest.json` for the applied-blueprint records; counts how many
+ * carry a scope:global ADR on `healthProbes` (the shelf-wide probe-path
+ * ownership topic). More than one is drift: names the blueprints and the
+ * remedy line naming the one that would have to drop its opinion.
+ *
+ * Also names any resolutions[] entry the alignment removed as redundant
+ * (a project that applied essentials v1.x + probe-endpoints v1.0.0 and
+ * resolved the two topics via supersede will have a resolution entry
+ * pointing at both blueprint ADRs; after re-applying to essentials v2.0.0
+ * the essentials side no longer claims the topic and the resolution is
+ * redundant historical context the operator can remove).
+ */
+async function runProbePathOwnerCheck(ctx) {
+  const drift = [];
+  const manifestPath = join(ctx.projectRoot, 'rcf', 'manifest.json');
+  let manifest = null;
+  try {
+    manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+  } catch { return { drift, writes: [] }; }
+  const applied = Array.isArray(manifest?.blueprints) ? manifest.blueprints : [];
+  const claimants = { healthProbes: [], readinessSemantics: [] };
+  for (const b of applied) {
+    for (const c of b?.contributions ?? []) {
+      if (c?.kind === 'adr' && c?.scope === 'global' && (c.topic === 'healthProbes' || c.topic === 'readinessSemantics')) {
+        claimants[c.topic].push({ slug: b.slug, adrId: c.id });
+      }
+    }
+  }
+  for (const topic of ['healthProbes', 'readinessSemantics']) {
+    if (claimants[topic].length > 1) {
+      const slugs = claimants[topic].map((x) => x.slug).join(', ');
+      const owner = claimants[topic].find((x) => x.slug === 'observability-probe-endpoints');
+      const remedy = owner
+        ? `${claimants[topic].filter((x) => x.slug !== 'observability-probe-endpoints').map((x) => x.slug).join(', ')} would have to drop its scope:global claim on ${topic} (observability-probe-endpoints is the shelf canonical owner from probe-endpoints v1.0.0)`
+        : `one of ${slugs} would have to drop its scope:global claim on ${topic}`;
+      drift.push({
+        item: `multiple-${topic}-owners`,
+        file: 'rcf/manifest.json',
+        message: `more than one applied blueprint teaches probe paths on topic '${topic}': ${slugs}. ${remedy}. Spec: projects/rcf-lite-wsd/specs/rcf-lite-probe-path-alignment-spec-2026-09-04.md section 9.`,
+        refusedByFix: true,
+      });
+    }
+  }
+  // Redundant resolutions: a resolutions[] entry that names both
+  // `healthProbes` or `readinessSemantics` where the current claimant
+  // count is 1 (or 0) is redundant historical context.
+  const resolutions = Array.isArray(manifest?.resolutions) ? manifest.resolutions : [];
+  for (const r of resolutions) {
+    if (r?.topic === 'healthProbes' || r?.topic === 'readinessSemantics') {
+      if (claimants[r.topic].length <= 1) {
+        drift.push({
+          item: `redundant-${r.topic}-resolution`,
+          file: 'rcf/manifest.json',
+          message: `resolution '${r?.resolvedByAdrId ?? '(unnamed)'}' on topic '${r.topic}' is now redundant historical context: only ${claimants[r.topic].length} applied blueprint claims the topic after the probe-path alignment. Consider \`rcf define blueprint remove-resolution ${r?.resolvedByAdrId ?? '<id>'}\` or leave the resolution ADR as historical.`,
+          refusedByFix: true,
+        });
+      }
+    }
+  }
+  return { drift, writes: [] };
+}
+
+
 /**
  * Default reader for the project-root .mcp.json body. Returns the parsed
  * object, or null on missing / unparseable (doctor treats an unparseable

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,