#186 docs: catalogue every ReasonCode and what it means (docs/REASON_CODES.md)

[Anonymous]

Originally created by: fu351

What

ReasonCode (src/doberman/models.py, class ReasonCode(StrEnum) at line 204) is Doberman's explainability contract: every non-PASS decision carries reason codes plus a human explanation. There are 51 codes today and no single page lists them. Add docs/REASON_CODES.md: a table with one row per ReasonCode value — code, the module that raises it, and what it means to a user.

Difficulty: level-2

Reading + transcription across a few files, no code changes, but accuracy matters — this is part of Doberman's explainability contract, so double-check each code against where it's actually raised (grep -rn "ReasonCode\.<name>" src/doberman) rather than guessing from the name alone.

Starting files

• src/doberman/models.py — class ReasonCode(StrEnum) (line 204) is the full enum, grouped by feature in comments (objective guardrail, roles/policy, subjective guardrail, token-channel defense, host-hook containment, turn gate, egress broker reconciliation).
• src/doberman/engine/rules/ and src/doberman/engine/detectors/ — where most objective/subjective codes are raised.
• New file: docs/REASON_CODES.md.

Acceptance criteria

• [ ] Every ReasonCode member has exactly one row.
• [ ] Existing behaviour unchanged (no test weakened, no output format broken)
• [ ] ruff check . && ruff format --check . and lint-imports pass
• [ ] pytest passes

How to validate

python -c "from doberman.models import ReasonCode; print(len(list(ReasonCode)))"
# confirm this number (51 as of v0.16.0) matches the row count in docs/REASON_CODES.md

Out of scope

• Do not change any reason-code names or values.
• Do not add new reason codes (see the base64-blob-detector issue for one that does).

Notes for contributors

New here? Start with CONTRIBUTING.md. Issues are labelled level-1 (docs only) through level-10 (new subsystem) — pick one at your level and climb. Comment to claim an issue before starting.

[Anonymous]

Ticket changed by: fu351

• status: open --> closed