trustabl-rulebook

Index and rationale docs for the trustabl
static analyzer's policy ruleset. Canonical YAML rules live in
trustabl/agent-reliability-rules — this
repo links into them and explains the threat model behind each rule.

Coverage spans eight agent frameworks, a protocol-level rule family for the
Model Context Protocol, and a family for Claude Skills:

• Claude Agent SDK (CSDK-*) — claude_sdk/
• OpenAI Agents SDK (OAI-*) — openai_sdk/
• Google ADK (ADK-*) — google_adk/
• LangChain / LangGraph (LC-*) — langchain/
• CrewAI (CREW-*) — crewai/
• AutoGen / AG2 (AG2-*) — autogen/
• Vercel AI SDK (VAI-*) — vercel_ai/
• Pydantic AI (PYD-*) — pydantic_ai/
• Model Context Protocol (MCP-*) — mcp/
• Claude Skills (CSKILL-*) — docs/Policy/claude_skill/

What lives here

ID scheme

ID prefix denotes SDK; numeric range denotes scope.

CSKILL-* is the exception: every rule in that family is skill-scope, so its
numeric ranges group rules by topic rather than by scope.

Risk score = severity_weight × confidence × 100. Weights: critical=1.0,
high=0.70, medium=0.40, low=0.15, info=0.05. Higher = worse.

Current totals

Counts are generated, not maintained here — that is what keeps them honest.
POLICY_INDEX.md carries the per-family breakdown by scope and
the full rule table; <sdk>/POLICY_INDEX.md carries the same for one family.
Both are a pure projection of the shipped pack, regenerated by
tools/gen_index.py and verified in CI by tools/gen_index.py --check.

Rationale coverage is likewise enforced rather than described:
tools/check_rulebook.py --strict fails the build when a shipped rule has no
rationale doc, or when a doc's severity/confidence/scope disagrees with the
pack. A green CI run means every rule in
trustabl-rules is documented here.

Using the rulebook

This repo is documentation only — it contains no rule YAML and the trustabl
engine never reads it. The engine resolves rules from
trustabl/agent-reliability-rules: at scan
time it clones the configured ref and caches it under
os.UserCacheDir()/trustabl/rules/<sha>/. The rulebook exists so a human can
look up why a rule fires (the threat model and references) without reading the
engine source.

To run a scan against a different rules pack or pin a version, point the
engine at an agent-reliability-rules repository/ref with --rules-repo /
--rules-ref (or the TRUSTABL_RULES_REPO env var); --no-rules-update uses
the local cache only. See the trustabl engine README for the full flag list.

Contributing a rule

A rule spans three repos. The YAML lives in agent-reliability-rules; the rationale
doc lives here; the test mirror lives in the engine.

1. Read the rule-authoring contract in
   agent-reliability-rules/CLAUDE.md
   — required fields, per-scope applies_to values, ID conventions, severity
   guidance.
2. Add the YAML rule to agent-reliability-rules under <sdk>/<topic>.yaml.
3. Copy the template from
   docs/policy-rationale-doc-template-guide.md,
   fill every section, and add the paired rationale here at
   docs/Policy/<sdk>/<topic>.md.
4. Mirror the rule into the engine repo's testdata/rules-fixture/ with at
   least one fire case and one silent case (see the engine's
   testdata/rules-fixture/CLAUDE.md, "Add a rule for X").
5. Open the PRs. The rule appears in POLICY_INDEX.md once
   the rulebook PR merges.

Companion repos

• trustabl/agent-reliability-rules —
  canonical YAML rules pack. The engine loads this at runtime; rule edits
  land here.
• trustabl/agent-reliability-analyzer — the analyzer
  binary that consumes the rules pack.