session-orchestrator 3.16.0

package/scripts/lib/validate/check-path-utils-canary.mjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+/**
+ * check-path-utils-canary.mjs — Assert that validatePathInsideProject is exported
+ * from path-utils.mjs and is imported at all three canonical callsites.
+ *
+ * Rationale: validatePathInsideProject is the canonical two-phase path-traversal +
+ * symlink-escape guard (Phase 1 lexical isPathInside, Phase 2 realpathSync-when-exists).
+ * It was extracted in #402 from three inline guard sites to prevent duplication drift.
+ * Without this canary, a refactor that removes the import at any callsite silently
+ * reverts to no guard (or re-introduces an inline one), which is a CWE-23 regression
+ * the test suite will not catch directly.
+ *
+ * Regression class this prevents (not covered by existing 39 canaries):
+ *   - Removal of `validatePathInsideProject` import from config/test.mjs,
+ *     profiles/schema.mjs, or playwright-driver/runner.mjs without a test failing.
+ *   - Removal of the export from path-utils.mjs while callsites still compile
+ *     (the call would simply return undefined and silently skip validation).
+ *
+ * Checks:
+ *   1. path-utils.mjs exports validatePathInsideProject (export keyword present)
+ *   2. scripts/lib/config/test.mjs imports validatePathInsideProject from path-utils
+ *   3. scripts/lib/profiles/schema.mjs imports validatePathInsideProject from path-utils
+ *   4. scripts/lib/playwright-driver/runner.mjs imports validatePathInsideProject from path-utils
+ *
+ * MAINTAINER NOTE: This canary locks in WHICH production modules use the helper.
+ * If a callsite is intentionally removed (e.g. module deprecation), DELETE the matching
+ * Check N block from this file — this is not a "fix the canary to be passing" situation.
+ * Conversely, when a NEW callsite is added, append a corresponding Check N+1 block.
+ *
+ * Exit codes:
+ *   0 — all checks passed
+ *   1 — at least one check failed
+ *
+ * Usage:
+ *   node scripts/lib/validate/check-path-utils-canary.mjs <plugin-root>
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const pluginRoot = process.argv[2];
+if (!pluginRoot) {
+  console.error('Usage: check-path-utils-canary.mjs <plugin-root>');
+  process.exit(1);
+}
+
+let passed = 0;
+let failed = 0;
+
+function pass(msg) { console.log(`  PASS: ${msg}`); passed += 1; }
+function fail(msg) { console.log(`  FAIL: ${msg}`); failed += 1; }
+
+function readFile(relPath) {
+  const abs = join(pluginRoot, relPath);
+  if (!existsSync(abs)) return null;
+  return readFileSync(abs, 'utf8');
+}
+
+// ---------------------------------------------------------------------------
+// Check 1: path-utils.mjs exports validatePathInsideProject
+// ---------------------------------------------------------------------------
+
+console.log('--- Check 1: path-utils.mjs exports validatePathInsideProject ---');
+
+const pathUtils = readFile('scripts/lib/path-utils.mjs');
+if (pathUtils === null) {
+  fail('scripts/lib/path-utils.mjs does not exist');
+} else if (/export function validatePathInsideProject/.test(pathUtils)) {
+  pass('path-utils.mjs exports validatePathInsideProject');
+} else {
+  fail('path-utils.mjs does not export validatePathInsideProject — two-phase guard helper is missing');
+}
+
+// ---------------------------------------------------------------------------
+// Check 2: config/test.mjs imports validatePathInsideProject
+// ---------------------------------------------------------------------------
+
+console.log('');
+console.log('--- Check 2: scripts/lib/config/test.mjs imports validatePathInsideProject ---');
+
+const configTest = readFile('scripts/lib/config/test.mjs');
+if (configTest === null) {
+  fail('scripts/lib/config/test.mjs does not exist');
+} else if (/import\s*\{[^}]*validatePathInsideProject[^}]*\}\s*from\s*['"][^'"]*path-utils/.test(configTest)) {
+  pass('config/test.mjs imports validatePathInsideProject from path-utils');
+} else {
+  fail('config/test.mjs does not import validatePathInsideProject from path-utils — SEC-IR-LOW-2 profiles-path guard may be missing');
+}
+
+// ---------------------------------------------------------------------------
+// Check 3: profiles/schema.mjs imports validatePathInsideProject
+// ---------------------------------------------------------------------------
+
+console.log('');
+console.log('--- Check 3: scripts/lib/profiles/schema.mjs imports validatePathInsideProject ---');
+
+const profilesSchema = readFile('scripts/lib/profiles/schema.mjs');
+if (profilesSchema === null) {
+  fail('scripts/lib/profiles/schema.mjs does not exist');
+} else if (/import\s*\{[^}]*validatePathInsideProject[^}]*\}\s*from\s*['"][^'"]*path-utils/.test(profilesSchema)) {
+  pass('profiles/schema.mjs imports validatePathInsideProject from path-utils');
+} else {
+  fail('profiles/schema.mjs does not import validatePathInsideProject from path-utils — SEC-IR-LOW-3 rubric path guard may be missing');
+}
+
+// ---------------------------------------------------------------------------
+// Check 4: playwright-driver/runner.mjs imports validatePathInsideProject
+// ---------------------------------------------------------------------------
+
+console.log('');
+console.log('--- Check 4: scripts/lib/playwright-driver/runner.mjs imports validatePathInsideProject ---');
+
+const runnerMjs = readFile('scripts/lib/playwright-driver/runner.mjs');
+if (runnerMjs === null) {
+  fail('scripts/lib/playwright-driver/runner.mjs does not exist');
+} else if (/import\s*\{[^}]*validatePathInsideProject[^}]*\}\s*from\s*['"][^'"]*path-utils/.test(runnerMjs)) {
+  pass('playwright-driver/runner.mjs imports validatePathInsideProject from path-utils');
+} else {
+  fail('playwright-driver/runner.mjs does not import validatePathInsideProject from path-utils — #398 runDir traversal guard may be missing');
+}
+
+// ---------------------------------------------------------------------------
+// Check 5: #477 cross-repo sink scripts import validatePathInsideProject
+// ---------------------------------------------------------------------------
+
+console.log('');
+console.log('--- Check 5: #477 cross-repo sink scripts import validatePathInsideProject ---');
+
+const sinkScripts = [
+  'scripts/promote-vault-strict.mjs',
+  'scripts/run-migrate-v2-cross-repo.mjs',
+  'scripts/vault-integration-watcher.mjs',
+];
+
+for (const relPath of sinkScripts) {
+  const src = readFile(relPath);
+  if (src === null) {
+    fail(`${relPath} does not exist`);
+  } else if (/import\s*\{[^}]*validatePathInsideProject[^}]*\}\s*from\s*['"][^'"]*path-utils/.test(src)) {
+    pass(`${relPath} imports validatePathInsideProject from path-utils (#477 confinement guard)`);
+  } else {
+    fail(`${relPath} does not import validatePathInsideProject from path-utils — #477 path-confinement guard is missing`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Check 6: #544 M3 memory-proposals modules import validatePathInsideProject
+// ---------------------------------------------------------------------------
+
+console.log('');
+console.log('--- Check 6: #544 M3 memory-proposals modules import validatePathInsideProject ---');
+
+const memoryProposalsModules = [
+  'scripts/lib/memory-proposals/store.mjs',
+  'scripts/lib/memory-proposals/sink.mjs',
+];
+
+for (const relPath of memoryProposalsModules) {
+  const src = readFile(relPath);
+  if (src === null) {
+    fail(`${relPath} does not exist`);
+  } else if (/import\s*\{[^}]*validatePathInsideProject[^}]*\}\s*from\s*['"][^'"]*path-utils/.test(src)) {
+    pass(`${relPath} imports validatePathInsideProject from path-utils (#544 M3 canonicalization)`);
+  } else {
+    fail(`${relPath} does not import validatePathInsideProject from path-utils — #544 M3 path-canonicalization guard is missing`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Summary
+// ---------------------------------------------------------------------------
+
+console.log('');
+console.log(`Results: ${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);

package/scripts/lib/validate/check-peekaboo-driver-canary.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+/**
+ * check-peekaboo-driver-canary.mjs — Forbid peekaboo-mcp references in
+ * skills/peekaboo-driver/** and scripts/lib/test-runner/**.
+ *
+ * Rationale: The peekaboo-driver skill wraps the `peekaboo` binary (steipete,
+ * MIT, macOS-only) directly via the CLI. Introducing an MCP adapter layer
+ * (peekaboo-mcp) would add unnecessary token overhead and couples the driver
+ * to a specific MCP transport. All invocations MUST use the raw binary.
+ *
+ * Forbidden pattern:
+ *   - peekaboo-mcp   (the string; NOT bare "peekaboo" which is the valid binary name)
+ *
+ * Allowed patterns:
+ *   - mentions inside lines that contain documentation markers explaining
+ *     WHY the pattern is forbidden, not actual imports or usage.
+ *
+ * Detection strategy:
+ *   - Scan all .md, .mjs, .js, .ts files under the two forbidden dirs
+ *   - Flag any line containing the forbidden pattern
+ *   - Skip lines that also contain a documentation marker
+ *     (HARD-GATE, check-peekaboo-driver-canary, R5 grep-canary, canary-exempt)
+ *
+ * Exit codes:
+ *   0 — no violations
+ *   1 — at least one violation found
+ *
+ * Usage:
+ *   node scripts/lib/validate/check-peekaboo-driver-canary.mjs <plugin-root>
+ *
+ * Test approach (for W4):
+ *   - Verify exit 0 when scan roots are clean or absent
+ *   - Verify exit 1 + FAIL line when a scanned file contains a bare forbidden pattern
+ *   - Verify that lines containing HARD-GATE are skipped (no false positives on SKILL.md)
+ *   - Verify non-scanned file extensions (e.g. .yaml) are not processed
+ */
+
+import { readdirSync, readFileSync, statSync, existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+const pluginRoot = process.argv[2];
+if (!pluginRoot) {
+  console.error('Usage: check-peekaboo-driver-canary.mjs <plugin-root>');
+  process.exit(1);
+}
+
+let passed = 0;
+let failed = 0;
+
+function pass(msg) { console.log(`  PASS: ${msg}`); passed += 1; }
+function fail(msg) { console.log(`  FAIL: ${msg}`); failed += 1; }
+
+console.log('--- Check 1: peekaboo-mcp canary (R5 — forbidden in peekaboo-driver + helpers) ---');
+
+const FORBIDDEN_PATTERNS = [
+  /peekaboo-mcp/,
+];
+
+// Lines that mention the forbidden pattern AS PART OF documenting the rule
+// itself are skipped. Any of these markers on the same line indicates a
+// documentation context, not an actual import or usage reference.
+const DOCUMENTATION_MARKERS = [
+  /HARD-GATE/,
+  /check-peekaboo-driver-canary/,
+  /R5 grep-canary/,
+  /R5 hard-gate/,
+  // SEC-PD-LOW-2: canary-exempt was an unguarded bypass keyword (security_control_bypass).
+  // HARD-GATE remains for legitimate documenting-the-rule context.
+  // "Never peekaboo-mcp" — anti-pattern prohibition in soul.md / SKILL.md
+  /Never.*peekaboo-mcp/,
+  // "blocks peekaboo-mcp" — rule-enforcement documentation
+  /blocks.*peekaboo-mcp/,
+  // Markdown table rows listing peekaboo-mcp as a "DO NOT USE" item
+  /DO NOT USE.*peekaboo-mcp|peekaboo-mcp.*DO NOT USE/,
+];
+
+const SCAN_ROOTS = [
+  'skills/peekaboo-driver',
+  'scripts/lib/test-runner',
+  'scripts/lib/profiles',
+];
+
+const SCAN_EXTENSIONS = ['.md', '.mjs', '.js', '.ts'];
+
+/**
+ * Recursively walk a directory and return all file paths with the allowed extensions.
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function walk(dir) {
+  const results = [];
+  if (!existsSync(dir)) return results;
+  for (const name of readdirSync(dir)) {
+    const full = join(dir, name);
+    const st = statSync(full);
+    if (st.isDirectory()) {
+      results.push(...walk(full));
+    } else if (SCAN_EXTENSIONS.some((ext) => name.endsWith(ext))) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+const violations = [];
+
+for (const rel of SCAN_ROOTS) {
+  const absDir = join(pluginRoot, rel);
+  if (!existsSync(absDir)) {
+    pass(`${rel}/ does not exist yet (no scan needed)`);
+    continue;
+  }
+  const files = walk(absDir);
+  let fileViolations = 0;
+  for (const file of files) {
+    const text = readFileSync(file, 'utf8');
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i += 1) {
+      const line = lines[i];
+      const matchesForbidden = FORBIDDEN_PATTERNS.some((p) => p.test(line));
+      if (!matchesForbidden) continue;
+      const isDocumentation = DOCUMENTATION_MARKERS.some((p) => p.test(line));
+      if (isDocumentation) continue;
+      violations.push({
+        file: relative(pluginRoot, file),
+        line: i + 1,
+        text: line.trim().slice(0, 160),
+      });
+      fileViolations += 1;
+    }
+  }
+  if (fileViolations === 0) {
+    pass(`${rel}/ scanned (${files.length} files): no peekaboo-mcp references`);
+  }
+}
+
+if (violations.length === 0) {
+  pass(`peekaboo-mcp canary clean across all ${SCAN_ROOTS.length} scan roots`);
+} else {
+  for (const v of violations) {
+    fail(
+      `${v.file}:${v.line} — '${v.text}' (matches forbidden pattern; ` +
+      `if intentional documentation, add a HARD-GATE marker on the line)`,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Check 2–4: anchor canaries — required vocabulary in SKILL.md (#401 GAP-Q4-5)
+// ---------------------------------------------------------------------------
+
+console.log('');
+console.log('--- Check 2: peekaboo SKILL.md anchor — "thin executor" (driver identity) ---');
+
+const SKILL_MD = join(pluginRoot, 'skills/peekaboo-driver/SKILL.md');
+
+if (!existsSync(SKILL_MD)) {
+  // SKILL.md absent in this plugin root — same graceful handling as absent scan roots in Check 1.
+  pass('skills/peekaboo-driver/SKILL.md does not exist yet (no anchor checks needed)');
+
+  console.log('');
+  console.log('--- Check 3: peekaboo SKILL.md anchor — "$MISSING" (permission-flow vocab) ---');
+  pass('skills/peekaboo-driver/SKILL.md does not exist yet (no anchor checks needed)');
+
+  console.log('');
+  console.log('--- Check 4: peekaboo SKILL.md anchor — "status: stub" (glass-modifiers v1 schema marker) ---');
+  pass('skills/peekaboo-driver/SKILL.md does not exist yet (no anchor checks needed)');
+} else {
+  const skillText = readFileSync(SKILL_MD, 'utf8');
+
+  // Anchor 1: "thin executor" — driver identity vocabulary
+  if (/thin executor/.test(skillText)) {
+    pass('SKILL.md contains required anchor "thin executor" (driver identity)');
+  } else {
+    fail('SKILL.md missing required anchor "thin executor" — driver identity vocabulary must be present');
+  }
+
+  console.log('');
+  console.log('--- Check 3: peekaboo SKILL.md anchor — "$MISSING" (permission-flow vocab) ---');
+
+  // Anchor 2: "$MISSING" — permission-flow vocabulary
+  if (/\$MISSING/.test(skillText)) {
+    pass('SKILL.md contains required anchor "$MISSING" (permission-flow vocabulary)');
+  } else {
+    fail('SKILL.md missing required anchor "$MISSING" — permission-flow vocabulary must be present');
+  }
+
+  console.log('');
+  console.log('--- Check 4: peekaboo SKILL.md anchor — "status: stub" (glass-modifiers v1 schema marker) ---');
+
+  // Anchor 3: "status: stub" — glass-modifiers v1 schema marker
+  if (/"status":\s*"stub"/.test(skillText)) {
+    pass('SKILL.md contains required anchor "status: stub" (glass-modifiers v1 schema marker)');
+  } else {
+    fail('SKILL.md missing required anchor "status: stub" — glass-modifiers v1 schema marker must be present');
+  }
+}
+
+console.log('');
+console.log(`Results: ${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);

package/scripts/lib/validate/check-pi-package.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// check-pi-package.mjs — Validate the Pi package manifest in package.json.
+// Usage: check-pi-package.mjs <plugin-root>
+// Exit 0 = all checks passed, 1 = at least one failure.
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+
+const pluginRoot = process.argv[2];
+if (!pluginRoot) {
+  console.error('Usage: check-pi-package.mjs <plugin-root>');
+  process.exit(1);
+}
+
+let passed = 0;
+let failed = 0;
+
+function pass(msg) { console.log(`  PASS: ${msg}`); passed += 1; }
+function fail(msg) { console.log(`  FAIL: ${msg}`); failed += 1; }
+
+function isDir(p) {
+  try { return statSync(p).isDirectory(); } catch { return false; }
+}
+
+function isFile(p) {
+  try { return statSync(p).isFile(); } catch { return false; }
+}
+
+function stripLeadingDotSlash(p) {
+  return p.replace(/^\.\//, '');
+}
+
+function matchesSimpleGlob(relPath) {
+  if (!relPath.includes('*')) {
+    return existsSync(join(pluginRoot, stripLeadingDotSlash(relPath)));
+  }
+
+  const clean = stripLeadingDotSlash(relPath);
+  const dir = dirname(clean);
+  const base = clean.slice(dir.length + 1);
+  const [prefix, suffix] = base.split('*');
+  const absDir = join(pluginRoot, dir);
+  if (!isDir(absDir)) return false;
+  return readdirSync(absDir).some((entry) => entry.startsWith(prefix) && entry.endsWith(suffix));
+}
+
+function validatePathArray(pkg, field) {
+  const values = pkg.pi?.[field];
+  if (!Array.isArray(values) || values.length === 0) {
+    fail(`pi.${field} must be a non-empty array`);
+    return;
+  }
+
+  for (const value of values) {
+    if (typeof value !== 'string' || value.length === 0) {
+      fail(`pi.${field} entry must be a non-empty string`);
+      continue;
+    }
+    if (!value.startsWith('./')) {
+      fail(`pi.${field} entry must be repo-relative and start with ./: ${value}`);
+      continue;
+    }
+    if (matchesSimpleGlob(value)) {
+      pass(`pi.${field} entry resolves: ${value}`);
+    } else {
+      fail(`pi.${field} entry does not resolve: ${value}`);
+    }
+  }
+}
+
+console.log('--- Check 1: package.json pi package manifest ---');
+
+const packageJsonPath = join(pluginRoot, 'package.json');
+let pkg;
+try {
+  pkg = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+} catch (err) {
+  fail(`package.json not found or invalid JSON: ${err.message}`);
+  console.log('');
+  console.log(`Results: ${passed} passed, ${failed} failed`);
+  process.exit(1);
+}
+
+if (Array.isArray(pkg.keywords) && pkg.keywords.includes('pi-package')) {
+  pass('package.json keywords include pi-package');
+} else {
+  fail('package.json keywords must include pi-package');
+}
+
+if (pkg.pi && typeof pkg.pi === 'object' && !Array.isArray(pkg.pi)) {
+  pass('package.json pi manifest is present');
+} else {
+  fail('package.json pi manifest is missing');
+}
+
+validatePathArray(pkg, 'extensions');
+validatePathArray(pkg, 'skills');
+validatePathArray(pkg, 'prompts');
+
+const extensionEntries = Array.isArray(pkg.pi?.extensions) ? pkg.pi.extensions : [];
+const tsExtension = extensionEntries.find((entry) => entry.endsWith('.ts'));
+if (tsExtension && isFile(join(pluginRoot, stripLeadingDotSlash(tsExtension)))) {
+  pass(`Pi extension TypeScript entry exists: ${tsExtension}`);
+} else {
+  fail('pi.extensions must include an existing .ts extension entry');
+}
+
+console.log('');
+console.log(`Results: ${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);

package/scripts/lib/validate/check-pi-prompts.mjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+// check-pi-prompts.mjs — Ensure generated Pi prompt wrappers match commands/*.md.
+// Usage: check-pi-prompts.mjs <plugin-root>
+// Exit 0 = all checks passed, 1 = at least one failure.
+
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const pluginRoot = process.argv[2];
+if (!pluginRoot) {
+  console.error('Usage: check-pi-prompts.mjs <plugin-root>');
+  process.exit(1);
+}
+
+let passed = 0;
+let failed = 0;
+
+function pass(msg) { console.log(`  PASS: ${msg}`); passed += 1; }
+function fail(msg) { console.log(`  FAIL: ${msg}`); failed += 1; }
+
+console.log('--- Check 1: generated Pi prompt wrappers ---');
+
+const generator = join(pluginRoot, 'scripts', 'generate-pi-prompts.mjs');
+if (!existsSync(generator)) {
+  fail('scripts/generate-pi-prompts.mjs exists');
+} else {
+  const result = spawnSync(process.execPath, [generator, '--check'], {
+    cwd: pluginRoot,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (result.status === 0) {
+    pass('pi/prompts/*.md are up to date with commands/*.md');
+  } else {
+    const detail = ((result.stdout ?? '') + (result.stderr ?? '')).trim();
+    fail(`pi prompt wrappers are stale${detail ? `: ${detail}` : ''}`);
+  }
+}
+
+console.log('');
+console.log(`Results: ${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);

package/scripts/lib/validate/check-playwright-mcp-canary.mjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+/**
+ * check-playwright-mcp-canary.mjs — Forbid @playwright/mcp references in
+ * skills/playwright-driver/** and scripts/lib/test-runner/**.
+ *
+ * Rationale: Playwright MCP costs ~4× more tokens per test than the
+ * canonical playwright CLI (Microsoft's own benchmark: ~114K vs ~27K).
+ * The playwright-driver and test-runner stack MUST stay on the CLI.
+ *
+ * Forbidden patterns:
+ *   - @playwright/mcp
+ *   - playwright-mcp
+ *
+ * Allowed patterns:
+ *   - mentions inside lines that contain HARD-GATE markers or other
+ *     canary-exempt tokens — those are documentation blocks explaining
+ *     WHY the pattern is forbidden, not actual imports or usage.
+ *
+ * Detection strategy:
+ *   - Scan all .md, .mjs, .js, .ts files under the two forbidden dirs
+ *   - Flag any line containing one of the forbidden patterns
+ *   - Skip lines that also contain a documentation marker
+ *     (HARD-GATE, check-playwright-mcp-canary, R5 grep-canary, canary-exempt)
+ *
+ * Exit codes:
+ *   0 — no violations
+ *   1 — at least one violation found
+ *
+ * Usage:
+ *   node scripts/lib/validate/check-playwright-mcp-canary.mjs <plugin-root>
+ *
+ * Test approach (for W4):
+ *   - Verify exit 0 when scan roots are clean or absent
+ *   - Verify exit 1 + FAIL line when a scanned file contains a bare forbidden pattern
+ *   - Verify that lines containing HARD-GATE are skipped (no false positives on SKILL.md)
+ *   - Verify non-scanned file extensions (e.g. .yaml) are not processed
+ */
+
+import { readdirSync, readFileSync, statSync, existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+const pluginRoot = process.argv[2];
+if (!pluginRoot) {
+  console.error('Usage: check-playwright-mcp-canary.mjs <plugin-root>');
+  process.exit(1);
+}
+
+let passed = 0;
+let failed = 0;
+
+function pass(msg) { console.log(`  PASS: ${msg}`); passed += 1; }
+function fail(msg) { console.log(`  FAIL: ${msg}`); failed += 1; }
+
+console.log('--- Check 1: playwright-mcp canary (R5 — forbidden in driver + helpers) ---');
+
+const FORBIDDEN_PATTERNS = [
+  /@playwright\/mcp/,
+  /playwright-mcp/,
+];
+
+// Lines that mention the forbidden pattern AS PART OF documenting the rule
+// itself are skipped. Any of these markers on the same line indicates a
+// documentation context, not an actual import or usage reference.
+const DOCUMENTATION_MARKERS = [
+  /HARD-GATE/,
+  /check-playwright-mcp-canary/,
+  /R5 grep-canary/,
+  /R5 hard-gate/,
+  /canary-exempt/,
+  // "Never @playwright/mcp" — anti-pattern prohibition in soul.md / SKILL.md
+  /Never.*@playwright\/mcp/,
+  /Never.*playwright-mcp/,
+  // "blocks @playwright/mcp" — rule-enforcement documentation
+  /blocks.*@playwright\/mcp/,
+  /blocks.*playwright-mcp/,
+  // Markdown table rows listing @playwright/mcp as a "DO NOT USE" item
+  /DO NOT USE.*@playwright\/mcp|@playwright\/mcp.*DO NOT USE/,
+  /DO NOT USE.*playwright-mcp|playwright-mcp.*DO NOT USE/,
+];
+
+const SCAN_ROOTS = [
+  'skills/playwright-driver',
+  'scripts/lib/test-runner',
+  'scripts/lib/profiles',
+];
+
+const SCAN_EXTENSIONS = ['.md', '.mjs', '.js', '.ts'];
+
+/**
+ * Recursively walk a directory and return all file paths with the allowed extensions.
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function walk(dir) {
+  const results = [];
+  if (!existsSync(dir)) return results;
+  for (const name of readdirSync(dir)) {
+    const full = join(dir, name);
+    const st = statSync(full);
+    if (st.isDirectory()) {
+      results.push(...walk(full));
+    } else if (SCAN_EXTENSIONS.some((ext) => name.endsWith(ext))) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+const violations = [];
+
+for (const rel of SCAN_ROOTS) {
+  const absDir = join(pluginRoot, rel);
+  if (!existsSync(absDir)) {
+    pass(`${rel}/ does not exist yet (no scan needed)`);
+    continue;
+  }
+  const files = walk(absDir);
+  let fileViolations = 0;
+  for (const file of files) {
+    const text = readFileSync(file, 'utf8');
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i += 1) {
+      const line = lines[i];
+      const matchesForbidden = FORBIDDEN_PATTERNS.some((p) => p.test(line));
+      if (!matchesForbidden) continue;
+      const isDocumentation = DOCUMENTATION_MARKERS.some((p) => p.test(line));
+      if (isDocumentation) continue;
+      violations.push({
+        file: relative(pluginRoot, file),
+        line: i + 1,
+        text: line.trim().slice(0, 160),
+      });
+      fileViolations += 1;
+    }
+  }
+  if (fileViolations === 0) {
+    pass(`${rel}/ scanned (${files.length} files): no playwright-mcp references`);
+  }
+}
+
+if (violations.length === 0) {
+  pass(`playwright-mcp canary clean across all ${SCAN_ROOTS.length} scan roots`);
+} else {
+  for (const v of violations) {
+    fail(
+      `${v.file}:${v.line} — '${v.text}' (matches forbidden pattern; ` +
+      `if intentional documentation, add a HARD-GATE marker on the line)`,
+    );
+  }
+}
+
+console.log('');
+console.log(`Results: ${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);