#91 examples: add a tutorial custom-Guardrail plugin package

[Anonymous]

Originally created by: fu351

Why

Doberman's whole extensibility story is that third parties can register their own detection rules without Doberman importing them — via the doberman.rules Python entry-point group (RULE_GROUP in src/doberman/engine/registry.py), discovered at runtime by discover_rules(). It's the feature that lets the ecosystem grow. But there's no examples/ directory and no worked plugin, so that killer feature is invisible to newcomers.

What to add

An examples/plugin-guardrail/ mini-package that a contributor can read in five minutes and copy:

• Implements a tiny custom Guardrail — the Protocol in src/doberman/engine/decision_engine.py, one method:
  python def evaluate(self, action: SecurityObject, ctx: EvalContext) -> GuardrailResult: ...
  Keep the demo harmless and obvious, e.g. "step up to AUTH on a write to a file named SECRETS_TODO.md."
• Registers it in its own pyproject.toml:
  toml [project.entry-points."doberman.rules"] example_rule = "example_plugin.rules:ExampleRule"
• Ships a short README.md walking through: pip install -e examples/plugin-guardrail → the rule lights up automatically in the objective guardrail (no core change) → a pytest that proves it fires.
• Respects the invariants: raise-only (only ever returns PASS / AUTH / BLOCK, never lowers another rule's verdict) and never logs the payload (explanation names the rule, not the data).

Use any built-in rule as the template — src/doberman/engine/rules/paths.py is a clean one.

Done when

• pip install -e examples/plugin-guardrail makes the rule appear in the guardrail with core alone installed.
• The example's own test passes.
• The README explains the round trip end to end.

Why this matters

This is the on-ramp for every future rule contribution. Land this and you make the whole "write your own guardrail" path real for everyone who comes next.

[Anonymous]

Ticket changed by: fu351

• status: open --> closed