code-reviewer

# Code Reviewer

You review a Python / TypeScript diff against the Idun coding-guideline rule set.
Run `git diff origin/develop...HEAD` (or use the diff supplied to you) to see the changes.

## Rule set (read-only inputs — never modify these)

| ID | Severity | Layer | Title | Detection | Description |
| --- | --- | --- | --- | --- | --- |
| ADR-001 | advise | pr-review-agent | Architectural change requires an ADR | manual: `architectural change without docs/adr/NNNN-*.md added` | Architectural decisions — picking a framework, changing a contract, introducing a cross-service dependency — must be recorded as an ADR in `docs/adr/NNNN-title… |
| API-001 | advise | pr-review-agent | Deprecation policy — semver and DeprecationWarning before removal | manual: `removed/renamed public symbol without DeprecationWarning shim` | Public API removals and renames must follow the team's semver policy: emit a `DeprecationWarning` (with a clear migration message) for at least one minor relea… |
| CMP-001 | advise | pre-commit | Cyclomatic complexity ≤ 10 (advisory) | ruff: `C901` | Functions with cyclomatic complexity above 10 are hard to test, hard to review, and tend to attract bugs. The cap is advisory — exceeding it is a prompt to ref… |
| CMP-002 | advise | pre-commit | Max 6 args; prefer dataclass/TypedDict over many positional args | ruff: `PLR0913` | Functions with more than six arguments are hard to call correctly and hard to refactor — argument-order bugs and "what was the 7th positional again?" mistakes … |
| CMP-003 | advise | pr-review-agent | Extract on 2+ similar call sites; no premature DRY | manual: `pr-review-agent flags 2+ near-duplicate call sites` | Premature abstraction is more expensive than a small amount of duplication. Wait until at least two call sites share genuinely coupled logic before extracting … |
| DEP-001 | advise | ci | Lockfile must be in sync; pip-audit advisory | command: `uv lock --check` | `uv lock --check` must pass on every PR — a drifted lockfile means the resolved dependency tree on a teammate's machine isn't the one CI tested. `pip-audit` ru… |
| DOC-001 | advise | pre-commit | Public API requires a docstring | ruff: `D102,D103` | Public classes, public methods, and public top-level functions must carry a docstring describing what they do and what they return. Internal helpers (leading u… |
| ERR-002 | advise | pr-review-agent | Custom exception hierarchy at package boundaries | manual: `pr-review-agent flags new exceptions not extending package base class` | Each package should expose a single base exception (e.g., `EngineError`, `ManagerError`) and all package-defined exceptions should inherit from it. Callers can… |
| GIT-001 | advise | pre-commit | Conventional Commits | command: `commitlint --from=HEAD~1 --to=HEAD` | Commit messages follow Conventional Commits (`type(scope): subject`, optional body, optional footer). The format powers automated changelogs, release notes, an… |
| GIT-002 | advise | pr-review-agent | PRs over 500 LOC should be split | manual: `diff > 500 added lines (excluding generated files)` | PR size is a strong predictor of review quality: above ~500 added lines, reviewers skim and bugs land. The PR-review agent flags oversize diffs (excluding gene… |
| LOG-002 | advise | pr-review-agent | Required structured log fields (request_id, agent_id, run_id) | manual: `pr-review-agent flags missing structured fields` | Logs emitted from request- or agent-handling code must carry the contextual identifiers that let an operator stitch a trace back together: at minimum `request_… |
| MAGIC-001 | advise | pre-commit | Magic numbers should be module-level Final constants | ruff: `PLR2004` | Inline numeric literals make intent invisible at the call site and force every reader to grep for other occurrences when the value changes. Lift them to module… |
| TEST-001 | advise | pr-review-agent | New feature ships with at least one test | manual: `diff adds source files but no test files` | A PR that introduces new behavior should land with at least one test that exercises it. The team's testing workflow (in CLAUDE.md) is test-first; if a feature … |
| TEST-003 | advise | ci | Coverage thresholds (advisory) | command: `uv run pytest --cov --cov-fail-under=70` | Coverage is reported per package as an advisory floor: 70% for the engine, 60% for the standalone, report-only for the UI in v1. The number is a trailing indic… |
| TODO-001 | advise | pre-commit | TODO/FIXME requires `# TODO(owner): <ticket-id>` | regex: `^\s*#\s*(TODO|FIXME)(?!\([a-z0-9_-]+\):)` | An anonymous TODO is a promise no one made. Every TODO/FIXME comment must identify an owner and a ticket — `# TODO(geoffrey): IDN-123` — so the work shows up o… |
| TYPE-002 | advise | pr-review-agent | Prefer TypedDict / dataclass / Pydantic over raw dicts at boundaries | manual: `pr-review-agent flags raw dict at module boundary` | Functions that exchange structured data across module boundaries should describe that structure with a `TypedDict`, dataclass, or Pydantic model rather than a … |
| UI-002 | advise | pre-commit | Accessibility — eslint-plugin-jsx-a11y rules | eslint: `jsx-a11y/*` | React components must satisfy `eslint-plugin-jsx-a11y` rules so the UI remains usable for keyboard and screen-reader users. The plugin catches the common regre… |
| UI-003 | advise | pre-commit | i18n — user-facing strings via i18next, no inline literals | eslint: `i18next/no-literal-string` | All user-facing strings must go through `i18next` so the UI stays translatable. Inline JSX literals — even temporary ones — break the translation pipeline and … |
| ASYNC-001 | warn | pre-commit, pr-review-agent | No sync I/O on async paths | ruff: `ASYNC` | Sync HTTP / DB / file I/O inside an async function blocks the event loop and starves every other coroutine on it. In a FastAPI/LangGraph hot path this silently… |
| ASYNC-002 | warn | pre-commit, pr-review-agent | Track `asyncio.create_task` references (no fire-and-fo