Learnt from: CR
Repo: Aureliolo/synthorg

Timestamp: 2026-06-28T17:32:58.937Z
Learning: Present every plan for accept/deny before coding.

Learnt from: CR
Repo: Aureliolo/synthorg

Timestamp: 2026-06-28T17:32:58.937Z
Learning: Every convention PR must ship its enforcement gate.

Learnt from: CR
Repo: Aureliolo/synthorg

Timestamp: 2026-06-28T17:32:58.937Z
Learning: Do not edit `tests/baselines/unit_timing.json` or any `scripts/*_baseline.*`; timeout and slow-test failures are source regressions, and baseline growth requires explicit approval.

Learnt from: CR
Repo: Aureliolo/synthorg

Timestamp: 2026-06-28T17:32:58.937Z
Learning: After an issue, branch, commit, and push; do not auto-create PRs; use `/pre-pr-review` and then `/aurelio-review-pr` after the PR, fixing every valid issue rather than deferring.

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 1760
File: scripts/_dual_backend_parity_lib.py:215-216
Timestamp: 2026-05-05T09:04:46.195Z
Learning: This repository targets Python 3.14+ and follows PEP 758. Therefore, reviewer tooling should NOT treat unparenthesized multi-exception `except` clauses written without an `as` clause (e.g., `except MemoryError, RecursionError:`) as syntax errors. Only flag `except`-clause problems when they are genuinely invalid for Python 3.14+.

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 2035
File: src/synthorg/meta/toolsmith/models.py:114-114
Timestamp: 2026-05-21T22:55:20.496Z
Learning: In this repo’s “magic number” review standard, the existing gate in `scripts/check_no_magic_numbers.py` intentionally does NOT flag numeric literals used as raw call-site arguments. So, do not flag numeric literals passed as keyword arguments to Pydantic `Field()` (e.g., `Field(ge=0, le=100)` / `Field(ge=1, le=50)`)—this is an established idiom. Only treat numeric literals as “magic numbers” when they occur in the locations the gate checks (module-level assignments and function/method parameter defaults).

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 2160
File: src/synthorg/persistence/sqlite/escalation_repo.py:370-370
Timestamp: 2026-05-29T08:50:58.380Z
Learning: In this repo, Ruff flake8-unused-arguments (ARG002) already suppresses unused-argument warnings on parameters of methods decorated with `override` (from `typing`). Therefore, if you see `# noqa: ARG002` (or equivalent) on parameters of an `override`-decorated method, treat it as stale/unused and remove it. Do not recommend re-adding `# noqa: ARG002` in these cases, because Ruff will flag the redundant directive (RUF100) and fail the Ruff CI gate.

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 2283
File: src/synthorg/engine/evolution/config.py:278-280
Timestamp: 2026-06-09T09:22:47.752Z
Learning: This repository uses ruff rule TC006 (`runtime-cast-value`), which requires the quoted string-literal form for the type argument in `cast()` calls (e.g., `cast("object", value)` rather than `cast(object, value)`). During code review, do not suggest removing the quotes from the `cast(<type>, ...)` first argument; the unquoted form will be auto-reverted by ruff on commit, so the quoted form should be treated as lint-compliant.

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 2080
File: tests/_shared/test_postgres_proxy.py:19-48
Timestamp: 2026-05-23T12:24:00.128Z
Learning: When creating test doubles for Python typing.Protocols in tests, prefer a hand-written Protocol fake (a concrete class that explicitly implements the Protocol) over `mock_of[T]` if the Protocol only defines annotation-only attributes (e.g., `username: str`, `password: str`, `dbname: str`) with no class-level values/assignments. This is because `mock_of[T]` relies on `create_autospec(..., spec_set=True)`, which enumerates members via `dir(spec)`; annotation-only attributes are not included, so `mock_of`’s kwarg-based attribute setting can raise `AttributeError: attribute not present on spec type`. In that annotation-only case, don’t recommend `mock_of[T]`—use an explicit fake class instead.

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 2311
File: tests/conformance/persistence/test_workflow_service.py:77-77
Timestamp: 2026-06-11T11:04:22.231Z
Learning: When using Aureliolo/synthorg test-id helpers, treat `sid(label)`/`as_uuid(label)` as label-only functions that deterministically hash a human-readable label into a UUID (uuid5). Do NOT call them on an already-canonical UUID value (string or `UUID` object), since this re-hashes into a different UUID and breaks key matching/persistence. Instead:
- Use `coerce_id(value)` / `as_pk(value)` for pass-through-or-hash behavior (accept label or canonical UUID/`UUID` object and return the canonical form without re-hashing).
- If you already have a `UUID` object (e.g., `definition.id`), use `str(definition.id)` (or `coerce_id(definition.id)` / `as_pk(definition.id)`) for string-key conversion—never `sid(str(definition.id))`.

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 2415
File: tests/unit/api/controllers/test_decomposition.py:118-139
Timestamp: 2026-06-19T14:28:19.662Z
Learning: For pytest test modules in this repo, if the module defines a module-level `pytestmark = pytest.mark.<marker>` (e.g., `pytest.mark.unit`, `pytest.mark.integration`, `pytest.mark.e2e`, `pytest.mark.slow`), then individual test functions in that module do not need their own per-function `pytest.mark.<marker>` decorators to satisfy the repo’s marker requirement. Only flag a missing per-function marker when the module does not set `pytestmark` and the test function also lacks the required `pytest.mark.<marker>` marker(s).

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 2415
File: tests/unit/observability/audit_chain/test_signer.py:61-93
Timestamp: 2026-06-19T14:28:49.107Z
Learning: For pytest test modules under tests/, if the module defines a module-level marker like `pytestmark = pytest.mark.unit`, then the repository requirement “tests carry the unit marker” is satisfied for that module. In that case, do not flag individual test functions for missing `pytest.mark.unit` decorators solely because they lack per-function decorators—per-function markers would be redundant unless the module-level `pytestmark` is missing or not applicable.

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 2200
File: tests/unit/engine/artifacts/test_service.py:42-45
Timestamp: 2026-06-03T11:43:13.104Z
Learning: For the D7 protocol method `save_returning_outcome(artifact: Artifact) -> bool` defined in `src/synthorg/persistence/artifact_protocol.py`, any implementation—including fake/stub/test doubles—must use the exact same parameter name `artifact` (i.e., `save_returning_outcome(self, artifact=...)` / `save_returning_outcome(self, artifact: Artifact)`), not `entity`. This name must match for typeguard positional-or-keyword name conformance. Do not suggest renaming the protocol method’s parameter to `entity`.

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 2283
File: src/synthorg/engine/middleware/coordination_constraints.py:152-152
Timestamp: 2026-06-09T10:06:53.040Z
Learning: Use International/British English spellings throughout the repository (code comments, docstrings, and documentation). British spellings such as "Analyse" (not "Analyze"), "Behaviour" (not "Behavior"), and "Colour" (not "Color") are mandatory and should not be flagged as spelling errors or inconsistencies during code review. This repo’s style is enforced via `vale` (see `CLAUDE.md` → "Regional Defaults (MANDATORY)"). If an American spelling appears, prefer the corresponding British spelling.

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 2348
File: docs/guides/custom-mcp-server-dev.md:155-161
Timestamp: 2026-06-13T08:51:11.124Z
Learning: When reviewing Aureliolo/synthorg usage of `mcp_descriptor()` (from `src/synthorg/meta/mcp/feature_descriptors.py`), ensure all call sites pass the keyword argument `handlers=...` (type `Callable[[], Mapping[str, object]]`). `mcp_descriptor()` maps this `handlers` value internally to the descriptor’s `handlers_factory` field; `handlers_factory=...` is not a valid keyword and will raise `TypeError: unexpected keyword argument`. Also ensure documentation and code examples do not suggest renaming `handlers` to `handlers_factory`; always show `handlers=`.

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 2159
File: web/src/__tests__/stores/auth-sessions.test.ts:8-8
Timestamp: 2026-05-28T22:27:09.037Z
Learning: In the frontend, `SessionInfo` is a local type alias for `SessionResponse` defined only in `web/src/api/types/auth.ts` (exported as `SessionResponse as SessionInfo`). It is not re-exported via the `@/api/types` barrel (which only re-exports `dtos.gen` including `SessionResponse`). Therefore, all code (including React components, stores, and tests) that needs `SessionInfo` must import it from `@/api/types/auth` and not from `@/api/types`. (Import `SessionResponse` from `@/api/types` only when `SessionResponse` is what you need.)

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 2159
File: web/src/__tests__/stores/backups.test.ts:9-9
Timestamp: 2026-05-28T22:27:14.761Z
Learning: In the synthorg web package, follow the established convention for importing DTOs from the domain-specific sub-barrels under `@/api/types/<domain>`, e.g. `import type { BackupInfo } from '`@/api/types/backup`'`. These domain sub-barrels are curated and re-export from generated DTOs (e.g., `./dtos.gen`), so they are not considered “deep reach” imports. Do not recommend changing these imports to the top-level `@/api/types` barrel (e.g., `@/api/types`)—production code and tests consistently use the domain-specific sub-barrel paths (such as `stores/backups.ts`, `AdminBackupsPage.tsx`, and `mocks/handlers/backup.ts`).

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 2159
File: web/src/__tests__/stores/workflows-export.test.ts:7-7
Timestamp: 2026-05-28T22:27:25.293Z
Learning: When reviewing code in this repository, if the change touches or adds types related to workflows, ensure those imports come from the domain-specific curated barrel at `@/api/types/workflows` (e.g., `@/api/types/workflows`), not from the top-level `@/api/types` barrel. Do not recommend switching workflow-related type imports to the top-level barrel; this convention is the established pattern across workflow UI/components, workflow editor store code, related hooks, and workflow-related tests.

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 2163
File: web/src/pages/providers/provider-form-helpers.ts:1-9
Timestamp: 2026-05-29T15:33:54.576Z
Learning: In the synthorg web package (web/src), import provider-related DTO types (e.g., AuthType, CloudPreset, CreateFromPresetRequest, CreateProviderRequest, ProviderConfig, ProviderPreset, UpdateProviderRequest) from the domain sub-barrel `@/api/types/providers` and not from the top-level `@/api/types` barrel. These types are not re-exported from `@/api/types`; using the top-level barrel will cause compilation errors. Follow the established convention when updating provider-related code and imports.

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 2163
File: web/src/pages/setup/CompanyStep.tsx:18-18
Timestamp: 2026-05-29T15:35:11.914Z
Learning: In the synthorg web package, when using setup-related DTO types (e.g., `SetupAgentSummary`, `SetupCompanyResponse`), import them from the setup domain sub-barrel `@/api/types/setup` rather than from the top-level `@/api/types`. The setup DTOs are not re-exported from `@/api/types`, so importing from the top-level barrel will fail to compile. Follow the existing domain-sub-barrel convention used elsewhere (e.g., `@/api/types/backup`, `@/api/types/workflows`, `@/api/types/auth`) and do not recommend moving setup-domain type imports to `@/api/types`.

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 2172
File: web/src/pages/project-brain/BrainEntryList.tsx:12-45
Timestamp: 2026-05-31T00:00:32.734Z
Learning: In the synthorg web package, do not flag React components for ESLint `max-params` violations based on destructured prop fields. ESLint `max-params` counts the number of function parameters (arity), not properties inside a destructured object. For example, `function BrainEntryList({ entries, loading, hasMore, ... }: BrainEntryListProps)` has exactly 1 parameter (the props object) and should not be considered a `max-params: 5` violation, even if the props type/interface contains 10+ fields. Only flag when a function declares 6+ separate parameters.

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 2356
File: web/src/components/ui/ws-connection-banner.tsx:30-45
Timestamp: 2026-06-13T14:07:55.334Z
Learning: In the synthorg web package, treat leading underscores on function names as an intentional convention for module-local, non-exported helper/utility functions (e.g., `_resolveBannerKind`, `_handleConflict`, `_statusFallback`, `_hasRequiredCredentials`, `_decideRetryWait`, `_shouldKeepRetrying`). Do not flag these or suggest renaming to remove the underscore. This does not conflict with React hook linting rules (e.g., the rule that React hook/sub-hook helpers must start with `use` and must not use leading underscores); only apply that hook-specific guidance to actual hook helpers, not plain utility functions.

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 2476
File: web/CLAUDE.md:31-34
Timestamp: 2026-06-25T14:59:52.946Z
Learning: For the TypeScript/React web dashboard code under web/src (e.g., dashboard utilities/components), follow the web logging convention: import and use `createLogger` from `@/lib/logger`, and name the resulting logger variable `log`. Do not apply the Python backend logging helper pattern (`get_logger` from `src/synthorg/observability/_logger.py` and its `logger` variable) to web TypeScript files.

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 2035
File: src/synthorg/meta/toolsmith/config.py:29-30
Timestamp: 2026-05-21T22:55:09.289Z
Learning: For this repo’s Pydantic configuration idiom, do not treat numeric literals passed directly as arguments to `pydantic.Field(...)` as “magic numbers” during review. This includes call-site usages like `Field(default=0.2, ge=0.0, le=1.0)` (e.g., in config models such as `ToolAuthoringConfig`, `ToolValidationConfig`, `ToolsmithConfig`). Do not request extracting those `Field(...)` numeric arguments into named constants, since the repo’s `scripts/check_no_magic_numbers.py` intentionally excludes call-site `Field(...)` numerics and relies on `Field(...)` as the canonical way to express these constraints/defaults.

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 2511
File: src/synthorg/engine/quality/decomposers/llm.py:371-373
Timestamp: 2026-06-28T17:04:20.222Z
Learning: When reviewing calls to `cost_recording_scope(...)` in this repository, do not flag missing prompt-class attribution if the call explicitly passes `purpose=None` as an intentional opt-out path under the `check_cost_scope_purpose` gate. This is sanctioned for prompts that are intentionally outside the registered prompt-class inventory. In particular, if the code comments/documentation indicate the cost is charged to the calling evaluator (not to a registered system prompt class)—for example in `LLMCriteriaDecomposer._invoke_provider` (`src/synthorg/engine/quality/decomposers/llm.py`)—treat the lack of prompt-class attribution as expected and do not raise a review issue.

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 2180
File: src/synthorg/engine/intervention/models.py:182-203
Timestamp: 2026-05-31T18:00:32.445Z
Learning: In this repository, `NotBlankStr` is a Pydantic `Annotated[str, ...]` type alias (defined in `synthorg/core/types.py`). At runtime, calling `NotBlankStr(value)` acts like an identity/cast to `str(value)` and does not execute the `StringConstraints` or `AfterValidator(...)`. Therefore, during code review, do not treat `NotBlankStr(x)` used inside non-Pydantic model methods as a place that would raise `ValidationError`; it won’t. Similarly, when `tuple[NotBlankStr, ...]` values are involved, `NotBlankStr` erases to `str` at runtime, so membership tests/comparisons can be done with raw `str` values.

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 2295
File: src/synthorg/project_brain/service.py:77-80
Timestamp: 2026-06-10T12:09:37.293Z
Learning: Do not flag or recommend moving imports out of `if TYPE_CHECKING:` in `src/synthorg` when the imported class is a collaborator type that’s intentionally “concrete-faked” in tests (duck-typed stubs injected into code under constructor/typing annotations). This pattern is used to avoid runtime import side effects where runtime type enforcement (e.g., `typeguard`/`isinstance` checks against the concrete type) would cause the test fakes to be rejected. If the code relies only on annotations for those collaborators and tests provide duck-typed stubs, keep the import under `TYPE_CHECKING` rather than promoting it to a module-level runtime import.

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 2295
File: src/synthorg/settings/dispatcher.py:43-46
Timestamp: 2026-06-10T12:09:46.221Z
Learning: In this repository’s Python modules, do not treat `if TYPE_CHECKING:` imports as violations of any “hoist to module level” rule when they are deliberately used to support duck-typed test fakes (“concrete-faked collaborators”).

Concretely: if the code includes a comment/docstring indicating that tests drive the module using a duck-typed stub (e.g., “Concrete-faked collaborator: tests drive … with a duck-typed … stub, so a runtime import would make typeguard reject the fake”), then keep that collaborator import/type reference under `if TYPE_CHECKING:` rather than importing it at runtime. The intent is to avoid runtime typeguard validation rejecting the test fake; these guards are intentional and should not be flagged.

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 2423
File: src/synthorg/api/lifecycle.py:292-292
Timestamp: 2026-06-20T14:08:03.848Z
Learning: When reviewing calls to `provider_credential_catalog_of(app_state)` (from `src/synthorg/integrations/state.py`), treat it as a soft/optional accessor: it returns `None` when the provider credential catalog is not wired and does not raise. Do not flag such uses as potentially raising exceptions or as hard dependencies that would disable functionality if the catalog is absent. (By contrast, `connection_catalog_of(app_state)` is a hard accessor that raises via `require_service`.)

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 2231
File: web/src/pages/org/build-org-tree-types.ts:122-122
Timestamp: 2026-06-05T10:17:59.769Z
Learning: When indexing an exhaustive TypeScript `Record<K, V>` (e.g., `SENIORITY_RANK: Record<SeniorityLevel, number>`) using a value whose parameter/type is the same union key type (e.g., `seniorityOf(level: SeniorityLevel)`), TypeScript already guarantees the key is covered at build time. In this case, do NOT request a runtime `?? fallback` or suggest handling for an `UNKNOWN` key unless the codebase has an explicit/ documented runtime drift or “unrecognized value” contract (like the one handled in `computeCategoryBreakdown` in `web/src/utils/budget.ts`). Also, don’t suggest non-existent keys that are not part of the union type.

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 2399
File: web/src/api/types/openapi.gen.ts:8700-8700
Timestamp: 2026-06-17T16:00:52.690Z
Learning: In this repo, `*.gen.ts` files are canonical TypeScript generator outputs produced by `uv run python scripts/generate_dto_types_ts.py` (with sync enforced by `check_dto_types_ts_in_sync.py`). During code review, do not flag diffs to `*.gen.ts` files as hand-edits if they match the generator output (including expected changes like new enum values from the Python sources). Only treat changes to `*.gen.ts` as suspicious if they do not match what the generator script would produce (i.e., the sync gate/CI would fail).

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 2171
File: src/synthorg/api/auth/controllers/sessions_mgmt.py:78-79
Timestamp: 2026-05-30T18:10:10.435Z
Learning: When reviewing Python code under src/synthorg/api, do not flag callsites that use `session_store_of(app_state)` as unsafe/bare field dereferences for missing-session-store scenarios. `session_store_of(app_state)` already routes through `require_service(slice.session_store, 'Session Store')`, which raises `ServiceUnavailableError` (HTTP 503) when the session store is not wired (e.g., JWT-only deployments). The existing 503 guard prevents the missing-store from becoming an unsafe access.

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 2423
File: src/synthorg/api/controllers/meta.py:268-273
Timestamp: 2026-06-20T14:08:01.947Z
Learning: In Aureliolo/synthorg controller code, do not flag an O(N) pre-materialization/performance issue when cursor pagination is implemented using the canonical idiom: `collect_all(lambda limit, offset: repo.list_items(...)) + paginate_cursor(...)` (e.g., in `custom_rules.py`, `meta.py`). Treat this as intentional because `paginate_cursor` requires the fully ordered collection to compute truncation/`has_more`, and repository protocol methods explicitly forbid bespoke `count`/extra methods under ADR-0001 (`IdKeyedRepository` compose-only). Only apply this “do not flag” guidance when the pagination is built from `repo.list_items(...)` via `collect_all` and then passed into `paginate_cursor` as part of cursor-pagination logic for low-cardinality datasets.

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 2459
File: src/synthorg/api/controllers/risk_overrides.py:37-41
Timestamp: 2026-06-22T15:30:01.837Z
Learning: When reviewing controller helper code in this project, reading the ASGI `request.scope` user (e.g., `request.scope.get("user")` / `request.scope["user"]`) should NOT be treated as untrusted input that requires `parse_typed()` / `check_boundary_typed()`.

In Aureliolo/synthorg, the project’s auth middleware populates `scope["user"]` with an already-constructed `AuthenticatedUser` Pydantic model, not arbitrary external dict data. The correct boundary check is to validate the type, e.g. `isinstance(actor, AuthenticatedUser)` (and raise `UnauthorizedError` when it fails), rather than adding `parse_typed()` around `scope["user"]`.

Learnt from: Aureliolo
Repo: Aureliolo/synthorg PR: 2459
File: src/synthorg/api/controllers/risk_overrides.py:39-40
Timestamp: 2026-06-22T15:30:20.153Z
Learning: In controller-layer code, do NOT log WARNING/ERROR with context immediately before raising client-facing guard exceptions that are part of normal request handling.

Specifically:
- For actor/auth guard helpers (e.g., `_require_actor`-style helpers) that raise `UnauthorizedError` when no authenticated actor is present, skip the preceding `logger.warning()`/`logger.error()` call and raise directly.
- For controller handlers that raise `NotFoundError` for missing resources (e.g., when a service returns `None`), skip the preceding log and raise directly (4xx “not found” is routine).

Only apply the “log WARNING/ERROR with context before raising” guideline to service-layer failures and state transitions (i.e., unexpected/operational failures), not routine controller authorization/not-found guards. Use the established idiom shown by `src/synthorg/api/controllers/users/org_roles.py::_require_actor` and the pattern in this controller (`risk_overrides.py`).