@rubytech/create-maxy-code 0.1.0

package/payload/platform/scripts/check-no-conversation-id-leaks.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+// Task 1007 build-time gate: prevents NEW files from gaining a `conversationId` /
+// `sessionId` reference while the 146-file rename slice is in progress.
+//
+// The legacy identifiers are being collapsed into the single canonical
+// `sessionKey`. This sprint shipped the schema-side load-bearing pieces
+// (backfill, new index, boot-time adherence probe) plus the core lib rename.
+// The mechanical tail (routes, MCP plugin parameters, UI props, WhatsApp,
+// tests, specialist templates) is split across follow-up tasks 1009 and 1010.
+//
+// During the transition window, every file currently containing the legacy
+// identifiers is named in `conversation-id-allowlist.txt`. Each follow-up
+// rename PR removes file paths from the allowlist as those files are migrated.
+// This gate fails if:
+//   (a) a file NOT in the allowlist contains any of the four legacy tokens, or
+//   (b) the allowlist references a path that no longer exists (stale entry).
+//
+// Once tasks 1009 and 1010 land, the allowlist is empty; the gate then enforces
+// the task's outcome contract (zero hits anywhere outside .tasks/archive/).
+
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs'
+import { dirname, join, relative, basename } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url))
+const REPO_ROOT = join(SCRIPT_DIR, '..', '..')
+const ALLOWLIST_PATH = join(SCRIPT_DIR, 'conversation-id-allowlist.txt')
+
+const SCAN_ROOTS = [
+  join(REPO_ROOT, 'platform'),
+  join(REPO_ROOT, 'packages'),
+  join(REPO_ROOT, 'brands'),
+  join(REPO_ROOT, '.docs'),
+  join(REPO_ROOT, '.claude', 'skills'),
+]
+
+const ALLOWED_EXTS = new Set([
+  '.sh', '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
+  '.md', '.cypher', '.json',
+])
+const SKIP_DIR_NAMES = new Set([
+  'node_modules', 'dist', 'build', '.next', 'payload',
+])
+const SKIP_PATH_FRAGMENTS = ['.tasks/archive/']
+
+// Whole-word matches only — avoids hits inside longer identifiers like
+// `agentSessionId` (Claude Agent SDK per-process session, intentionally kept)
+// and `conversationIdentity` (ConversationArchive hash key, unrelated).
+const LEGACY_TOKEN_RE = /\b(?:conversationId|sessionId|CONVERSATION_ID|SESSION_ID)\b/
+
+// Comment-line skip — matches the convention in check-no-task-id-leaks.mjs.
+// Comments that *describe* the legacy field (inside the migration code itself,
+// or inline docstrings explaining the rename) are not new executing code
+// introducing the token, so they don't trip the gate.
+function isCommentLine(line) {
+  const trimmed = line.replace(/^\s+/, '')
+  if (trimmed.startsWith('#')) return true
+  if (trimmed.startsWith('//')) return true
+  if (trimmed.startsWith('/*')) return true
+  if (trimmed.startsWith('*')) return true
+  if (trimmed.startsWith('{/*')) return true
+  return false
+}
+
+function loadAllowlist() {
+  if (!existsSync(ALLOWLIST_PATH)) return new Set()
+  const text = readFileSync(ALLOWLIST_PATH, 'utf-8')
+  return new Set(
+    text.split('\n')
+      .map(l => l.trim())
+      .filter(l => l && !l.startsWith('#'))
+  )
+}
+
+function shouldScanFile(filePath) {
+  const name = basename(filePath)
+  const ext = name.includes('.') ? '.' + name.split('.').pop() : ''
+  if (!ALLOWED_EXTS.has(ext)) return false
+  const rel = relative(REPO_ROOT, filePath)
+  for (const frag of SKIP_PATH_FRAGMENTS) {
+    if (rel.includes(frag)) return false
+  }
+  return true
+}
+
+function* walk(root) {
+  let entries
+  try { entries = readdirSync(root) } catch { return }
+  for (const name of entries) {
+    if (SKIP_DIR_NAMES.has(name)) continue
+    const full = join(root, name)
+    let st
+    try { st = statSync(full) } catch { continue }
+    if (st.isDirectory()) {
+      yield* walk(full)
+    } else if (st.isFile()) {
+      yield full
+    }
+  }
+}
+
+const allowlist = loadAllowlist()
+const newLeaks = []
+const hitFiles = new Set()
+
+for (const root of SCAN_ROOTS) {
+  if (!existsSync(root)) continue
+  for (const file of walk(root)) {
+    if (!shouldScanFile(file)) continue
+    let content
+    try { content = readFileSync(file, 'utf-8') } catch { continue }
+    if (!LEGACY_TOKEN_RE.test(content)) continue
+    const rel = relative(REPO_ROOT, file)
+    const lines = content.split('\n')
+    // For non-allowlisted files: only flag hits in non-comment lines. For
+    // allowlisted files: any hit counts (so the allowlist accurately tracks
+    // the surface still using the legacy name, comments and code alike).
+    if (allowlist.has(rel)) {
+      hitFiles.add(rel)
+      continue
+    }
+    let firstLine = 0, firstText = ''
+    for (let i = 0; i < lines.length; i++) {
+      if (!LEGACY_TOKEN_RE.test(lines[i])) continue
+      if (isCommentLine(lines[i])) continue
+      firstLine = i + 1
+      firstText = lines[i].trim().slice(0, 120)
+      break
+    }
+    if (firstLine > 0) {
+      newLeaks.push({ file: rel, line: firstLine, content: firstText })
+    }
+  }
+}
+
+// Stale allowlist entries: files in the allowlist that no longer have a hit
+// (renamed already, or no longer exist) — remove them.
+const staleAllowlistEntries = [...allowlist].filter(p => !hitFiles.has(p))
+
+let failed = false
+
+if (newLeaks.length > 0) {
+  failed = true
+  console.error(`check-no-conversation-id-leaks: ${newLeaks.length} NEW file(s) introduced legacy identifier(s):`)
+  for (const leak of newLeaks) {
+    console.error(`  ${leak.file}:${leak.line}: ${leak.content}`)
+  }
+  console.error('')
+  console.error('The single canonical identifier is `sessionKey`. New code must use it.')
+  console.error('Legacy tokens: conversationId, sessionId, CONVERSATION_ID, SESSION_ID.')
+  console.error('Follow-up tasks 1009 + 1010 are migrating existing files off the allowlist.')
+}
+
+if (staleAllowlistEntries.length > 0) {
+  failed = true
+  console.error('')
+  console.error(`check-no-conversation-id-leaks: ${staleAllowlistEntries.length} stale allowlist entry(ies) — remove from platform/scripts/conversation-id-allowlist.txt:`)
+  for (const entry of staleAllowlistEntries) {
+    console.error(`  ${entry}`)
+  }
+}
+
+if (failed) process.exit(1)
+
+console.error(`check-no-conversation-id-leaks: ok (${allowlist.size} files in transition allowlist; 0 new leaks)`)

package/payload/platform/scripts/check-no-task-id-leaks.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// Build-time gate: rejects `(Task NNN)` citations in operator-visible production
+// strings. Citations are allowed in inline comments and test titles/bodies only.
+//
+// Live repro that motivated the gate: setup-tunnel.sh on realagent 192.168.88.8
+// emitted `Re-run the installer to provision Chromium (Task 929).` to the
+// operator's chat surface — the citation made the operator chase Task 929's
+// history rather than execute the verb. Operator surfaces strip citations;
+// internal references keep them.
+//
+// Comment-skip is line-leading-character based, not AST. The repo's actual
+// comment forms are: `#` (shell), `//` (TS/JS line), `*`/`/*`/`/**` (JSDoc
+// continuation, block, doc), and `{/*` (JSX). Any line whose first non-
+// whitespace token is one of these is skipped. Test files (`__tests__/` and
+// `*.test.{ts,tsx,js}`) are skipped wholesale because the brief's out-of-scope
+// rule covers test titles, and test bodies that assert on citations are
+// equivalent to titles for this gate's purpose.
+
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { dirname, join, relative, sep, basename } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url))
+const REPO_ROOT = join(SCRIPT_DIR, '..', '..')
+
+const SCAN_ROOTS = [
+  join(REPO_ROOT, 'platform', 'scripts'),
+  join(REPO_ROOT, 'platform', 'plugins'),
+  join(REPO_ROOT, 'platform', 'ui', 'server'),
+  join(REPO_ROOT, 'platform', 'ui', 'app'),
+  join(REPO_ROOT, 'packages', 'create-maxy', 'src'),
+]
+
+const ALLOWED_EXTS = new Set(['.sh', '.ts', '.tsx', '.js', '.mjs', '.cjs'])
+const SKIP_DIR_NAMES = new Set([
+  'node_modules', 'dist', 'build', '.next', 'payload', '__tests__',
+])
+const TASK_ID_RE = /\(Task \d+\)/
+
+function isCommentLine(line) {
+  const trimmed = line.replace(/^\s+/, '')
+  if (trimmed.startsWith('#')) return true
+  if (trimmed.startsWith('//')) return true
+  if (trimmed.startsWith('/*')) return true
+  if (trimmed.startsWith('*')) return true
+  if (trimmed.startsWith('{/*')) return true
+  return false
+}
+
+function shouldScanFile(filePath) {
+  const name = basename(filePath)
+  if (name.endsWith('.test.ts')) return false
+  if (name.endsWith('.test.tsx')) return false
+  if (name.endsWith('.test.js')) return false
+  const ext = name.includes('.') ? '.' + name.split('.').pop() : ''
+  return ALLOWED_EXTS.has(ext)
+}
+
+function* walk(root) {
+  let entries
+  try {
+    entries = readdirSync(root)
+  } catch {
+    return
+  }
+  for (const name of entries) {
+    if (SKIP_DIR_NAMES.has(name)) continue
+    const full = join(root, name)
+    let st
+    try { st = statSync(full) } catch { continue }
+    if (st.isDirectory()) {
+      yield* walk(full)
+    } else if (st.isFile()) {
+      yield full
+    }
+  }
+}
+
+const leaks = []
+
+for (const root of SCAN_ROOTS) {
+  for (const file of walk(root)) {
+    if (!shouldScanFile(file)) continue
+    let content
+    try {
+      content = readFileSync(file, 'utf-8')
+    } catch {
+      continue
+    }
+    const lines = content.split('\n')
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i]
+      if (!TASK_ID_RE.test(line)) continue
+      if (isCommentLine(line)) continue
+      leaks.push({ file: relative(REPO_ROOT, file), line: i + 1, content: line.trim() })
+    }
+  }
+}
+
+if (leaks.length > 0) {
+  console.error(`check-no-task-id-leaks: ${leaks.length} operator-visible (Task NNN) citation(s) found:`)
+  for (const leak of leaks) {
+    console.error(`  ${leak.file}:${leak.line}: ${leak.content}`)
+  }
+  console.error('')
+  console.error('Citations belong in inline comments only, never in operator-visible strings')
+  console.error('(stderr/stdout, log files surfaced via logs-read.sh, systemd unit')
+  console.error('--description=, error messages, console.log/warn/error, throw new Error).')
+  process.exit(1)
+}

package/payload/platform/scripts/check-sdk-oauth.mjs

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+// Task 746 — OAuth + wire-identity check for @anthropic-ai/claude-agent-sdk.
+//
+// One-shot spike. Pi-runnable. Intentionally orphan/standalone — not imported
+// by any production module, not wired into any cron, hook, or route. Task 606
+// owns SDK adoption in production; this script gates that adoption.
+//
+// Precondition (exact):
+//   ssh <pi>     # see memory/reference_device_ssh.md for hosts
+//   cd /tmp && mkdir -p sdk-spike && cd sdk-spike
+//   npm install @anthropic-ai/claude-agent-sdk@0.2.119   # pin matches static evidence
+//   cp <repo>/platform/scripts/check-sdk-oauth.mjs .
+//   unset ANTHROPIC_API_KEY
+//   node check-sdk-oauth.mjs 2>&1 | tee spike.log
+//
+// PASS condition: apiKeySource ∈ {'oauth', 'none'}. Both indicate OAuth-only mode:
+// 'oauth' = SDK supplied an OAuth-issued API key; 'none' = SDK supplied no key
+// at all and the claude binary's own credentials file is in use. Production
+// brand installs (Task 923) read this file from CLAUDE_CONFIG_DIR — which
+// the brand main service sets to `${persistDir}/.claude` — so the
+// per-brand path is `~/${BRAND.configDir}/.claude/.credentials.json`. This
+// orphan/standalone Pi spike runs without that env var and falls back to
+// `~/.claude/.credentials.json`; that's by design (the spike is not in the
+// production execution path; see Task 746 brief). Cross-check with
+// `claude --print --output-format json "Reply…"` to confirm parity.
+//
+// Verdict reasons (exit 1 unless PASS):
+//   env-set                       ANTHROPIC_API_KEY present (operator must `unset`)
+//   no-oauth-credentials          credentials file unreadable, empty, or
+//                                 contains no OAuth-shaped fields (run `claude login`)
+//   exception:<msg>               SDK import or runtime error
+//   no-system-init                SDK never emitted system.init message
+//   wrong-api-key-source:<value>  apiKeySource ∉ {oauth, none} — value verbatim;
+//                                 MISSING-FIELD if SDK message shape drifted
+//                                 (raw msg dumped on next line)
+//   assistant-error:<value>       SDK reported assistant error: authentication_failed |
+//                                 billing_error | rate_limit | invalid_request |
+//                                 server_error | unknown | max_output_tokens
+//   no-response                   no assistant message arrived
+//   empty-response                assistant arrived, no text content
+//   timeout                       60s elapsed waiting for response
+//
+// Wire-identity (mitmproxy header diff vs `claude -p`) and subscription-billing
+// (VNC dashboard) are operator-manual per Task 746 brief — not script-side.
+// .docs/platform.md captures the consolidated verdict (script + mitm + VNC).
+
+import { accessSync, readFileSync, constants as FS } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+const TIMEOUT_MS = 60_000
+const PROMPT = 'Reply with the literal string OK and nothing else.'
+// Claude Code emits apiKeySource='none' when the SDK supplies no API key and
+// the claude binary uses its own OAuth credentials at the path resolved from
+// CLAUDE_CONFIG_DIR (Task 923) — falling back to `~/.claude/.credentials.json`
+// when CLAUDE_CONFIG_DIR is unset, as in this orphan Pi spike's runtime.
+// Brief assumed 'oauth' based on stale type-defs; runtime-correct OAuth-only
+// indicator on Claude Code 2.1.x is 'none'. Both accepted; cross-check with
+// `claude --print --output-format json` to confirm parity.
+const OAUTH_API_KEY_SOURCES = new Set(['oauth', 'none'])
+
+const log = (line) => process.stdout.write(line + '\n')
+const safeStringify = (v) => { try { return JSON.stringify(v) } catch { return '<unstringifiable>' } }
+
+let verdictEmitted = false
+const fail = (reason) => {
+  if (verdictEmitted) return
+  verdictEmitted = true
+  log(`[sdk-spike] verdict: FAIL reason=${reason}`)
+  process.exit(1)
+}
+const pass = (note) => {
+  if (verdictEmitted) return
+  verdictEmitted = true
+  log(`[sdk-spike] verdict: PASS${note ? ` ${note}` : ''}`)
+  process.exit(0)
+}
+
+async function main() {
+  const envState = process.env.ANTHROPIC_API_KEY ? 'set' : 'unset'
+  log(`[sdk-spike] env: ANTHROPIC_API_KEY=${envState}`)
+  if (envState === 'set') fail('env-set')
+
+  const credsPath = join(homedir(), '.claude', '.credentials.json')
+  try { accessSync(credsPath, FS.R_OK) }
+  catch { fail('no-oauth-credentials') }
+
+  let credsSize = 0
+  let credsHasOauthFields = false
+  let credsTopKeys = []
+  try {
+    const credsRaw = readFileSync(credsPath, 'utf8')
+    credsSize = credsRaw.length
+    const credsObj = JSON.parse(credsRaw)
+    credsTopKeys = Object.keys(credsObj).sort()
+    credsHasOauthFields = credsTopKeys.some((k) => /oauth|access|refresh|bearer/i.test(k)) ||
+      Object.values(credsObj).some((v) => v && typeof v === 'object' &&
+        Object.keys(v).some((k) => /oauth|access|refresh|bearer/i.test(k)))
+  } catch { /* malformed creds file — surface in log, fail with no-oauth-credentials below */ }
+  log(`[sdk-spike] creds: size=${credsSize} topKeys=${credsTopKeys.join(',')} hasOauthFields=${credsHasOauthFields}`)
+  if (credsSize === 0 || !credsHasOauthFields) fail('no-oauth-credentials')
+
+  let query
+  try {
+    ({ query } = await import('@anthropic-ai/claude-agent-sdk'))
+  } catch (err) {
+    fail(`exception:${String(err?.message ?? err).slice(0, 200)}`)
+  }
+
+  let sdkVersion = '<unknown>'
+  try {
+    const pkgPath = join(process.cwd(), 'node_modules', '@anthropic-ai', 'claude-agent-sdk', 'package.json')
+    sdkVersion = JSON.parse(readFileSync(pkgPath, 'utf8')).version
+  } catch { /* leave as <unknown> — diagnostic, not load-bearing */ }
+  log(`[sdk-spike] sdk-version: ${sdkVersion}`)
+
+  let gotInit = false
+  let apiKeySource = ''
+  let apiProvider = ''
+  let model = ''
+  let sessionId = ''
+  let claudeCodeVersion = ''
+  let gotAssistant = false
+  let assistantError = ''
+  let responseText = ''
+
+  const result = query({ prompt: PROMPT })
+
+  let timeoutId
+  const timer = new Promise((_, reject) => {
+    timeoutId = setTimeout(() => reject(new Error(`timeout after ${TIMEOUT_MS}ms`)), TIMEOUT_MS)
+  })
+
+  const consume = (async () => {
+    for await (const msg of result) {
+      if (msg?.type === 'system' && msg?.subtype === 'init') {
+        gotInit = true
+        // apiKeySource is required (sdk.d.ts:3286 — non-optional). MISSING-FIELD here = SDK shape drift, dump raw.
+        apiKeySource = msg.apiKeySource ?? msg.api_key_source ?? 'MISSING-FIELD'
+        // apiProvider is optional (sdk.d.ts:32 declares `?:`); absent on Claude Code 2.1.119. <absent> ≠ defect.
+        apiProvider = msg.apiProvider ?? msg.api_provider ?? '<absent>'
+        model = msg.model ?? '<unknown>'
+        sessionId = msg.session_id ?? msg.sessionId ?? '<unknown>'
+        claudeCodeVersion = msg.claude_code_version ?? '<unknown>'
+        log(`[sdk-spike] system-init: apiKeySource=${apiKeySource} apiProvider=${apiProvider} model=${model} sessionId=${sessionId} claudeCodeVersion=${claudeCodeVersion}`)
+        if (apiKeySource === 'MISSING-FIELD') {
+          log(`[sdk-spike] system-init-raw: ${safeStringify(msg)}`)
+        }
+      } else if (msg?.type === 'assistant') {
+        gotAssistant = true
+        if (msg.error && !assistantError) assistantError = msg.error
+        const blocks = msg.message?.content ?? []
+        for (const block of blocks) {
+          if (block?.type === 'text' && typeof block.text === 'string') {
+            responseText += block.text
+          }
+        }
+      }
+    }
+  })()
+
+  try {
+    await Promise.race([consume, timer])
+  } catch (err) {
+    try { Promise.resolve(result.return?.()).catch(() => {}) } catch { /* best-effort cleanup */ }
+    if (String(err?.message ?? '').startsWith('timeout after')) fail('timeout')
+    fail(`exception:${String(err?.message ?? err).slice(0, 200)}`)
+  } finally {
+    clearTimeout(timeoutId)
+    try { Promise.resolve(result.return?.()).catch(() => {}) } catch { /* best-effort cleanup */ }
+  }
+
+  log(`[sdk-spike] response: ${responseText}`)
+
+  if (!gotInit) fail('no-system-init')
+  if (!OAUTH_API_KEY_SOURCES.has(apiKeySource)) fail(`wrong-api-key-source:${apiKeySource}`)
+  if (assistantError) fail(`assistant-error:${assistantError}`)
+  if (!gotAssistant) fail('no-response')
+  if (responseText.trim() === '') fail('empty-response')
+  pass(`apiKeySource=${apiKeySource} apiProvider=${apiProvider} sdk=${sdkVersion} cli=${claudeCodeVersion}`)
+}
+
+main().catch((err) => {
+  fail(`exception:${String(err?.message ?? err).slice(0, 200)}`)
+})

package/payload/platform/scripts/check-skill-load-coverage.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+// Task 1015 — build-time gate: rejects prose that tells an agent to load a
+// SKILL.md via `plugin-read`. `skill-load skillName=<name>` is the canonical
+// resolve+read primitive for skills; `plugin-read` retains ownership of
+// `references/*` and `PLUGIN.md` (both inherently plugin-scoped).
+//
+// Two phrasing classes regressed historically (corrections ledger:
+// `path-as-pluginName`, count >= 1):
+//   1. Literal-path:  "Load `<plugin>/skills/<slug>/SKILL.md` via `plugin-read`"
+//   2. Manifest-pointer: "load via `plugin-read` (find its path in the manifest ...)"
+// Both surface the same failure — the LLM packs the path into the `pluginName`
+// argument and hits the not-found branch. This gate fails CI if either phrasing
+// reappears in `platform/templates/` or in any plugin's `SKILL.md` / `PLUGIN.md`.
+//
+// Scope: prose-only Markdown the agent reads as instructions. Code files are
+// out of scope (TypeScript / shell already lint elsewhere). References under
+// `skills/*/references/` are out of scope because they document end-user
+// behaviour, not agent routing. The MCP server's `index.ts` and tests are
+// covered by their own type checks + the `skill-load.test.ts` suite.
+
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs'
+import { dirname, join, basename } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url))
+const REPO_ROOT = join(SCRIPT_DIR, '..', '..')
+
+const SCAN_ROOTS = [
+  join(REPO_ROOT, 'platform', 'templates'),
+  join(REPO_ROOT, 'platform', 'plugins'),
+]
+
+// Phrasing 1 — literal SKILL.md path with `via plugin-read`. Matches every
+// historical site that named a path string.
+const PATH_PHRASING_RE = /Load\s+[`"]?[\w/-]*skills\/[a-z0-9-]+\/SKILL\.md[`"]?\s+via\s+`?plugin-read`?/i
+
+// Phrasing 2 — manifest-pointer "via plugin-read (find its path in the manifest ...)"
+// from sites that referred the agent to the manifest instead of naming a path.
+const MANIFEST_PHRASING_RE = /via\s+`?plugin-read`?\s*\(\s*find its path in the manifest/i
+
+// Only scan files that an agent reads as routing instructions.
+function shouldScanFile(filePath) {
+  const base = basename(filePath)
+  if (base === 'SKILL.md' || base === 'PLUGIN.md' || base === 'IDENTITY.md' || base === 'SOUL.md') return true
+  // Specialist agent files live under platform/templates/specialists/agents/*.md
+  if (filePath.includes('/templates/specialists/agents/') && filePath.endsWith('.md')) return true
+  // Other markdown under templates/agents/ (admin/public IDENTITY.md handled by base check)
+  if (filePath.includes('/templates/agents/') && filePath.endsWith('.md')) return true
+  return false
+}
+
+const SKIP_DIR_NAMES = new Set(['node_modules', 'dist', '.git', 'references', 'archive'])
+
+function* walk(root) {
+  if (!existsSync(root)) return
+  for (const entry of readdirSync(root)) {
+    if (SKIP_DIR_NAMES.has(entry)) continue
+    const full = join(root, entry)
+    let stat
+    try { stat = statSync(full) } catch { continue }
+    if (stat.isDirectory()) {
+      yield* walk(full)
+    } else if (stat.isFile()) {
+      yield full
+    }
+  }
+}
+
+const violations = []
+
+for (const root of SCAN_ROOTS) {
+  for (const file of walk(root)) {
+    if (!shouldScanFile(file)) continue
+    let text
+    try { text = readFileSync(file, 'utf-8') } catch { continue }
+    const lines = text.split('\n')
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i]
+      if (PATH_PHRASING_RE.test(line)) {
+        violations.push({ file, line: i + 1, phrasing: 'literal-path', text: line.trim() })
+      } else if (MANIFEST_PHRASING_RE.test(line)) {
+        violations.push({ file, line: i + 1, phrasing: 'manifest-pointer', text: line.trim() })
+      }
+    }
+  }
+}
+
+if (violations.length > 0) {
+  console.error(`check-skill-load-coverage: ${violations.length} prose site(s) still tell the agent to load a skill via plugin-read.`)
+  console.error(`Rewrite each to: Run \`skill-load skillName=<name>\``)
+  console.error(``)
+  for (const v of violations) {
+    const rel = v.file.replace(REPO_ROOT + '/', '')
+    console.error(`  ${rel}:${v.line}  [${v.phrasing}]`)
+    console.error(`    ${v.text.slice(0, 200)}${v.text.length > 200 ? '…' : ''}`)
+  }
+  process.exit(1)
+}
+
+console.log(`check-skill-load-coverage: ok (0 prose sites use legacy plugin-read for skills)`)