@rubytech/create-maxy 1.0.711 → 1.0.713

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

@@ -0,0 +1,178 @@
+#!/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 ~/.claude/.credentials.json OAuth state is
+// in use. Cross-check with `claude --print --output-format json "Reply…"` to
+// confirm the same value: parity = SDK is faithfully proxying claude's auth.
+//
+// Verdict reasons (exit 1 unless PASS):
+//   env-set                       ANTHROPIC_API_KEY present (operator must `unset`)
+//   no-oauth-credentials          ~/.claude/.credentials.json 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 ~/.claude/.credentials.json.
+// 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/redact-install-logs.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# Existing-pi install-log redaction (Task 744).
+#
+# Idempotent one-shot remediation for Pis that completed installation BEFORE
+# the install-log redaction landed at index.ts:152 / setup.sh:94. Scans every
+# `install-*.log` in the configured logs directory and replaces every literal
+# `set-initial-password ...<secret>` payload with `set-initial-password
+# [REDACTED]`. Re-running the script is safe — already-redacted lines do not
+# match the source pattern, so no further edits occur.
+#
+# Source patterns covered:
+#   1. TS installer (packages/create-maxy/src/index.ts:152) — "[ISO] > sudo
+#      neo4j-admin dbms set-initial-password -- <secret>" or any args after
+#      "set-initial-password" (positional or "--" delimited).
+#   2. Shell installer (platform/scripts/setup.sh, pre-fix variant) — "+ sudo
+#      neo4j-admin dbms set-initial-password <secret>" if bash -x had been on.
+#
+# A trailing marker line `[redact-install-logs] redacted=<n> file=<path>` is
+# appended to each modified log so subsequent reads can identify which logs
+# went through the remediation. Files with zero matches are left untouched.
+#
+# Default scan location: $HOME/.maxy/logs (the installer's LOG_DIR). Override
+# with --dir <path> for non-default deployments.
+
+set -euo pipefail
+
+LOG_DIR="${HOME}/.maxy/logs"
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --dir) LOG_DIR="$2"; shift 2 ;;
+    --help|-h)
+      cat <<USAGE
+Usage: redact-install-logs.sh [--dir <log-dir>]
+
+Redacts neo4j set-initial-password secrets from install-*.log files.
+Default --dir: \$HOME/.maxy/logs
+
+Idempotent — safe to re-run.
+USAGE
+      exit 0 ;;
+    *) echo "Unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+if [ ! -d "$LOG_DIR" ]; then
+  echo "[redact-install-logs] log dir not found: $LOG_DIR (nothing to do)"
+  exit 0
+fi
+
+shopt -s nullglob
+TOTAL_FILES=0
+TOTAL_REDACTIONS=0
+
+for f in "$LOG_DIR"/install-*.log; do
+  [ -f "$f" ] || continue
+  TOTAL_FILES=$((TOTAL_FILES + 1))
+
+  # Pattern: any "set-initial-password" line followed by one or more args.
+  # The replacement keeps the leading prefix (timestamp + cmd up through
+  # set-initial-password and an optional "--") and substitutes everything
+  # after with [REDACTED]. We anchor the replacement only when the remaining
+  # tail is non-empty AND not already "[REDACTED]" — making the script idempotent.
+  REDACTED_THIS_FILE=$(
+    perl -ne '
+      if (/set-initial-password(\s+--)?\s+(\S.*)$/ && $2 ne "[REDACTED]") {
+        print STDOUT "1\n";
+      }
+    ' "$f" | wc -l | tr -d ' '
+  )
+
+  if [ "$REDACTED_THIS_FILE" -gt 0 ]; then
+    perl -i -pe '
+      if (/set-initial-password(\s+--)?\s+(\S.*)$/ && $2 ne "[REDACTED]") {
+        s/set-initial-password(\s+--)?\s+\S.*$/set-initial-password${1} [REDACTED]/;
+      }
+    ' "$f"
+    printf "[redact-install-logs] redacted=%d file=%s\n" "$REDACTED_THIS_FILE" "$f" >> "$f"
+    echo "[redact-install-logs] redacted=$REDACTED_THIS_FILE file=$f"
+    TOTAL_REDACTIONS=$((TOTAL_REDACTIONS + REDACTED_THIS_FILE))
+  fi
+done
+
+echo "[redact-install-logs] summary files_scanned=$TOTAL_FILES total_redactions=$TOTAL_REDACTIONS"
+exit 0

package/payload/platform/scripts/setup.sh

@@ -86,12 +86,20 @@ else
   # Configure Neo4j for local use
   sudo sed -i 's/#server.default_listen_address=0.0.0.0/server.default_listen_address=127.0.0.1/' /etc/neo4j/neo4j.conf
 
-  # Generate a strong random password and store it
+  # Generate a strong random password and store it.
+  # Password handling block is set +x bracketed so even bash -x setup.sh
+  # cannot print the substituted secret. The password is written to
+  # platform/config/.neo4j-password (chmod 600) — the only readable source.
+  # set-initial-password reads the secret via $(cat ...) so the literal
+  # never appears on the parent shell's command line, and stdout is
+  # discarded so neo4j-admin's own echo cannot leak it either (Task 744).
+  { set +x; } 2>/dev/null
   NEO4J_GENERATED_PASSWORD=$(openssl rand -base64 32 | tr -d '/+=' | head -c 32)
   mkdir -p "$INSTALL_DIR/platform/config"
-  echo "$NEO4J_GENERATED_PASSWORD" > "$INSTALL_DIR/platform/config/.neo4j-password"
+  printf '%s' "$NEO4J_GENERATED_PASSWORD" > "$INSTALL_DIR/platform/config/.neo4j-password"
   chmod 600 "$INSTALL_DIR/platform/config/.neo4j-password"
-  sudo neo4j-admin dbms set-initial-password "$NEO4J_GENERATED_PASSWORD"
+  unset NEO4J_GENERATED_PASSWORD
+  sudo neo4j-admin dbms set-initial-password "$(cat "$INSTALL_DIR/platform/config/.neo4j-password")" >/dev/null 2>&1
 
   # Start and enable
   sudo systemctl enable neo4j
@@ -139,6 +147,15 @@ else
   cd "$INSTALL_DIR"
 fi
 
+# ------------------------------------------------------------------
+# 6.5. Redact install-log credential leaks (Task 744 — idempotent).
+# Pre-fix logs may contain plaintext neo4j passwords; this script scrubs
+# every install-*.log to "[REDACTED]". Safe on already-clean logs.
+# ------------------------------------------------------------------
+if [ -x "$INSTALL_DIR/platform/scripts/redact-install-logs.sh" ]; then
+  bash "$INSTALL_DIR/platform/scripts/redact-install-logs.sh" || true
+fi
+
 # ------------------------------------------------------------------
 # 7. Install dependencies and build
 # ------------------------------------------------------------------

package/payload/platform/scripts/verify-skill-tool-surface.sh

@@ -0,0 +1,255 @@
+#!/usr/bin/env bash
+# Pre-publish acceptance gate (Task 744).
+#
+# Statically intersects what each shipped skill *prescribes* (every
+# backtick-quoted `mcp__<server>__<tool>` token in SKILL.md and references/*.md)
+# against the dispatched specialist's frontmatter `tools:` list. Catches the
+# class of bug where a skill prescribes a tool the specialist does not have,
+# and where a skill prescribes a forbidden direct-execution path
+# (`cypher-shell`, `neo4j-admin` invocations, raw-Cypher DML in prose).
+#
+# Wired into the root `packages/create-maxy/package.json` `prepublishOnly`
+# script so a regression cannot reach npm publish without firing.
+#
+# One stdout line per (skill, specialist) pair:
+#   [verify] skill=<plugin>/<skill> specialist=<n> resolved=<n>/<m> forbidden=<n>
+#
+# Exit 0: every prescribed token resolves AND no forbidden tokens.
+# Exit 1: any unresolved or any forbidden — stderr names the offending token.
+#
+# Skill→specialist mapping comes from PLUGIN.md frontmatter `specialist:` field.
+# Plugins without that field are admin-owned (loaded by the admin agent
+# directly via plugin-read); for those the gate only enforces the forbidden-
+# token rule, since admin's tool surface is the union of all enabled plugins.
+
+set -euo pipefail
+
+REPO_ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)
+cd "$REPO_ROOT"
+
+python3 - <<'PYEOF'
+import os, re, sys
+
+REPO_ROOT = os.getcwd()
+PLUGINS_DIR = os.path.join(REPO_ROOT, "platform", "plugins")
+SPECIALISTS_DIR = os.path.join(REPO_ROOT, "platform", "templates", "specialists", "agents")
+
+# Per-skill specialist ownership for plugins where the plugin itself is
+# multi-purpose. The PLUGIN.md `specialist:` field handles single-owner
+# plugins (linkedin-import → database-operator). Mixed-use plugins like
+# `memory` declare per-skill ownership here.
+EXPLICIT_OWNERSHIP = {
+    # plugin/skill -> specialist
+    "memory/document-ingest": "database-operator",
+}
+
+# Skills that are explicitly admin-owned (loaded via plugin-read by the admin
+# agent itself, not delegated to a specialist). These get only the forbidden-
+# token check since admin's effective tool set is the union of all enabled
+# plugins.
+ADMIN_OWNED_SKILLS = {
+    "memory/conversational-memory",
+}
+
+TOKEN_RE = re.compile(r"`(mcp__[a-z][a-z0-9_-]*__[a-z][a-z0-9_-]*)`")
+FENCED_BLOCK_RE = re.compile(r"```(?P<lang>[a-zA-Z]*)\n(?P<body>.*?)\n```", re.S)
+PROSE_CYPHER_RE = re.compile(
+    r"`(?:MERGE|CREATE|DETACH\s+DELETE)\s+\(",
+    re.IGNORECASE,
+)
+
+
+def parse_frontmatter(path: str) -> dict | None:
+    """Parse YAML-ish frontmatter without PyYAML — handles `key: value` and
+    `key:\n  - item\n  - item` shapes used in PLUGIN.md and specialist files."""
+    try:
+        text = open(path, encoding="utf-8").read()
+    except FileNotFoundError:
+        return None
+    m = re.match(r"^---\n(.*?)\n---", text, re.S)
+    if not m:
+        return None
+    block = m.group(1)
+    out: dict = {}
+    cur_key: str | None = None
+    cur_list: list[str] | None = None
+    for line in block.split("\n"):
+        if not line.strip():
+            continue
+        # List item under cur_key
+        if line.startswith("  - ") or line.startswith("- "):
+            if cur_list is None:
+                continue
+            cur_list.append(line.split("- ", 1)[1].strip())
+            continue
+        # Top-level key
+        m2 = re.match(r"^([A-Za-z_][A-Za-z0-9_]*)\s*:\s*(.*)$", line)
+        if not m2:
+            continue
+        cur_key = m2.group(1)
+        rhs = m2.group(2).strip()
+        if rhs:
+            # inline value — strip surrounding quotes
+            if (rhs.startswith('"') and rhs.endswith('"')) or (
+                rhs.startswith("'") and rhs.endswith("'")
+            ):
+                rhs = rhs[1:-1]
+            out[cur_key] = rhs
+            cur_list = None
+        else:
+            cur_list = []
+            out[cur_key] = cur_list
+    return out
+
+
+def specialist_tools(specialist: str) -> set[str] | None:
+    fm = parse_frontmatter(os.path.join(SPECIALISTS_DIR, f"{specialist}.md"))
+    if fm is None:
+        return None
+    raw = fm.get("tools", "")
+    if isinstance(raw, list):
+        items = raw
+    else:
+        items = [t.strip() for t in str(raw).split(",")]
+    return {t for t in items if t}
+
+
+def extract_prescribed_tokens(text: str) -> set[str]:
+    return set(TOKEN_RE.findall(text))
+
+
+def extract_forbidden(text: str) -> list[tuple[str, str]]:
+    forbidden: list[tuple[str, str]] = []
+
+    # Forbidden invocations inside fenced shell blocks
+    for m in FENCED_BLOCK_RE.finditer(text):
+        lang = m.group("lang").lower()
+        body = m.group("body")
+        if lang in {"bash", "sh", "shell", "zsh"}:
+            if re.search(r"\bcypher-shell\b", body):
+                forbidden.append(("cypher-shell", "in fenced shell block"))
+            if re.search(r"\bneo4j-admin\s+dbms\b", body):
+                forbidden.append(("neo4j-admin", "in fenced shell block"))
+
+    # Strip fenced blocks for the prose-Cypher heuristic
+    prose = FENCED_BLOCK_RE.sub("", text)
+    if PROSE_CYPHER_RE.search(prose):
+        forbidden.append(("raw-cypher-dml", "in backtick-quoted prose"))
+
+    return forbidden
+
+
+def aggregate_skill_text(skill_dir: str) -> str:
+    out: list[str] = []
+    skill_md = os.path.join(skill_dir, "SKILL.md")
+    if not os.path.exists(skill_md):
+        return ""
+    out.append(open(skill_md, encoding="utf-8").read())
+    refs = os.path.join(skill_dir, "references")
+    if os.path.isdir(refs):
+        for name in sorted(os.listdir(refs)):
+            if name.endswith(".md"):
+                out.append(open(os.path.join(refs, name), encoding="utf-8").read())
+    return "\n".join(out)
+
+
+def main() -> int:
+    if not os.path.isdir(PLUGINS_DIR):
+        print(f"[verify] PLUGINS_DIR not found: {PLUGINS_DIR}", file=sys.stderr)
+        return 1
+    if not os.path.isdir(SPECIALISTS_DIR):
+        print(f"[verify] SPECIALISTS_DIR not found: {SPECIALISTS_DIR}", file=sys.stderr)
+        return 1
+
+    summary: list[str] = []
+    errors: list[str] = []
+    pairs_checked = 0
+
+    for plugin in sorted(os.listdir(PLUGINS_DIR)):
+        pdir = os.path.join(PLUGINS_DIR, plugin)
+        if not os.path.isdir(pdir):
+            continue
+        plugin_fm = parse_frontmatter(os.path.join(pdir, "PLUGIN.md")) or {}
+        plugin_specialist = plugin_fm.get("specialist")
+
+        skills_dir = os.path.join(pdir, "skills")
+        if not os.path.isdir(skills_dir):
+            continue
+        for skill_name in sorted(os.listdir(skills_dir)):
+            sdir = os.path.join(skills_dir, skill_name)
+            if not os.path.isdir(sdir):
+                continue
+
+            text = aggregate_skill_text(sdir)
+            if not text:
+                continue
+
+            prescribed = extract_prescribed_tokens(text)
+            forbidden = extract_forbidden(text)
+
+            ownership_key = f"{plugin}/{skill_name}"
+            if ownership_key in ADMIN_OWNED_SKILLS:
+                specialist = None
+            else:
+                specialist = (
+                    EXPLICIT_OWNERSHIP.get(ownership_key)
+                    or plugin_specialist
+                )
+
+            if specialist is None:
+                # Admin-owned: only enforce forbidden-token rule.
+                for tok, ctx in forbidden:
+                    errors.append(
+                        f"[verify] skill={ownership_key} specialist=admin "
+                        f"FORBIDDEN token={tok} context=\"{ctx}\""
+                    )
+                summary.append(
+                    f"[verify] skill={ownership_key} specialist=admin (admin-owned) "
+                    f"tokens={len(prescribed)} forbidden={len(forbidden)}"
+                )
+                continue
+
+            tools = specialist_tools(specialist)
+            if tools is None:
+                errors.append(
+                    f"[verify] skill={ownership_key} specialist={specialist} "
+                    f"ERROR specialist frontmatter not parseable"
+                )
+                continue
+
+            unresolved = sorted(prescribed - tools)
+            for tok in unresolved:
+                errors.append(
+                    f"[verify] skill={ownership_key} specialist={specialist} "
+                    f"unresolved={tok}"
+                )
+            for tok, ctx in forbidden:
+                errors.append(
+                    f"[verify] skill={ownership_key} specialist={specialist} "
+                    f"FORBIDDEN token={tok} context=\"{ctx}\""
+                )
+            summary.append(
+                f"[verify] skill={ownership_key} specialist={specialist} "
+                f"resolved={len(prescribed) - len(unresolved)}/{len(prescribed)} "
+                f"forbidden={len(forbidden)}"
+            )
+            pairs_checked += 1
+
+    for line in summary:
+        print(line)
+
+    if errors:
+        for line in errors:
+            print(line, file=sys.stderr)
+        print(
+            f"[verify] FAIL pairs_checked={pairs_checked} errors={len(errors)}",
+            file=sys.stderr,
+        )
+        return 1
+
+    print(f"[verify] OK pairs_checked={pairs_checked}")
+    return 0
+
+
+sys.exit(main())
+PYEOF

package/payload/platform/templates/specialists/agents/database-operator.md

@@ -3,7 +3,7 @@ name: database-operator
 description: "Document and archive ingestion and ad-hoc graph operations — running the universal `document-ingest` skill for any unstructured document (PDF, text, transcript, web page, audio, video) and per-source archive-import skills (LinkedIn Basic Data Export today; CRM-type seed archives as each plugin ships), plus operator-driven graph hygiene (prune orphans, deduplicate entities, add edges, normalise labels). Delegate when the operator uploads any document, drops an archive directory into chat, or asks for any graph operation that is not a routine per-turn write."
 summary: "Ingests every unstructured document and external archive into your graph (LinkedIn today; other CRM sources in future) and handles ad-hoc graph tidy-ups on request. For example, when you upload a CV, a pricing guide, or a contract; when you drop a LinkedIn export folder into chat; or when you ask to prune orphan nodes, merge duplicate people, or add edges between entities."
 model: claude-sonnet-4-6
-tools: Read, Bash, Glob, Grep, mcp__graph__maxy-graph-read_neo4j_cypher, mcp__graph__maxy-graph-get_neo4j_schema, mcp__memory__memory-write, mcp__memory__memory-update, mcp__memory__memory-delete, mcp__memory__memory-search, mcp__memory__memory-rank, mcp__memory__memory-reindex, mcp__memory__memory-find-candidates, mcp__memory__memory-ingest, mcp__memory__memory-ingest-extract, mcp__memory__memory-ingest-web, mcp__memory__memory-classify, mcp__memory__graph-prune-denylist-list, mcp__memory__graph-prune-denylist-add, mcp__memory__graph-prune-denylist-remove, mcp__contacts__contact-create, mcp__contacts__contact-update, mcp__contacts__contact-lookup, mcp__contacts__contact-list, mcp__admin__file-attach, mcp__admin__plugin-read
+tools: Read, Bash, Glob, Grep, mcp__graph__maxy-graph-read_neo4j_cypher, mcp__graph__maxy-graph-get_neo4j_schema, mcp__memory__memory-write, mcp__memory__memory-update, mcp__memory__memory-delete, mcp__memory__memory-search, mcp__memory__memory-rank, mcp__memory__memory-reindex, mcp__memory__memory-find-candidates, mcp__memory__memory-ingest, mcp__memory__memory-ingest-extract, mcp__memory__memory-ingest-web, mcp__memory__memory-classify, mcp__memory__memory-archive-write, mcp__memory__graph-prune-denylist-list, mcp__memory__graph-prune-denylist-add, mcp__memory__graph-prune-denylist-remove, mcp__contacts__contact-create, mcp__contacts__contact-update, mcp__contacts__contact-lookup, mcp__contacts__contact-list, mcp__admin__file-attach, mcp__admin__plugin-read
 ---
 
 # Database Operator
@@ -12,7 +12,7 @@ You own document and archive ingestion and ad-hoc graph operations. You receive
 
 ## Prerogatives
 
-Three rules govern every turn. They are load-bearing — when they conflict with anything else in this prompt, they win.
+Four rules govern every turn. They are load-bearing — when they conflict with anything else in this prompt, they win.
 
 **PRECISE.** Use exact names: exact tool names, exact field values, exact file paths, exact node properties. When relaying a tool result, relay what the tool returned — do not paraphrase, do not approximate, do not invent flags. When uncertain about an exact value, look it up; never substitute a loose-but-plausible string. *Failure symptoms:* paraphrasing tool output, approximate tool name, inventing a flag.
 
@@ -26,6 +26,10 @@ Three rules govern every turn. They are load-bearing — when they conflict with
 
 A landfill graph defeats EVIDENCE-BASED: search returns noise, the agent re-writes the noise, the noise compounds. Compress on write; filter on read.
 
+**LOUD-FAIL.** If a dispatched skill prescribes a tool not present in your live tool surface, or a credential not provided in your tool input, terminate with a structured blocker — never improvise via Bash, never search the filesystem for credentials, never construct a parallel write path. Return: `Skill <name> prescribes <tool/credential>; not available. Cannot proceed. Operator must <remediation>.` Identical doctrine to Task 740 classifier failure and Task 560 graph-MCP loud-fail. *Failure symptoms:* `cypher-shell` invocation, `find … neo4j` / `grep … NEO4J_PASSWORD` filesystem probes, `curl` against Neo4j HTTP endpoints, any Bash improvisation that recreates the missing tool's effect.
+
+The pre-publish gate (`platform/scripts/verify-skill-tool-surface.sh`) statically asserts every shipped skill's prescribed `mcp__*` tokens resolve against your frontmatter `tools:` list, so a missing tool is a build error, not a production discovery. LOUD-FAIL is the runtime backstop when that gate is bypassed (e.g. operator-edited skill).
+
 ---
 
 ## Output contract