Gatekeeper

Repo: this skill's folder (installed as a symlink at ~/.claude/skills/gatekeeper). CLI: python3 ~/.claude/skills/gatekeeper/bin/gatekeeper <command>, or bin/gatekeeper from the repo.

A gate name resolves to gates/local/<gate>.yaml (private, git-ignored) first, then gates/<gate>.yaml, then examples/<gate>/<gate>.yaml. A path to a YAML file works anywhere a gate name does, except log --gate, which takes the gate's gate: name.

event -> hard_rules (code) -> judgments (one Jev request) -> decide (first match) -> verdict + log

Commands

judge, explain, and bench call Jev and need TYPESAFE_API_KEY. The client reads it from the environment, then the file named by GATEKEEPER_ENV_FILE, then ~/.config/gatekeeper/env. Never print it.

Editing a rulebook (gates/<gate>.yaml)

1. Read the rulebook and gates/_schema.json first.
2. Put anything a regex or comparison can decide in hard_rules. Put only the semantic part in judgments.
3. One narrow question per judgment. A Choice needs an escape option when nothing may fit.
4. Bands are per judgment and follow the cost of a wrong call. They stay untuned guesses until bench over reviewed labels says otherwise.
5. Bump version whenever a rule, band, or option changes, so the log shows which rulebook made each decision.
6. Run bin/gatekeeper lint <gate> and python3 -m pytest -q before reporting done.

New gate

Copy the shape of gates/agent-selection.yaml: state.fields names the event fields Jev sees, judgments holds the questions, and decide maps answers to verdicts. A new domain (for example email triage) needs a new YAML file plus whatever adapter turns its input into an event dict. The engine does not change.

Rosters from an index

A gate can route to Markdown procedures instead of Claude Code agents: set roster.sources: [index] and point roster.index.file at a JSON list (fields for name, description, group, and path are configurable). Add rollup: group to the Choice and the engine also sums probabilities by group, so a decide rule can use group_band: act when the exact handler is unclear but its group is not. See examples/marketing-team/. Such gates run in advise mode.

Enforcement (agent-selection)

The hooks are installed with scripts/install_hooks.py (--global or --project, dry run by default). shadow only logs what it would inject or deny. advise injects the verdict as context but never blocks or denies. enforce injects the route as context and denies Agent or Skill calls that break an act-band route or a forbid rule. GATEKEEPER=off disables every hook at once. The hooks fail open: a Jev outage never blocks work. A handler named in the prompt is never denied. Harness messages (passthrough) are never judged. See README "Safety rules".

Keep it working

The gate fails open, so a broken gate looks exactly like a quiet one. Run bin/gatekeeper doctor monthly, after installing or removing agents or skills, after a Claude Code update, and always before mode ... enforce. It checks the key, that the pinned model still answers, what jev-latest now serves, hook installs, the fail-open rate in the log, harness messages that slipped past passthrough, handlers no rule covers, and whether the bench is stale.

• FAIL: fix before anything else. The gate is not judging.
• WARN: fix soon. Each line carries its own fix:.
• INFO: a choice for the user (for example a newer Jev version to bench).
• Never move model: or a band without a fresh bench on the new setting.

Rules

• Gatekeeper decides who handles work. It never sends, publishes, or spends.
• Typed output guarantees the shape, not the truth. Tune on labelled data.
• Only a hand-reviewed bench can move a threshold. Draft labels (label_source: claude-draft) are a starting point.
• Re-check the Jev model, limits, and price against GET https://api.typesafe.ai/v1/models and docs.typesafe.ai before relying on them.