rcf-lite 0.16.0 → 0.17.0

package/rcf/prd.json

@@ -18,7 +18,8 @@
     "SDD build loop: assemble an implementation prompt from a build specification and mark it done on merge",
     "Local stdio MCP surface exposing query, CRUD, view and build to AI tooling",
     "Validation of every document against the published schema package at every boundary",
-    "Deploy-aware, runtime-honest build guidance: a documented local preview as the default build outcome, an early deploy-target question that constrains the stack, and runtime-provenance labels on verification claims"
+    "Deploy-aware, runtime-honest build guidance: a documented local preview as the default build outcome, an early deploy-target question that constrains the stack, and runtime-provenance labels on verification claims",
+    "End-to-end verification contract: version-pinned Playwright MCP in verify, e2e as a declared test level in the chain (application-spa browserSurface and delivery-ci-workflows e2e CI job), doctor checks for browser-facing projects, and init that writes a Playwright MCP entry only when no scope-visible entry exists"
   ],
   "outOfScope": [
     "The schema package itself, which is the separately published rcf-schemas contract",
@@ -43,5 +44,5 @@
     "MCP transport is local stdio only"
   ],
   "createdAt": "2026-06-25T00:00:00Z",
-  "updatedAt": "2026-07-20T17:56:57.237Z"
+  "updatedAt": "2026-09-03T16:56:00Z"
 }

package/rcf/requirements/req-011.json

@@ -0,0 +1,22 @@
+{
+  "reqId": "REQ-011",
+  "prdId": "PRD-001",
+  "title": "e2e verification contract: pinned Playwright MCP, declared e2e test level, doctor and init behaviour",
+  "description": "The rcf-lite verify pass provisions a version-pinned Playwright MCP server instead of @latest, prints the effective pin in preflight, and honours an emergency override. The rcf method exposes e2e as a declared test level: the application-spa blueprint declares a browserSurface, contributes browser-facing acceptance criteria, and cross-links a test-case template to the browser-verify TAC; the delivery-ci-workflows blueprint materialises a distinct e2e CI job when an applied blueprint declares a browserSurface. rcf doctor gains playwright-present, browser-present, playwright-mcp-reachable, and playwright-mcp-redundant checks for browser-facing projects; non-browser projects skip the three with one reason line. rcf init writes a Playwright MCP entry only when a project-scope signature is absent and a user-scope harness probe cannot prove one exists; otherwise it leaves the wiring alone or writes the distinctly named playwright-rcf fallback. All four parts observe the ratified 2026-09-03 e2e contract at projects/rcf-lite-wsd/specs/rcf-lite-e2e-contract-spec-2026-09-03.md.",
+  "category": "functional",
+  "domain": "verify",
+  "priority": "must",
+  "rationale": "Verify is the ship gate. A silent runtime change in the browser MCP on the next verify run is the reproducibility hole Baz named on 2026-09-03. Pinning the MCP closes it. Formalising e2e as a declared test level gives browser-facing projects a first-class contract instead of relying on the verify browser stage as a proxy for coverage. Doctor and init together make Playwright the operator's decision, not rcf-lite's ambient inheritance.",
+  "tags": [
+    "verify",
+    "playwright-mcp",
+    "e2e",
+    "blueprint-library",
+    "doctor",
+    "init"
+  ],
+  "version": "0.1.0",
+  "status": "draft",
+  "createdAt": "2026-09-03T16:56:00Z",
+  "updatedAt": "2026-09-03T16:56:00Z"
+}

package/rcf/test-suites/ts-030.json

@@ -0,0 +1,66 @@
+{
+  "id": "TS-030",
+  "usId": "US-1101",
+  "title": "Verify pins the Playwright MCP version, prints it in preflight, honours the override",
+  "purpose": "Cover the four ACs on US-1101: the pinned constant + composed default MCP config, the preflight stderr line, the override notice + non-semver refusal, and the default pin lands on the report as runStats.playwrightMcpVersion.",
+  "testLevel": "unit",
+  "acIds": [
+    "AC-1101-1",
+    "AC-1101-2",
+    "AC-1101-3",
+    "AC-1101-4"
+  ],
+  "testCases": [
+    {
+      "id": "TC-030-pin-constant-exported",
+      "acId": "AC-1101-1",
+      "description": "PLAYWRIGHT_MCP_VERSION is exported as a semver string, not @latest",
+      "testPointer": "test/verify/engine/launcher.test.js::PLAYWRIGHT_MCP_VERSION is exported as a semver string and is NOT @latest",
+      "status": "pending",
+      "scope": "library"
+    },
+    {
+      "id": "TC-030-default-config-uses-pin",
+      "acId": "AC-1101-1",
+      "description": "DEFAULT_MCP_CONFIG.args composes @playwright/mcp with the pinned version and never @latest",
+      "testPointer": "test/verify/engine/launcher.test.js::DEFAULT_MCP_CONFIG composes @playwright/mcp with the pinned version (never @latest)",
+      "status": "pending",
+      "scope": "library"
+    },
+    {
+      "id": "TC-030-preflight-line",
+      "acId": "AC-1101-2",
+      "description": "rcf verify run prints one preflight line naming the effective @playwright/mcp pin on stderr",
+      "testPointer": "test/verify/cli/run.test.js::run: preflight prints the pinned Playwright MCP version to stderr",
+      "status": "pending",
+      "scope": "runtime"
+    },
+    {
+      "id": "TC-030-override-notice",
+      "acId": "AC-1101-3",
+      "description": "--playwright-mcp-version fires the loud stderr override notice and records the effective pin on the report",
+      "testPointer": "test/verify/cli/run.test.js::run: --playwright-mcp-version fires the loud override notice AND lands on the report",
+      "status": "pending",
+      "scope": "runtime"
+    },
+    {
+      "id": "TC-030-override-non-semver-refused",
+      "acId": "AC-1101-3",
+      "description": "--playwright-mcp-version with a non-semver value refuses exit 2 with the spec-named message",
+      "testPointer": "test/verify/cli/run.test.js::run: --playwright-mcp-version with a non-semver value refuses exit 2 with the spec-named message",
+      "status": "pending",
+      "scope": "runtime"
+    },
+    {
+      "id": "TC-030-default-pin-on-report",
+      "acId": "AC-1101-4",
+      "description": "Even with no override the report records the default pin as runStats.playwrightMcpVersion",
+      "testPointer": "test/verify/cli/run.test.js::run: default pin lands on the report as runStats.playwrightMcpVersion even with no override",
+      "status": "pending",
+      "scope": "runtime"
+    }
+  ],
+  "status": "draft",
+  "createdAt": "2026-09-03T18:30:50Z",
+  "updatedAt": "2026-09-03T18:30:50Z"
+}

package/rcf/test-suites/ts-031.json

@@ -0,0 +1,59 @@
+{
+  "id": "TS-031",
+  "usId": "US-1102",
+  "title": "application-spa v1.4.0 declares browserSurface, delivery-ci-workflows v2.2.0 documents the e2e job",
+  "purpose": "Cover the five ACs on US-1102: SPA blueprint at 1.4.0 with browserSurface.declared, the two new e2e user stories plus the e2e.md template, delivery-ci-workflows v2.2.0 US-6124 binding the four e2e-job points, the illustrative GHA workflow + per-provider notes, and the applied manifest validating with no browserSurface on the applied record.",
+  "testLevel": "contract",
+  "acIds": [
+    "AC-1102-1",
+    "AC-1102-2",
+    "AC-1102-3",
+    "AC-1102-4",
+    "AC-1102-5"
+  ],
+  "testCases": [
+    {
+      "id": "TC-031-spa-version-and-flag",
+      "acId": "AC-1102-1",
+      "description": "SPA blueprint.json is at version 1.4.0 and browserSurface.declared is true",
+      "testPointer": "test/blueprint/apply-spa-v1-4-0-schema.test.js::AC-1102-5: apply application-spa v1.4.0 -> manifest still validates + no browserSurface on the applied record",
+      "status": "pending",
+      "scope": "library"
+    },
+    {
+      "id": "TC-031-spa-us-and-template",
+      "acId": "AC-1102-2",
+      "description": "SPA contributes US-1134 and US-1135 as browser-facing e2e stories, and ships assets/tc-templates/e2e.md naming the browser-verify driver seam",
+      "testPointer": "test/blueprint/e2e-contract-blueprint-facts.test.js::AC-1102-2: application-spa ships US-1134 and US-1135 as browser-facing (scope: deployed) e2e stories, plus the e2e.md template",
+      "status": "pending",
+      "scope": "library"
+    },
+    {
+      "id": "TC-031-ci-us-6124",
+      "acId": "AC-1102-3",
+      "description": "delivery-ci-workflows v2.2.0 contributes US-6124 whose AC-6124-1 names the four e2e-job points",
+      "testPointer": "test/blueprint/e2e-contract-blueprint-facts.test.js::AC-1102-3: delivery-ci-workflows v2.2.0 US-6124 binds an AC naming the four e2e-job points",
+      "status": "pending",
+      "scope": "library"
+    },
+    {
+      "id": "TC-031-illustrative-workflow-and-notes",
+      "acId": "AC-1102-4",
+      "description": "Illustrative GHA pull-request-checks.yml carries the e2e job block and notes.md translates it per provider",
+      "testPointer": "test/blueprint/e2e-contract-blueprint-facts.test.js::AC-1102-4: illustrative GHA pull-request-checks.yml carries the e2e job and notes.md translates the four points per provider",
+      "status": "pending",
+      "scope": "library"
+    },
+    {
+      "id": "TC-031-manifest-validates",
+      "acId": "AC-1102-5",
+      "description": "Applying SPA v1.4.0 produces a manifest that still validates against rcf-schemas 0.5.1 and the applied record carries no browserSurface field",
+      "testPointer": "test/blueprint/apply-spa-v1-4-0-schema.test.js::AC-1102-5: apply application-spa v1.4.0 -> manifest still validates + no browserSurface on the applied record",
+      "status": "pending",
+      "scope": "runtime"
+    }
+  ],
+  "status": "draft",
+  "createdAt": "2026-09-03T18:30:50Z",
+  "updatedAt": "2026-09-03T18:30:50Z"
+}

package/rcf/test-suites/ts-032.json

@@ -0,0 +1,50 @@
+{
+  "id": "TS-032",
+  "usId": "US-1103",
+  "title": "rcf doctor Playwright + browser checks on browser-facing projects",
+  "purpose": "Cover the four ACs on US-1103: peer-dependency declaration for @playwright/mcp and playwright as optional peers, the three doctor checks reporting fix lines on a browser-facing project, the skip line on an API-only project, and the --check override running one of the three checks on demand.",
+  "testLevel": "integration",
+  "acIds": [
+    "AC-1103-1",
+    "AC-1103-2",
+    "AC-1103-3",
+    "AC-1103-4"
+  ],
+  "testCases": [
+    {
+      "id": "TC-032-peer-deps-optional",
+      "acId": "AC-1103-1",
+      "description": "packages/rcf-lite/package.json declares @playwright/mcp and playwright as optional peer dependencies",
+      "testPointer": "test/pkg/peer-deps-playwright.test.js::AC-1103-1: @playwright/mcp and playwright are declared as optional peer dependencies",
+      "status": "pending",
+      "scope": "library"
+    },
+    {
+      "id": "TC-032-fix-lines",
+      "acId": "AC-1103-2",
+      "description": "A browser-facing project with the three items missing reports all three fix lines exactly per the spec",
+      "testPointer": "test/cli/doctor-playwright.test.js::doctor: browser-facing project with everything missing reports all three fix lines",
+      "status": "pending",
+      "scope": "runtime"
+    },
+    {
+      "id": "TC-032-skip-line",
+      "acId": "AC-1103-3",
+      "description": "An API-only project prints the skip line and does not run the three checks",
+      "testPointer": "test/cli/doctor-playwright.test.js::doctor: API-only project prints the skip line and does NOT run the three checks",
+      "status": "pending",
+      "scope": "runtime"
+    },
+    {
+      "id": "TC-032-check-override",
+      "acId": "AC-1103-4",
+      "description": "--check playwright-present on an API-only project overrides the skip and runs the check",
+      "testPointer": "test/cli/doctor-playwright.test.js::doctor --check playwright-present on an API-only project runs the check anyway (spec 3.5)",
+      "status": "pending",
+      "scope": "runtime"
+    }
+  ],
+  "status": "draft",
+  "createdAt": "2026-09-03T18:30:50Z",
+  "updatedAt": "2026-09-03T18:30:50Z"
+}

package/rcf/test-suites/ts-033.json

@@ -0,0 +1,83 @@
+{
+  "id": "TS-033",
+  "usId": "US-1104",
+  "title": "rcf init Playwright MCP entry write only when no scope-visible entry exists",
+  "purpose": "Cover the five ACs on US-1104: signature-based project-scope detection leaves a pre-existing entry alone, the injected probe drives the four downstream branches (none/found/inconclusive/CLI-absent), the distinct 'playwright-rcf' entry has the exact shape, --no-playwright-mcp suppresses the write, and doctor's redundant-entry probe fires only on browser-facing projects.",
+  "testLevel": "integration",
+  "acIds": [
+    "AC-1104-1",
+    "AC-1104-2",
+    "AC-1104-3",
+    "AC-1104-4",
+    "AC-1104-5"
+  ],
+  "testCases": [
+    {
+      "id": "TC-033-project-scope-signature-left-alone",
+      "acId": "AC-1104-1",
+      "description": "A pre-existing project-scope Playwright signature leaves .mcp.json untouched and prints the 'left alone' line",
+      "testPointer": "test/cli/init-playwright.test.js::init: existing project-scope Playwright signature -> left alone (spec 4.1)",
+      "status": "pending",
+      "scope": "runtime"
+    },
+    {
+      "id": "TC-033-probe-none-writes-distinct",
+      "acId": "AC-1104-2",
+      "description": "Probe returning 'none' drives the distinct playwright-rcf project-scope write branch",
+      "testPointer": "test/cli/init-playwright.test.js::init: fresh project + probe=none -> writes distinctly named playwright-rcf entry",
+      "status": "pending",
+      "scope": "library"
+    },
+    {
+      "id": "TC-033-probe-found-leaves-alone",
+      "acId": "AC-1104-2",
+      "description": "Probe returning 'found' at user scope leaves .mcp.json alone with the 'already registered ... in Claude Code' line",
+      "testPointer": "test/cli/init-playwright.test.js::init: probe=found at user scope -> left alone; no project entry written (spec 4.2)",
+      "status": "pending",
+      "scope": "library"
+    },
+    {
+      "id": "TC-033-probe-inconclusive-writes-with-notice",
+      "acId": "AC-1104-2",
+      "description": "Probe returning 'inconclusive' writes the distinct entry and prints the could-not-probe notice (covers both CLI-absent and unparseable branches via the injected probe result)",
+      "testPointer": "test/cli/init-playwright.test.js::init: probe=inconclusive -> writes playwright-rcf entry AND prints the could-not-probe notice (spec 4.3)",
+      "status": "pending",
+      "scope": "library"
+    },
+    {
+      "id": "TC-033-distinct-entry-shape",
+      "acId": "AC-1104-3",
+      "description": "The written playwright-rcf entry equals { type:'stdio', command:'npx', args:['-y', '@playwright/mcp@<version>'], env:{} }",
+      "testPointer": "test/cli/init-playwright.test.js::init: fresh project + probe=none -> writes distinctly named playwright-rcf entry",
+      "status": "pending",
+      "scope": "runtime"
+    },
+    {
+      "id": "TC-033-no-playwright-mcp-suppresses-write",
+      "acId": "AC-1104-4",
+      "description": "--no-playwright-mcp suppresses the write; the probe still runs but no Playwright entry is created",
+      "testPointer": "test/cli/init-playwright.test.js::init --no-playwright-mcp: probe still runs, but no Playwright entry is written",
+      "status": "pending",
+      "scope": "runtime"
+    },
+    {
+      "id": "TC-033-redundant-fires-browser-facing",
+      "acId": "AC-1104-5",
+      "description": "playwright-mcp-redundant fires when project + user both declare Playwright on a browser-facing project",
+      "testPointer": "test/cli/doctor-playwright.test.js::doctor: playwright-mcp-redundant fires when project + user both declare Playwright (browser-facing only)",
+      "status": "pending",
+      "scope": "runtime"
+    },
+    {
+      "id": "TC-033-redundant-quiet-on-api-only",
+      "acId": "AC-1104-5",
+      "description": "playwright-mcp-redundant does NOT fire on an API-only project",
+      "testPointer": "test/cli/doctor-playwright.test.js::doctor: playwright-mcp-redundant does NOT fire on an API-only project (spec 4.5)",
+      "status": "pending",
+      "scope": "runtime"
+    }
+  ],
+  "status": "draft",
+  "createdAt": "2026-09-03T18:30:50Z",
+  "updatedAt": "2026-09-03T18:30:50Z"
+}

package/rcf/user-stories/us-1101.json

@@ -0,0 +1,51 @@
+{
+  "usId": "US-1101",
+  "prdId": "PRD-001",
+  "reqId": "REQ-011",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Verify pins the Playwright MCP version and prints it in preflight",
+  "asA": "operator running rcf verify as the ship gate",
+  "iWant": "the verify launcher to provision a version-pinned @playwright/mcp instead of @latest, print the effective pin in preflight, record it in the report, and honour an emergency override with a loud stderr notice",
+  "soThat": "a newly published Playwright MCP release cannot become a silent runtime change on the next verify run, and every report artefact carries the exact browser tooling version the pass ran against",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-1101-1",
+      "description": "packages/rcf-lite/src/verify/engine/launcher.js exports a PLAYWRIGHT_MCP_VERSION constant, and DEFAULT_MCP_CONFIG.args composes @playwright/mcp@<PLAYWRIGHT_MCP_VERSION> instead of @playwright/mcp@latest.",
+      "given": "the rcf-lite source at HEAD",
+      "when": "the launcher module is imported",
+      "then": "PLAYWRIGHT_MCP_VERSION resolves to a semver string and DEFAULT_MCP_CONFIG.mcpServers.playwright.args contains the exact-pinned @playwright/mcp@<version> token, with no @latest anywhere in the module",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-1101-2",
+      "description": "rcf verify run prints one preflight line naming the effective @playwright/mcp pin on stderr; the line is not suppressed by --quiet.",
+      "given": "a browser-facing fixture project and a stubbed verify launcher",
+      "when": "rcf verify run is invoked with valid required flags",
+      "then": "stderr contains one line matching /^Playwright MCP: pinned to @playwright\\/mcp@/ carrying the effective pin",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-1101-3",
+      "description": "rcf verify run --playwright-mcp-version <semver> overrides the pinned constant for one run, prints a loud stderr override notice, and records the effective pin on the report as runStats.playwrightMcpVersion. A non-semver value refuses with exit 2.",
+      "given": "the same fixture, run with --playwright-mcp-version 0.0.99",
+      "when": "the run completes",
+      "then": "stderr carries one line matching /^Playwright MCP: OVERRIDE @playwright\\/mcp@0\\.0\\.99/, the report's run.runStats.playwrightMcpVersion equals 0.0.99, and rerunning with --playwright-mcp-version notasemver exits 2 with a semver-shape error",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-1101-4",
+      "description": "Even when no override fires, the report records the effective (default) pin as run.runStats.playwrightMcpVersion so a report re-render tells the operator what browser tooling the pass ran against.",
+      "given": "a completed verify run with no override",
+      "when": "the report JSON is inspected",
+      "then": "report.run.runStats.playwrightMcpVersion equals PLAYWRIGHT_MCP_VERSION",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "createdAt": "2026-09-03T16:56:00Z",
+  "updatedAt": "2026-09-03T16:56:00Z"
+}

package/rcf/user-stories/us-1102.json

@@ -0,0 +1,60 @@
+{
+  "usId": "US-1102",
+  "prdId": "PRD-001",
+  "reqId": "REQ-011",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "Application-spa declares browserSurface and delivery-ci-workflows materialises an e2e CI job",
+  "asA": "operator applying the application-spa and delivery-ci-workflows blueprints",
+  "iWant": "the SPA blueprint's manifest to declare a browserSurface field, its browser-facing acceptance criteria and e2e test-case template to ship, and the delivery-ci-workflows materialiser to wire a distinct e2e CI job when at least one applied blueprint carries a browserSurface",
+  "soThat": "e2e is a first-class declared test level in the chain, and browser-facing projects get a distinct pull-request-checks e2e job while API-only projects keep the existing workflow shape verbatim",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-1102-1",
+      "description": "blueprints/application-spa/blueprint.json is at version 1.4.0 and carries a top-level browserSurface object with declared: true; the object also carries routes[] and themes[] as reference hint arrays.",
+      "given": "the SPA blueprint at HEAD",
+      "when": "blueprint.json is inspected",
+      "then": "version equals 1.4.0 and .browserSurface.declared is true",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-1102-2",
+      "description": "The SPA blueprint contributes two new browser-facing acceptance criteria in the 1101 to 1899 band (existing 1131 and 1132 are already occupied by unrelated 1.3.x contributions): US-1134 binds an e2e AC on application-spa-REQ-011 (iconography), US-1135 binds an e2e AC on application-spa-REQ-009 (user arrival and auth surfaces); a paste-in assets/tc-templates/e2e.md test-case template ships and names the browser-verify TAC as its driver seam.",
+      "given": "the SPA blueprint at HEAD",
+      "when": "blueprints/application-spa/contributions/user-stories/ and blueprints/application-spa/assets/tc-templates/ are inspected",
+      "then": "application-spa-us-1134.json and application-spa-us-1135.json exist, each binds one AC whose scope is deployed and whose description names an e2e observable at a rendered browser surface; assets/tc-templates/e2e.md exists and references TAC-208",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-1102-3",
+      "description": "blueprints/delivery-ci-workflows/blueprint.json is at version 2.2.0 and contributes a new US-6124 whose AC binds the elicited e2e check to a distinct e2e CI job that runs project testLevel: e2e cases against a local preview or --parity-env runtime, uploads browser artefacts, and reports a distinct row in the aggregate pipeline report.",
+      "given": "the delivery-ci-workflows blueprint at HEAD",
+      "when": "blueprint.json and contributions/user-stories/delivery-ci-workflows-us-6124.json are inspected",
+      "then": "version equals 2.2.0 and the US-6124 record binds an AC-6124-1 whose description names the four points above",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-1102-4",
+      "description": "The illustrative GHA workflow at blueprints/delivery-ci-workflows/assets/ci-provider-examples/github-actions/pull-request-checks.yml carries a documented e2e job, and the alternate-provider notes file at ../notes.md carries one line per provider translating the same four points.",
+      "given": "the delivery-ci-workflows blueprint at HEAD",
+      "when": "the illustrative workflow file is inspected",
+      "then": "the workflow declares an e2e job as an example, and notes.md contains one line per provider (GitLab CI, CircleCI, Buildkite, Jenkins) naming the four points",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-1102-5",
+      "description": "Applying application-spa v1.4.0 to a scratch project produces a manifest that still validates against rcf-schemas 0.5.1; the applied blueprint record carries no new field, and doctor and the delivery-ci-workflows materialiser both read browserSurface from the applied record's source blueprint.json via the existing manifest.blueprints[].source reference.",
+      "given": "a scratch project created by rcf init with application-spa v1.4.0 applied",
+      "when": "the resulting rcf/manifest.json is validated against the shipped schemas",
+      "then": "validation passes and no browserSurface key appears on the applied blueprint record itself",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "createdAt": "2026-09-03T16:56:00Z",
+  "updatedAt": "2026-09-03T16:56:00Z"
+}

package/rcf/user-stories/us-1103.json

@@ -0,0 +1,51 @@
+{
+  "usId": "US-1103",
+  "prdId": "PRD-001",
+  "reqId": "REQ-011",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "rcf doctor checks Playwright and a browser on browser-facing projects and skips them otherwise",
+  "asA": "operator running rcf doctor on either a browser-facing or an API-only project",
+  "iWant": "doctor to run playwright-present, browser-present, and playwright-mcp-reachable checks when at least one applied blueprint declares a browserSurface, and to skip all three with one printed reason line otherwise",
+  "soThat": "browser-facing projects surface missing Playwright, missing browser, or an unreachable @playwright/mcp with actionable fix lines, while API-only projects are not asked to install a browser stack they will never use",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-1103-1",
+      "description": "packages/rcf-lite/package.json declares @playwright/mcp and playwright as optional peer dependencies (peerDependenciesMeta.<pkg>.optional: true). npm and pnpm do not fail install when the peers are absent.",
+      "given": "packages/rcf-lite at HEAD",
+      "when": "package.json is inspected",
+      "then": ".peerDependencies['@playwright/mcp'] and .peerDependencies.playwright are declared and .peerDependenciesMeta.<pkg>.optional is true for both",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-1103-2",
+      "description": "On a browser-facing fixture project (application-spa v1.4.0 applied), rcf doctor runs playwright-present, browser-present, and playwright-mcp-reachable; each check emits at most one fix line naming the exact remedy per the spec's fix-line table.",
+      "given": "a browser-facing fixture with no @playwright/mcp installed",
+      "when": "rcf doctor is run",
+      "then": "the three checks appear in the drift output and their fix lines match the spec's fix-line strings",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-1103-3",
+      "description": "On an API-only fixture project (application-api-rest applied, no browser-facing blueprint), rcf doctor prints one line naming the three skipped checks and their skip reason. The line is not suppressed by --quiet.",
+      "given": "an API-only fixture project",
+      "when": "rcf doctor is run",
+      "then": "stdout contains exactly one line 'rcf doctor: skipping playwright-present, browser-present, playwright-mcp-reachable (no applied blueprint declares a browser surface).'",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-1103-4",
+      "description": "The three checks are legal values of --check <check>[,check]; passing one explicitly on a non-browser project overrides the skip and runs it.",
+      "given": "an API-only fixture project",
+      "when": "rcf doctor --check playwright-present is run",
+      "then": "the playwright-present check runs and reports its result rather than being skipped",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "createdAt": "2026-09-03T16:56:00Z",
+  "updatedAt": "2026-09-03T16:56:00Z"
+}

package/rcf/user-stories/us-1104.json

@@ -0,0 +1,60 @@
+{
+  "usId": "US-1104",
+  "prdId": "PRD-001",
+  "reqId": "REQ-011",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "rcf init writes a Playwright MCP entry only when no scope-visible entry exists",
+  "asA": "operator running rcf init on a project with or without an ambient Playwright MCP entry",
+  "iWant": "init to detect a project-scope Playwright signature by command-tail matching, probe user scope via claude mcp list where the Claude Code harness is on PATH, write a distinctly named playwright-rcf project-scope entry only when it cannot prove any Playwright entry exists at any scope, and honour --no-playwright-mcp",
+  "soThat": "an operator with a user-scope Playwright MCP entry in Claude Code keeps it (init never shadows it) and an operator with none gets a working project-scope entry that shadows nothing at any scope by naming convention",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-1104-1",
+      "description": "When the project-scope .mcp.json carries a Playwright signature (any entry key whose args contain a string matching /^@playwright\\/mcp(@|$)/), rcf init writes no Playwright entry and prints the 'left alone' line naming the key.",
+      "given": "a fixture project with a pre-existing mcpServers entry whose args include @playwright/mcp",
+      "when": "rcf init is run",
+      "then": "the .mcp.json keys are unchanged and stdout carries the line 'Playwright MCP: already registered in .mcp.json under key '<name>' at project scope, left alone.'",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-1104-2",
+      "description": "When the project-scope .mcp.json carries no Playwright signature, init probes the harness via an injectable seam (default: claude mcp list; 5 second timeout; text output parsed for the signature). Probe results 'entry found at user scope', 'no entry anywhere', 'CLI absent or non-zero', and 'output unparseable' each drive the correct downstream branch.",
+      "given": "a fixture project and a stubbed probe returning each of the four probe results in turn",
+      "when": "rcf init runs against each probe result",
+      "then": "'entry found' leaves .mcp.json untouched and prints the 'already registered at <scope> scope in Claude Code' line; 'no entry anywhere' writes the distinct playwright-rcf project-scope entry; both 'CLI absent or non-zero' and 'output unparseable' treat the probe as inconclusive and write the distinct playwright-rcf entry with the 'could not probe' notice",
+      "testable": true,
+      "scope": "library"
+    },
+    {
+      "id": "AC-1104-3",
+      "description": "The playwright-rcf entry, when written, has key 'playwright-rcf' distinct from 'playwright', command 'npx', args ['-y', '@playwright/mcp@<PLAYWRIGHT_MCP_VERSION>'] and empty env.",
+      "given": "a fixture project with no ambient Playwright entry anywhere",
+      "when": "rcf init runs with the probe stubbed inconclusive",
+      "then": ".mcp.json.mcpServers['playwright-rcf'] equals { type: 'stdio', command: 'npx', args: ['-y', '@playwright/mcp@<version>'], env: {} }",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-1104-4",
+      "description": "rcf init --no-playwright-mcp suppresses the write step for the Playwright entry entirely; the probe still runs so the print-out remains honest, but no .mcp.json Playwright entry is created and no existing one is touched.",
+      "given": "a fixture project with no ambient Playwright entry anywhere",
+      "when": "rcf init --no-playwright-mcp is run",
+      "then": ".mcp.json.mcpServers contains no key matching a Playwright signature",
+      "testable": true,
+      "scope": "runtime"
+    },
+    {
+      "id": "AC-1104-5",
+      "description": "rcf doctor's playwright-mcp-redundant check fires only on browser-facing projects; when the project-scope .mcp.json carries a Playwright signature AND the probe reports a Playwright signature at user scope, doctor reports drift with the removal line naming --no-playwright-mcp and the hand-edit path. --fix does not repair this drift.",
+      "given": "a browser-facing fixture with a project-scope playwright entry and a stubbed probe reporting user-scope",
+      "when": "rcf doctor is run",
+      "then": "the drift output contains one 'playwright-mcp-redundant' entry naming the two remedies and no --fix action is applied",
+      "testable": true,
+      "scope": "runtime"
+    }
+  ],
+  "createdAt": "2026-09-03T16:56:00Z",
+  "updatedAt": "2026-09-03T16:56:00Z"
+}

package/releases/releases.yaml

@@ -40,8 +40,18 @@
 # `npm install rcf-lite`.
 
 feedVersion: 1
-latest: "0.16.0"
+latest: "0.17.0"
 releases:
+  - version: "0.17.0"
+    date: "2026-09-04"
+    breaking: false
+    headlines:
+      - "rcf verify now pins the Playwright MCP browser tooling to a specific version, prints the effective pin on preflight and lands it on the run report, and takes a one-run override for emergency use."
+      - "rcf doctor grows four checks for browser-facing projects (Playwright installed, a browser available, the Playwright MCP reachable, and no shadowed duplicate entry), routed by an applied blueprint declaring a browser surface; API-only projects see one skip line."
+      - "rcf init writes a Playwright MCP entry only when no scope-visible one exists; when it cannot prove absence it writes a distinctly named playwright-rcf project-scope entry, and --no-playwright-mcp opts out entirely. application-spa v1.4.0 and delivery-ci-workflows v2.2.0 ship the paired browser stories and the illustrative e2e job as a documentation contract."
+    minAgentAction: null
+    notesUrl: "https://stravica.ai/docs/rcf/changelog/"
+
   - version: "0.16.0"
     date: "2026-09-03"
     breaking: false

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'