clembot-doorman 0.1.0

package/doorman/cli/watch.mjs

@@ -0,0 +1,218 @@
+/**
+ * `doorman watch` - the private half of a subscription.
+ *
+ * The feed is shared: a candidate is graded once and everyone reads that grade
+ * for nothing. THIS half is private, and stays that way. It fetches the feed,
+ * then decides which rows matter by reading YOUR inventory on YOUR machine.
+ * Your agent roster, your installed servers and your allowlist are never sent
+ * anywhere. The only request this makes is a GET for the feed, and that GET
+ * says nothing about you.
+ *
+ * WHAT THIS IS NOT: it is not the fit review. `fitReview()` reads a candidate
+ * against your build with a model and returns one of `redundant`, `fits`,
+ * `needs-new-subagent`, `out-of-scope`. That needs a key and costs tokens.
+ * What runs here is a MECHANICAL overlap check: string matching on hosts and
+ * urls. It can tell you "you already have this one" and "this one hard-failed".
+ * It cannot tell you whether a server you do not have would help, and it must
+ * never claim to, so it never emits the word `fits`.
+ *
+ * Exit codes follow the rest of the CLI: 0 it ran, 2 usage, 3 could not
+ * measure, 1 it broke.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { inventoryFor } from '../src/inventory.mjs';
+
+export const DEFAULT_API = 'https://scorecard.wanessalabs.com';
+export const DEFAULT_STATE = join('.doorman', 'watch.json');
+
+/** What the mechanical check can honestly say. Deliberately not FIT_VERDICTS. */
+export const WATCH_VERDICTS = ['already-installed', 'blocked', 'unreviewed', 'skipped'];
+
+/**
+ * Normalise a server url for comparison.
+ *
+ * Host plus path, lowercased, trailing slash and default ports removed. Host
+ * alone is too coarse: openzeppelin publishes four different servers under one
+ * host and treating them as one would report three of them as already
+ * installed on the strength of the fourth.
+ */
+export function serverKey(url) {
+  if (!url) return null;
+  try {
+    const u = new URL(String(url));
+    const path = u.pathname.replace(/\/+$/, '');
+    return (u.hostname.toLowerCase() + path.toLowerCase()) || u.hostname.toLowerCase();
+  } catch {
+    return String(url).trim().toLowerCase().replace(/\/+$/, '') || null;
+  }
+}
+
+/** Every server this build already knows about, from any source. */
+export function installedKeys(inv) {
+  const keys = new Set();
+  for (const s of inv.mcpServers ?? []) {
+    const k = serverKey(s.url);
+    if (k) keys.add(k);
+  }
+  for (const a of inv.allowlisted ?? []) {
+    const k = serverKey(a.url);
+    if (k) keys.add(k);
+  }
+  return keys;
+}
+
+/**
+ * Classify one feed row against one inventory. Pure, so it is testable without
+ * a network or a filesystem.
+ */
+export function classify(candidate, keys) {
+  if (candidate.is_fixture || candidate.self_graded) {
+    return { verdict: 'skipped', why: candidate.is_fixture
+      ? 'a deliberately hostile test fixture, not a candidate'
+      : 'graded by the operator of the feed, about themselves' };
+  }
+  const key = serverKey(candidate.server_url);
+  if (key && keys.has(key)) {
+    return { verdict: 'already-installed', why: 'this build already has it' };
+  }
+  if (candidate.hard_fail) {
+    return { verdict: 'blocked', why: candidate.hard_fail };
+  }
+  if (candidate.grade === 'F') {
+    return { verdict: 'blocked', why: 'graded F' };
+  }
+  return {
+    verdict: 'unreviewed',
+    // Deliberately not "fits". Nothing here read the candidate against this
+    // build; it only established that the build does not already have it.
+    why: 'new to this build, and it passed the static layer',
+  };
+}
+
+export function readState(file) {
+  try {
+    const raw = JSON.parse(readFileSync(file, 'utf8'));
+    return { since: typeof raw.since === 'string' ? raw.since : null, seen: raw.seen ?? 0 };
+  } catch {
+    return { since: null, seen: 0 };
+  }
+}
+
+export function writeState(file, state) {
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(state, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.root        project to read the inventory from
+ * @param {string} opts.api         scorecard base url
+ * @param {string|null} opts.since  cursor; null for the first run
+ * @param {number} opts.limit
+ * @param {typeof fetch} [opts.fetchImpl]  injected in tests
+ */
+export async function watch({ root, api, since, limit, fetchImpl = fetch }) {
+  const inv = inventoryFor(root);
+  const keys = installedKeys(inv);
+
+  const url = new URL('/feed', api);
+  if (since) url.searchParams.set('since', since);
+  url.searchParams.set('limit', String(limit));
+
+  const res = await fetchImpl(url.toString(), { headers: { accept: 'application/json' } });
+  if (!res.ok) {
+    const err = new Error(`feed returned HTTP ${res.status}`);
+    err.code = 3;                                   // could not measure, not broken
+    throw err;
+  }
+  const feed = await res.json();
+
+  const rows = (feed.candidates ?? []).map((c) => ({ ...c, ...classify(c, keys) }));
+
+  return {
+    api,
+    since_used: since ?? null,
+    next_since: feed.next_since ?? null,
+    inventory: {
+      root: inv.root ?? root,
+      // Counts are reported ALONGSIDE what could be read, never alone. "0
+      // agents" is a fact in a Claude Code project and an artefact of asking
+      // the wrong question in a Cursor one, and a caller has to be able to tell
+      // those apart before trusting "new to this build".
+      coverage: inv.coverage ?? { agents: 'unknown', skills: 'unknown', mcpServers: 'unknown' },
+      agents: (inv.agents ?? []).length,
+      skills: (inv.skills ?? []).length,
+      mcp_servers: (inv.mcpServers ?? []).length,
+      known_keys: keys.size,
+      notes: inv.notes ?? [],
+    },
+    counts: WATCH_VERDICTS.reduce((acc, v) => {
+      acc[v] = rows.filter((r) => r.verdict === v).length;
+      return acc;
+    }, {}),
+    candidates: rows,
+  };
+}
+
+export function renderWatch(r) {
+  const out = [];
+  out.push(`doorman watch  ${r.api}/feed`);
+  const cov = r.inventory.coverage ?? {};
+  const n = (count, seen) => (seen === 'read' ? String(count) : 'unknown');
+  out.push(`  inventory: ${n(r.inventory.agents, cov.agents)} agents, ` +
+           `${n(r.inventory.skills, cov.skills)} skills, ` +
+           `${n(r.inventory.mcp_servers, cov.mcpServers)} mcp servers, ` +
+           `${r.inventory.known_keys} known urls`);
+  if (cov.mcpServers !== 'read') {
+    out.push('  !! No MCP config was readable here, so "new to this build" below');
+    out.push('     means "not found in a config I could read", which is a weaker');
+    out.push('     claim. Everything may already be installed.');
+  }
+  for (const note of r.inventory.notes ?? []) out.push(`  note: ${note}`);
+  out.push(`  cursor:    ${r.since_used ?? '(first run: everything graded so far)'}`);
+  out.push('');
+
+  if (!r.candidates.length) {
+    out.push('Nothing new since the last run.');
+    out.push('Your cursor is unchanged, so nothing has been missed.');
+    return out.join('\n');
+  }
+
+  const order = ['unreviewed', 'blocked', 'already-installed', 'skipped'];
+  const heading = {
+    'unreviewed': 'NEW TO THIS BUILD  (not yet reviewed against it)',
+    'blocked': 'BLOCKED  (do not adopt)',
+    'already-installed': 'ALREADY INSTALLED',
+    'skipped': 'SKIPPED',
+  };
+
+  for (const v of order) {
+    const group = r.candidates.filter((c) => c.verdict === v);
+    if (!group.length) continue;
+    out.push(`${heading[v]}  (${group.length})`);
+    for (const c of group) {
+      const score = c.score === null || c.score === undefined ? '  n/a' : String(c.score).padStart(6);
+      out.push(`  ${String(c.grade ?? '?').padEnd(2)} ${score}  ${c.server_url}`);
+      out.push(`        ${c.why}`);
+      if (v === 'unreviewed') {
+        const unmeasured = ['behavioral_pct', 'guidance_pct']
+          .filter((k) => c.layers?.[k] === null || c.layers?.[k] === undefined);
+        if (unmeasured.length) {
+          out.push(`        ${unmeasured.length} of 3 layers NOT measured on this grade`);
+        }
+        out.push(`        tape: ${c.transcripts}`);
+      }
+    }
+    out.push('');
+  }
+
+  out.push('This was a mechanical overlap check, not a fit review. It knows what');
+  out.push('you already have. It does not know whether any of these would help,');
+  out.push('and it has not spent anything to find out.');
+  out.push('');
+  out.push('  doorman report <url>     what it implements, free');
+  out.push('  doorman eval <url> --task <file>   whether it makes YOUR agent better');
+  return out.join('\n');
+}

package/doorman/commands/doorman.md

@@ -0,0 +1,116 @@
+---
+description: The doorman front door. With no arguments it reports what is gating this build and what to do next. Usage: /doorman [allow <server> | check <url> | needs | status]
+---
+
+Doorman: $ARGUMENTS
+
+You are the front door for clembot-doorman. `/vet` is the deep path for grading
+a candidate; this is the one somebody reaches for when they do not yet know
+which command they want, and most often when the gate has just blocked them.
+
+## Preflight, before any branch below
+
+Every branch here shells out to the `doorman` CLI, and **installing the plugin
+does not put `doorman` on PATH**. It does not need to: the installed plugin
+directory carries its own copy. Resolve it once, first, and use `$D` everywhere
+below instead of a bare `doorman`:
+
+```bash
+D="$(bash "${CLAUDE_PLUGIN_ROOT:-.}/scripts/resolve-cli.sh")" && echo "$D"
+```
+
+That prints either a global `doorman`, or `node <plugin>/cli/doorman.mjs`,
+whichever exists. A global install wins, because the user chose it and it may
+be newer than the plugin cache.
+
+If it prints `NOT_FOUND`, stop and tell the user this, then end the turn:
+
+> The doorman CLI could not be located, from PATH or from the installed plugin.
+> Reinstall the plugin, or install the CLI directly:
+>
+> ```bash
+> git clone https://github.com/clemenswan/clembot-doorman
+> npm i -g ./clembot-doorman
+> ```
+>
+> The gate is still running either way. It is pure bash and depends on none of
+> this, so nothing is unprotected. You just cannot inspect or change the trust
+> list from here yet.
+
+Do **not** try to work around a missing CLI by reading or editing registry
+files by hand. The registry carries provenance fields (`basis`, `grade`,
+`audit_id`) that `doorman allow` writes correctly and a hand-edit loses, and a
+hand-written entry is indistinguishable from a measured one afterwards.
+
+**Pick the branch from $ARGUMENTS. If it is empty, run `status`.**
+
+## status (the default)
+
+```bash
+"$D" doctor .
+```
+
+Report, in this order, and stop after it:
+
+1. Whether the gate is running, and **from where**. A user-scope plugin gates
+   every project on the machine; a project install gates one. Those have
+   different blast radius and the user needs to know which they have.
+2. Which trust list is actually in force. The order is `$DOORMAN_REGISTRY_DIR`,
+   then `<project>/registry`, then `~/.doorman/registry`, then the plugin
+   default. Name the one being read, not all four.
+3. How many servers it trusts, and how many of those were **graded** versus
+   allowed by the operator. That ratio is the honest summary of the setup, and
+   `basis` on each entry is where it comes from.
+
+Then offer the next step that fits what you found, one line, no menu.
+
+## allow <server>
+
+The user has been blocked and wants the server through. They have a NAME, not
+a url, because `mcp__<server>__<tool>` is all the gate can see.
+
+```bash
+"$D" allow <server>              # ~/.doorman/registry, every project
+"$D" allow <server> --scope project   # ./registry, this project only
+```
+
+**Say what this is, every time, in one sentence:** it records a decision, not a
+measurement. The entry is written with `basis: operator` and a null grade
+because nothing graded the server. Never describe an allowed server as safe,
+vetted, or approved. It is permitted.
+
+Then offer the free measurement, once: `"$D" report <url>` needs no key.
+
+If it refuses because the server is on a denylist, do NOT work around it. Read
+the recorded reason back to the user and stop. A denial was earned by an audit.
+
+## check <url>
+
+```bash
+"$D" report <url>
+```
+
+Free, keyless, no model. Report the score, whether anything hard-failed, and
+the worst findings. Say plainly that this is the static layer: it describes
+what the server implements and what its tool descriptions say to a model. It
+does not say whether an agent can use it well, which is `doorman eval`.
+
+## needs
+
+```bash
+"$D" needs .
+```
+
+Read this build's own prompts and report unmet capabilities against the graded
+feed. Two things must survive into your summary: a match is `worth-measuring`
+and never `fits`, and a `GAP` means nothing graded covers that need, which is a
+hole in the catalogue rather than a fact about the user's build.
+
+## Rules that outrank anything above
+
+- **Never invent a grade, a score, or an audit id.** If it was not measured it
+  is null, and you say so.
+- **Never edit a registry by hand when `doorman allow` would do it.** The
+  command writes the provenance fields; hand-editing loses them.
+- **Never suggest disabling the gate to get past a block.** Allow the specific
+  server, or leave it blocked.

package/doorman/commands/vet.md

@@ -0,0 +1,69 @@
+---
+description: Vet a candidate before an agent gets it. Fit review first (free), paid grade only if the system actually needs it. Usage: /vet <url|repo|path> [what you need it for]
+---
+
+Vet: $ARGUMENTS
+
+**Three questions, in this order, and the order is the feature.** First: does
+this system need it at all? Second: can it afford to find out? Both are free and
+local. Only if both pass does anything get paid for.
+
+## Steps
+
+1. **Run it.** The flow is a program, not instructions, so the ordering cannot
+   drift and the "no charge on a redundant candidate" guarantee is testable:
+
+   ```bash
+   cd doorman && node scripts/vet.mjs <candidate> --needed-for "<purpose>"
+   ```
+
+   Add `--type mcp-server|skill|repo` if detection guesses wrong, and
+   `--dry-run` to run fit only and never construct a scorecard client.
+   `--max-usdc` and `--max-usdc-day` override the spend caps for this run.
+
+2. **Read the FIT block back to the human first**, before any grade. On
+   `redundant` or `out-of-scope` the run stops there having spent nothing, and
+   the overlaps are the answer: name what already covers the need. Do not
+   suggest grading it anyway.
+
+3. **Read the budget line too.** On `REFUSED  the spend cap said no`, report
+   the cap and what it would take to raise it. Do not raise it yourself, and do
+   not suggest a way around it: a cap the agent edits when it is inconvenient
+   is not a cap. On `REFUSED  could not read the price`, say that the price was
+   unreadable and that an unknown price is not a free one. Never guess a price.
+
+4. **On `fits` or `needs-new-subagent`**, the paid grade runs only for an MCP
+   server. A skill or a repo gets a fit review plus an injection scan of its
+   instruction text and reports `behavioral grade: n/a - no tools to probe`.
+   Never describe that as a grade, and never send one to the scorecard.
+
+5. **A review note is written to the vault**, status `pending`. Say where it
+   landed. If it fell back to `registry/reviews/`, say that too and say why.
+
+6. **Then, and only then, propose the registry change as a diff:**
+
+   - Band A or B, no hard fail  -> propose adding to `registry/allowlist.json`
+   - Band C                     -> allowlist PLUS the drafted recipe to
+                                   `recipes/<server>.md`, because a C means an
+                                   agent needs the recipe to succeed
+   - Band F, or any hard fail   -> propose `registry/denylist.json`
+
+   Show the diff. Do not apply it. The human decides what the gate trusts.
+
+## Never
+
+- **Never let a human's approval override a hard fail.** The poller refuses it
+  and logs the refusal into the note. Do not work around that by editing the
+  registry by hand.
+- **Never flip a note's `status` yourself.** `pending` is the resting state; a
+  person changes it. Nothing in this flow auto-approves.
+- **Never claim a grade for a skill or a repo.** They have no tools to drive, so
+  a behavioural grade cannot exist for them.
+- **Never advise bypassing the `mcp-gate` hook.**
+- **Never raise a spend cap on the human's behalf**, and never suggest
+  `--max-usdc` as a way past a refusal you triggered. Report the number and let
+  them decide.
+- **Never state a price the service did not give you.** If `GET /price` could
+  not be read, the price is unknown, and unknown is not zero.
+- Never edit `registry/allowlist.json` without showing the diff and getting an
+  explicit yes.

package/doorman/hooks/hooks.json

@@ -0,0 +1,30 @@
+{
+  "$comment": [
+    "The plugin's copy of the hook wiring. The file it points at is the SAME",
+    "mcp-gate.sh that install.sh copies, not a second copy: two gates would",
+    "drift, and the one that drifted would be the one still passing its tests.",
+    "",
+    "${CLAUDE_PLUGIN_ROOT} is the plugin's own directory. The non-plugin",
+    "install writes $CLAUDE_PROJECT_DIR/.claude/hooks/mcp-gate.sh instead, and",
+    "the gate resolves its registry the same way in both cases: the project's",
+    "trust list first, the shipped default only if the project has none.",
+    "",
+    "Timeout matches .claude/settings.json. The gate does no network and no",
+    "subprocess, so 5s is generous; it exists so a wedged hook fails rather",
+    "than hanging every tool call."
+  ],
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "mcp__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/.claude/hooks/mcp-gate.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/doorman/install.sh

@@ -0,0 +1,186 @@
+#!/usr/bin/env bash
+#
+# Install the doorman into a project, then PROVE it works there.
+#
+# The gate has its own test suite, and that suite proves the gate works in this
+# repo. It says nothing about whether the copy sitting in your project resolves
+# its registry, reads its lists, and blocks. A security control that was
+# installed slightly wrong looks exactly like one that is working: quiet.
+#
+# So this script ends by driving the INSTALLED gate at its INSTALLED path and
+# checking all four outcomes. If any of them is wrong it exits non-zero and says
+# the install is not safe to rely on, rather than printing a tick.
+#
+# What it deliberately does NOT do:
+#
+#   - It never edits your settings.json. Merging JSON in bash without jq is how
+#     a config gets silently clobbered, and the gate is dependency-free on
+#     purpose. It detects whether the hook is wired and prints the exact block.
+#   - It never overwrites an existing registry. That file is your trust list,
+#     built by hand over time, and replacing it with our three entries would be
+#     the most destructive thing this script could do.
+#
+# Usage:
+#   ./install.sh <path-to-your-project>
+#   ./install.sh <path-to-your-project> --dry-run
+#
+# Requires: bash. Nothing else. No node, no jq, no network.
+
+set -uo pipefail
+
+SRC="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+TARGET="${1:-}"
+DRY=0
+for a in "$@"; do [ "$a" = "--dry-run" ] && DRY=1; done
+
+say()  { printf '%s\n' "$*"; }
+warn() { printf '  !  %s\n' "$*" >&2; }
+die()  { printf '\nerror: %s\n\n' "$*" >&2; exit 1; }
+
+if [ -z "$TARGET" ] || [ "$TARGET" = "--dry-run" ]; then
+  die "usage: ./install.sh <path-to-your-project> [--dry-run]"
+fi
+[ -d "$TARGET" ] || die "no such directory: $TARGET"
+TARGET="$(cd -- "$TARGET" && pwd)"
+[ "$TARGET" = "$SRC" ] && die "that is this repo. Point it at the project you want to protect."
+
+say ""
+say "  doorman -> $TARGET"
+[ "$DRY" = 1 ] && say "  (dry run: nothing will be written)"
+say ""
+
+# ── 1. Copy ──────────────────────────────────────────────────────────────────
+#
+# Four things, and only one of them is allowed to be skipped: the registry,
+# because an existing one is yours.
+
+copy() {                      # copy <relative-src> <relative-dest-dir>
+  local from="$SRC/$1" to="$TARGET/$2"
+  if [ "$DRY" = 1 ]; then
+    say "  would copy   $1 -> $2/"
+    return 0
+  fi
+  mkdir -p "$to" || die "cannot create $to"
+  cp "$from" "$to/" || die "cannot copy $1"
+  say "  copied       $1 -> $2/"
+}
+
+copy .claude/hooks/mcp-gate.sh .claude/hooks
+copy agents/doorman.md   .claude/agents
+copy commands/vet.md     .claude/commands
+
+REGISTRY_KEPT=0
+if [ -f "$TARGET/registry/allowlist.json" ]; then
+  REGISTRY_KEPT=1
+  say "  KEPT         registry/ already exists. Not touching it: that is your"
+  say "               trust list, and ours has three entries in it."
+elif [ "$DRY" = 1 ]; then
+  say "  would copy   registry/ -> registry/"
+else
+  mkdir -p "$TARGET/registry" || die "cannot create $TARGET/registry"
+  cp "$SRC/registry/allowlist.json" "$SRC/registry/denylist.json" "$TARGET/registry/" \
+    || die "cannot copy the registry"
+  : > "$TARGET/registry/ledger.jsonl"
+  say "  copied       registry/ -> registry/"
+fi
+
+GATE="$TARGET/.claude/hooks/mcp-gate.sh"
+[ "$DRY" = 1 ] || chmod +x "$GATE" 2>/dev/null
+
+# ── 2. The hook wiring, which we will not do for you ─────────────────────────
+
+SETTINGS="$TARGET/.claude/settings.json"
+say ""
+if [ -f "$SETTINGS" ] && grep -q 'mcp-gate.sh' "$SETTINGS" 2>/dev/null; then
+  say "  hook         already wired in .claude/settings.json"
+else
+  if [ -f "$SETTINGS" ]; then
+    warn "settings.json exists but does not mention mcp-gate.sh."
+  else
+    warn "no .claude/settings.json yet."
+  fi
+  say ""
+  say "  Add this. Not doing it for you: merging JSON in bash is how a config"
+  say "  gets silently clobbered, and this file is yours."
+  say ""
+  cat <<'JSON'
+  {
+    "hooks": {
+      "PreToolUse": [{
+        "matcher": "mcp__.*",
+        "hooks": [{
+          "type": "command",
+          "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/mcp-gate.sh",
+          "timeout": 5
+        }]
+      }]
+    }
+  }
+JSON
+  say ""
+  say "  UNTIL YOU DO, THE GATE IS INSTALLED AND NOT RUNNING."
+fi
+
+if [ "$DRY" = 1 ]; then
+  say ""
+  say "  dry run complete. Nothing was written, and nothing was verified:"
+  say "  verification drives the installed gate, and there is not one yet."
+  exit 0
+fi
+
+# ── 3. Prove it ──────────────────────────────────────────────────────────────
+#
+# Four cases. Three of them are refusals, and a gate that refuses EVERYTHING
+# would pass all three while being useless, so the allow case is not optional.
+#
+# The allow case runs against this repo's own registry rather than the target's,
+# because after a KEPT registry we do not know what is on yours. That still
+# tests the code path that matters: read a list, find a match, exit 0.
+
+say ""
+say "  verifying the INSTALLED gate at $GATE"
+say ""
+
+fails=0
+probe() {                     # probe <expected-exit> <name> <tool> [env...]
+  local want="$1" name="$2" tool="$3"; shift 3
+  local out got
+  out="$(printf '%s' "{\"tool_name\":\"$tool\",\"tool_input\":{}}" \
+        | env "$@" bash "$GATE" 2>&1)"
+  got=$?
+  if [ "$got" = "$want" ]; then
+    printf '  PASS  %s\n' "$name"
+  else
+    printf '  FAIL  %s (wanted exit %s, got %s)\n' "$name" "$want" "$got"
+    printf '        %s\n' "$(printf '%s' "$out" | head -2)"
+    fails=$((fails + 1))
+  fi
+}
+
+probe 0 "an allowlisted server is allowed" mcp__scorecard__grade \
+      "DOORMAN_REGISTRY_DIR=$SRC/registry"
+probe 2 "a denylisted server is blocked" mcp__planted_bad__search_notes \
+      "DOORMAN_REGISTRY_DIR=$SRC/registry"
+probe 2 "an unknown server is blocked" mcp__zz_not_a_real_server_9f3a__search \
+      "DOORMAN_REGISTRY_DIR=$TARGET/registry"
+probe 2 "a missing registry blocks rather than opens" mcp__scorecard__grade \
+      "DOORMAN_REGISTRY_DIR=$TARGET/registry-does-not-exist"
+
+say ""
+if [ "$fails" != 0 ]; then
+  say "  $fails CHECK(S) FAILED. Do not rely on this install."
+  say "  The files are in place but the gate is not behaving. Most likely the"
+  say "  registry did not land next to .claude/, which is where the gate looks:"
+  say "  it resolves \$hook/../../registry, never a git root."
+  exit 1
+fi
+
+say "  4/4. The gate is installed and behaving."
+say ""
+if [ "$REGISTRY_KEPT" = 1 ]; then
+  say "  Your registry was left alone, so what is trusted has not changed."
+else
+  say "  Three servers are trusted, and they are ours. Everything else your"
+  say "  agent reaches for will be blocked until you grade it: /vet <url>"
+fi
+say ""

package/doorman/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "clembot-doorman",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Vets MCP servers, skills and repos before an agent gets them. Fit review first, paid grade second.",
+  "homepage": "https://clembot-doorman.wanessalabs.com",
+  "bin": {
+    "doorman": "./cli/doorman.mjs"
+  },
+  "scripts": {
+    "test": "node test/run.mjs",
+    "test:cli": "node test/cli-run.mjs",
+    "test:gate": "bash test-gate.sh",
+    "test:all": "node test/run.mjs && node test/cli-run.mjs && bash test-gate.sh && node test-poller.mjs"
+  },
+  "comment": [
+    "ZERO runtime dependencies, and that is a requirement rather than an",
+    "achievement. This repo is the giveaway: someone clones it into their own",
+    "project and expects a security gate to start working. Every dependency is",
+    "one more thing that can fail to install on their machine, and a gate that",
+    "fails to start is a gate that fails open.",
+    "",
+    "The same reasoning is why test/run.mjs is 40 lines instead of a runner,",
+    "and why cli/task.mjs hand-parses a strict YAML subset instead of pulling",
+    "in a yaml package. That parser REFUSES what it cannot read rather than",
+    "guessing: a task file that quietly means something other than it looks",
+    "like would corrupt an eval while every number still looked plausible.",
+    "",
+    "`bin` is the CLI surface: doorman report (L1) and doorman eval (L3).",
+    "L1 delegates to mcp-scorecard/runner/run.mjs rather than reimplementing",
+    "the static layer, per invariant 2."
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/clemenswan/clembot-doorman.git"
+  }
+}