rcf-lite 0.16.0 → 0.18.0

package/src/blueprint/remove-resolution.js

@@ -0,0 +1,104 @@
+// `rcf define blueprint remove-resolution <adr-id>` implementation.
+//
+// Removes a single entry from `manifest.resolutions[]` (and NOTHING
+// else). The `<adr-id>` argument is matched against the entry's
+// `resolvedByAdrId` field, which is how the doctor's probe-path-owner
+// check (spec section 9) and the four-path resolution card (spec
+// section 4) name the resolution to the operator.
+//
+// Behaviours (spec amendment A2, ratified 2026-09-04):
+//   - Removes the resolutions[] entry whose `resolvedByAdrId` equals
+//     the argument; leaves every other manifest section untouched. The
+//     project-level ADR file at `rcf/adrs/<adr-id>.json` is NOT
+//     deleted: an operator who wants to keep the ruling ADR as
+//     historical context after the redundant resolution goes away has
+//     that path open; an operator who wants the ADR gone can rm it
+//     themselves.
+//   - Refuses exit 2 when the argument is not a resolution entry on
+//     this manifest. Two flavours count as "not a resolution entry":
+//     the id is malformed (fails the ADR-\d{3,}(-<kebab-tail>)? grammar),
+//     or the id is well-formed but names no ADR anywhere on the
+//     tree AND is not present under any resolutions[] entry.
+//   - Idempotent on a second run: when the id is a well-formed ADR
+//     id that names an ADR present on the tree (the ruling ADR that
+//     the resolution had pointed at) but is not (any longer) present
+//     under any resolutions[] entry, the module returns
+//     `{ removed: false, alreadyAbsent: true }` and the CLI edge
+//     prints "nothing to remove" and exits 0. The distinction is:
+//     the ruling ADR still exists on disk, so the operator is running
+//     the SAME operation a second time, not typing a bogus id.
+//
+// The verb never touches project ADR files, blueprint records, or any
+// other manifest section. That keeps the scope narrow enough that the
+// operator can reason about the write without reading the module.
+
+import { isRcfError, rcfError } from '../core/errors/index.js';
+import { updateManifest } from './manifest-writer.js';
+
+const ADR_ID_PATTERN = /^ADR-\d{3,}(?:-[a-z0-9]+(?:-[a-z0-9]+)*)?$/;
+
+/**
+ * @typedef {object} RemoveResolutionResult
+ * @property {boolean} removed
+ * @property {boolean} [alreadyAbsent]
+ * @property {string}  resolvedByAdrId
+ * @property {string}  [resolutionId]
+ * @property {string}  [topic]
+ */
+
+/**
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {import('#core/store/walker.js').TreeModel} args.tree
+ * @param {string} args.resolvedByAdrId
+ * @param {boolean} [args.dryRun]
+ * @returns {Promise<RemoveResolutionResult | import('../core/errors/index.js').RcfError>}
+ */
+export async function removeResolution({ projectRoot, tree, resolvedByAdrId, dryRun = false }) {
+  if (typeof resolvedByAdrId !== 'string' || resolvedByAdrId.trim().length === 0) {
+    return rcfError({ kind: 'usage', message: `<adr-id> is required (e.g. rcf define blueprint remove-resolution ADR-011-health-probes).` });
+  }
+  if (!ADR_ID_PATTERN.test(resolvedByAdrId)) {
+    return rcfError({ kind: 'usage', message: `'${resolvedByAdrId}' is not a well-formed ADR id (grammar: ADR-\\d{3,}(-<kebab-tail>)?).` });
+  }
+  const manifest = tree.manifest ?? {};
+  const resolutions = Array.isArray(manifest.resolutions) ? manifest.resolutions : [];
+  const index = resolutions.findIndex((r) => r?.resolvedByAdrId === resolvedByAdrId);
+  if (index === -1) {
+    // Not on resolutions[]. Two branches:
+    //   - the ruling ADR file exists on the tree: idempotent no-op
+    //     (this is a re-run of the same operation).
+    //   - no ADR by that id anywhere: refuse. The operator has typed
+    //     an id that this project has no record of, either as a
+    //     resolution entry or as a project ADR.
+    const adrPresent = tree.byId instanceof Map && tree.byId.has(resolvedByAdrId);
+    if (adrPresent) {
+      return { removed: false, alreadyAbsent: true, resolvedByAdrId };
+    }
+    return rcfError({
+      kind: 'usage',
+      message: `'${resolvedByAdrId}' is not a resolution entry on this manifest (no resolutions[] record names it as resolvedByAdrId, and no ADR by that id exists on the project tree).`,
+    });
+  }
+  const target = resolutions[index];
+  const result = await updateManifest({
+    projectRoot,
+    manifest,
+    mutate: (next) => {
+      const list = Array.isArray(next.resolutions) ? next.resolutions : [];
+      list.splice(index, 1);
+      // Drop the field entirely when empty so the manifest shape stays
+      // as compact as it was before any resolution was ever recorded.
+      if (list.length === 0) delete next.resolutions;
+      else next.resolutions = list;
+    },
+    dryRun,
+  });
+  if (isRcfError(result)) return result;
+  return {
+    removed: true,
+    resolvedByAdrId,
+    resolutionId: typeof target?.id === 'string' ? target.id : undefined,
+    topic: typeof target?.topic === 'string' ? target.topic : undefined,
+  };
+}

package/src/blueprint/supersede.js

@@ -26,7 +26,7 @@
 // the refused-add state; the escalation the worker adapted around was
 // that AC-1002-5 could not pass as written. The `--incoming` argument
 // was subsequently fed directly to `loadBlueprint`, which understands
-// paths only — a newcomer who intuited the `@stock/<slug>` form from
+// paths only; a newcomer who intuited the `@stock/<slug>` form from
 // `add`'s help hit a refusal. Persona re-run 2026-08-31 arc-4, H2.
 //
 // Two side effects, both governed by dryRun:
@@ -171,7 +171,7 @@ export async function supersedeBlueprintTopic({ projectRoot, tree, topic, incomi
     // For library-qualified sources the applied identity is rewired
     // under the library prefix (`<libraryPrefix>-<blueprintSlug>`), so
     // the supersedes[] entry must reference that effective slug and
-    // stamp the ADR id under it — matching what `apply.js` writes to
+    // stamp the ADR id under it; matching what `apply.js` writes to
     // `manifest.blueprints[].slug`. For shelf / path sources the
     // blueprint's own slug applies.
     const effectiveSlug = resolved.kind === 'library'

package/src/cli/blueprint.js

@@ -20,6 +20,7 @@ import {
   groupRowsByCategory,
   listBlueprints,
   removeBlueprint,
+  removeResolution,
   renderDiff,
   resolveBlueprintSource,
   supersedeBlueprintTopic,
@@ -66,6 +67,20 @@ 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.
   library <verb>         Manage external blueprint libraries. Sub-verbs:
                          add, list, remove, refresh. See
                          'rcf define blueprint library --help' for the
@@ -364,6 +379,32 @@ 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;
+  }
+
   stderr.write(`[error] blueprint: unknown verb '${verb}'\n`);
   stderr.write(HELP);
   return 2;

package/src/cli/doctor.js

@@ -47,6 +47,16 @@ import {
 } from '../setup/managed-gitignore.js';
 import { identityProfilePath } from '../setup/identity-seed.js';
 import { knowledgePaths } from '../setup/knowledge-seed.js';
+import {
+  checkBrowserPresent,
+  checkPlaywrightMcpReachable,
+  checkPlaywrightPresent,
+  findProjectPlaywrightKey,
+  FIX_LINES,
+  loadBrowserFacingSources,
+  probeClaudeCodeMcp,
+  SKIP_LINE_NON_BROWSER_FACING,
+} from '../setup/playwright-checks.js';
 
 const OPTION_SPEC = {
   fix: { type: 'boolean' },
@@ -57,7 +67,25 @@ const OPTION_SPEC = {
   help: { type: 'boolean' },
 };
 
-const KNOWN_CHECKS = /** @type {const} */ (['agent-instructions', 'gitignore', 'knowledge', 'identity']);
+const KNOWN_CHECKS = /** @type {const} */ ([
+  'agent-instructions',
+  'gitignore',
+  'knowledge',
+  'identity',
+  'playwright-present',
+  'browser-present',
+  'playwright-mcp-reachable',
+  'playwright-mcp-redundant',
+  'probe-path-owner',
+]);
+
+/** The four Playwright-related checks doctor runs conditionally for
+ * browser-facing projects (spec 2026-09-03, section 3). */
+const PLAYWRIGHT_CHECKS = /** @type {const} */ ([
+  'playwright-present',
+  'browser-present',
+  'playwright-mcp-reachable',
+]);
 
 export const HELP = `Usage: rcf doctor [--fix] [--check <check>[,check]] [--json] [--quiet] [--help]
 
@@ -73,8 +101,10 @@ Options:
                             removing the corrupted region.
   --check <check>[,check]   Run only the named checks. Default: all.
                             Values: agent-instructions, gitignore,
-                                    knowledge, identity.
-  --json                    Emit machine-readable envelope: { ok, drift[] }.
+                                    knowledge, identity, playwright-present,
+                                    browser-present, playwright-mcp-reachable,
+                                    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
                             content that a non-interactive run would
@@ -155,12 +185,48 @@ export async function main(argv, deps = {}) {
     force: Boolean(flags.force),
     // isTty is deps-injectable for tests; falls back to real stdout.
     isTty: deps.isTty ?? Boolean(stdout.isTTY),
+    // Doctor's Playwright-check seams (spec 2026-09-03, section 3). Every
+    // probe is injectable so the unit suite runs with none of these tools
+    // installed on the runner.
+    checkPlaywrightPresentImpl: deps.checkPlaywrightPresent ?? checkPlaywrightPresent,
+    checkBrowserPresentImpl: deps.checkBrowserPresent ?? checkBrowserPresent,
+    checkPlaywrightMcpReachableImpl:
+      deps.checkPlaywrightMcpReachable ?? checkPlaywrightMcpReachable,
+    probeClaudeCodeMcpImpl: deps.probeClaudeCodeMcp ?? probeClaudeCodeMcp,
+    loadBrowserFacingSourcesImpl:
+      deps.loadBrowserFacingSources ?? loadBrowserFacingSources,
+    readMcpJsonImpl: deps.readMcpJson ?? defaultReadMcpJson,
   };
 
+  // Section 3.1: browser-facing projection. Computed once; every Playwright
+  // check reads the result from ctx rather than re-walking the manifest.
+  const browserFacingResult = await ctx.loadBrowserFacingSourcesImpl(cwd);
+  ctx.browserFacing = Boolean(browserFacingResult.browserFacing);
+  ctx.browserFacingSources = browserFacingResult.sources ?? [];
+
   /** @type {Array<{check: string, item: string, file: string, message: string, refusedByFix: boolean}>} */
   const drift = [];
   /** @type {Array<{file: string, action: string}>} */
   const writes = [];
+  /** @type {string[]} */
+  const notices = [];
+
+  // Section 3.4: skip line for the three Playwright checks on non-browser-
+  // facing projects. Emitted when at least one of the three is enabled but
+  // the project is not browser-facing AND the operator did not explicitly ask
+  // for that check by name (spec 3.5). We honour the --check filter by
+  // detecting whether the operator explicitly named any playwright check.
+  const explicitlyPickedPlaywrightChecks = new Set(
+    enabled.filter((c) => PLAYWRIGHT_CHECKS.includes(c)),
+  );
+  const anyPlaywrightCheckEnabled = explicitlyPickedPlaywrightChecks.size > 0;
+  const operatorAskedByName =
+    typeof flags.check === 'string'
+    && flags.check.length > 0
+    && explicitlyPickedPlaywrightChecks.size > 0;
+  if (anyPlaywrightCheckEnabled && !ctx.browserFacing && !operatorAskedByName) {
+    notices.push(SKIP_LINE_NON_BROWSER_FACING);
+  }
 
   for (const check of enabled) {
     let result;
@@ -168,7 +234,26 @@ export async function main(argv, deps = {}) {
     else if (check === 'gitignore') result = await runGitignoreCheck(ctx);
     else if (check === 'knowledge') result = await runKnowledgeCheck(ctx);
     else if (check === 'identity') result = await runIdentityCheck(ctx);
-    else continue;
+    else if (PLAYWRIGHT_CHECKS.includes(check)) {
+      // Skip the check on non-browser-facing projects unless the operator
+      // explicitly asked for this check by name (--check filter): the skip
+      // line above is the ground-truth diagnostic in that case (spec 3.4/3.5).
+      if (!ctx.browserFacing && !operatorAskedByName) continue;
+      if (check === 'playwright-present') result = await runPlaywrightPresentCheck(ctx);
+      else if (check === 'browser-present') result = await runBrowserPresentCheck(ctx);
+      else if (check === 'playwright-mcp-reachable') result = await runPlaywrightMcpReachableCheck(ctx);
+      else continue;
+    } else if (check === 'playwright-mcp-redundant') {
+      // Fires only on browser-facing projects (spec 4.5). Never runs on an
+      // 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);
   }
@@ -183,10 +268,15 @@ export async function main(argv, deps = {}) {
   const exitCode = ok ? 0 : 3;
 
   if (flags.json) {
-    stdout.write(`${JSON.stringify({ ok, drift, writes }, null, 2)}\n`);
+    stdout.write(`${JSON.stringify({ ok, drift, writes, notices }, null, 2)}\n`);
     return exitCode;
   }
 
+  // Notices (spec 3.4 skip line) are diagnostic ground truth. Emitted BEFORE
+  // the summary so an operator scanning the top of the output sees why the
+  // three checks did not fire on a non-browser-facing project. Not
+  // suppressed by --quiet.
+  for (const notice of notices) stdout.write(`${notice}\n`);
   writeHumanSummary({ stdout, ok, drift, writes, fixed: ctx.fix, quiet: Boolean(flags.quiet) });
   return exitCode;
 }
@@ -546,3 +636,165 @@ async function isPathIgnored(projectRoot) {
 
 // Silence unused-import warnings for values consumed only via names.
 void composeGitignoreInner;
+
+/* ------------------------------------------------------------------ */
+/* Check: playwright-present (spec 3.3)                               */
+/* ------------------------------------------------------------------ */
+
+async function runPlaywrightPresentCheck(ctx) {
+  const drift = [];
+  const result = ctx.checkPlaywrightPresentImpl(ctx.projectRoot);
+  if (!result.ok) {
+    drift.push({
+      item: 'missing-peer',
+      file: 'package.json',
+      message: FIX_LINES['playwright-present'],
+      refusedByFix: true,
+    });
+  }
+  return { drift, writes: [] };
+}
+
+/* ------------------------------------------------------------------ */
+/* Check: browser-present (spec 3.3)                                  */
+/* ------------------------------------------------------------------ */
+
+async function runBrowserPresentCheck(ctx) {
+  const drift = [];
+  const result = await ctx.checkBrowserPresentImpl();
+  if (!result.ok) {
+    drift.push({
+      item: 'no-browser',
+      file: '(system)',
+      message: FIX_LINES['browser-present'],
+      refusedByFix: true,
+    });
+  }
+  return { drift, writes: [] };
+}
+
+/* ------------------------------------------------------------------ */
+/* Check: playwright-mcp-reachable (spec 3.3)                         */
+/* ------------------------------------------------------------------ */
+
+async function runPlaywrightMcpReachableCheck(ctx) {
+  const drift = [];
+  const result = await ctx.checkPlaywrightMcpReachableImpl();
+  if (!result.ok) {
+    drift.push({
+      item: result.timedOut ? 'unreachable-timeout' : 'unreachable',
+      file: '(npx @playwright/mcp)',
+      message: FIX_LINES['playwright-mcp-reachable'],
+      refusedByFix: true,
+    });
+  }
+  return { drift, writes: [] };
+}
+
+/* ------------------------------------------------------------------ */
+/* Check: playwright-mcp-redundant (spec 4.5)                         */
+/* ------------------------------------------------------------------ */
+
+async function runPlaywrightMcpRedundantCheck(ctx) {
+  const drift = [];
+  const mcpJson = await ctx.readMcpJsonImpl(ctx.projectRoot);
+  const projectKey = mcpJson ? findProjectPlaywrightKey(mcpJson) : null;
+  if (!projectKey) return { drift, writes: [] };
+  const probeResult = await ctx.probeClaudeCodeMcpImpl();
+  if (probeResult.kind !== 'found') return { drift, writes: [] };
+  drift.push({
+    item: 'redundant-entry',
+    file: '.mcp.json',
+    message: `project-scope .mcp.json carries a Playwright MCP entry ('${projectKey}') that is also declared at ${probeResult.scope} scope. The project entry shadows the user entry. Remove the project entry with \`rcf init --no-playwright-mcp\` (which re-runs init without writing it), or delete the '${projectKey}' entry from .mcp.json by hand.`,
+    refusedByFix: true,
+  });
+  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
+ * .mcp.json as "no signature findable" rather than a hard refusal here; the
+ * merge path in agent-setup already refuses unparseable with exit 2 on write).
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<object|null>}
+ */
+async function defaultReadMcpJson(projectRoot) {
+  const file = join(projectRoot, '.mcp.json');
+  try {
+    const raw = await readFile(file, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}