docs(wp5): public-facing truth refresh

[Aureliolo]

Closes #1920.

Public-facing truth refresh from the 2026-05-15 audit (WP-5).
Every numeric, claim, and status on synthorg.io and the in-repo docs
that was wrong or stale is now in sync with the code.

Numeric drift

• data/runtime_stats.yaml regenerated. Tests 30,536, providers
  curated 20 (featured-only), Mem0 stars 55,792.
• scripts/generate_runtime_stats.py _fetch_providers_curated
  switched from len(list_presets()) to an AST walk of
  _FEATURED_PRESETS so the public count tracks the 20 hand-curated
  entries with brand logos and vetted descriptions. The AST walk also
  avoids a pre-existing circular import in the providers package init
  chain that previously kept the stat stale.
• docs/roadmap/index.md:17 "8+ tool categories" becomes "12+" and
  the inline list now matches the table in docs/design/tools.md.

Claim drift (shipped features previously labelled planned)

• data/competitors.yaml SynthOrg row: budget_tracking and
  security_model to FULL with rewritten notes (Risk-Unit Action
  Budgets and self-healing SSRF are shipped).
• docs/roadmap/future-vision.md and docs/roadmap/index.md:
  Notification sink MVP removed from Planned and promoted into "What
  works today". PostgreSQL bullet narrowed to TimescaleDB hypertable
  support only (PG core shipped v0.6.6).

Marketing-site autonomy claim

• site/src/pages/index.astro (two sites), site/src/pages/compare.astro,
  site/src/components/FeatureShowcase.astro: "five / 5 autonomy tiers"
  becomes "four / 4 autonomy tiers" with the level names listed (full,
  semi, supervised, locked). Design spec and the AutonomyLevel enum
  are now the single source of truth and the marketing site matches.

Docs reference drift

• docs/user_guide.md setup-wizard step list: swap Company and
  Providers so order matches web/src/stores/setup-wizard/navigation.ts.
• New docs/reference/cli-commands.md: operator-facing per-command
  flag inventory with defaults for the 8 flags called out by the audit
  (start --timeout=90s, update --timeout=90s, status --interval=2s,
  logs --tail=100, cleanup --keep=0, backup create --timeout=60s,
  backup restore --timeout=30s, backup list --limit=0). Also
  documents init --encrypt-secrets=true and backup restore --confirm.
• mkdocs.yml: surface the new CLI commands page and the existing
  cli-config-subcommands / cli-env-vars / cli-persistence-backends /
  configuration-precedence reference pages in the Reference section.

404 pages

• web/Caddyfile: redirect legacy /docs/getting-started/,
  /docs/decisions/, /docs/comparison/ paths to their canonical
  locations. Caddy validate passes pre-commit. Production serves the
  docs via Caddy in front of the mkdocs output, so this is the
  authoritative redirect surface.
• pyproject.toml + mkdocs.yml: mkdocs-redirects==1.2.2 added as
  a defence in depth for builds that run the mkdocs plugin lifecycle
  (zensical does not).

Design-spec contradictions

• docs/design/hr-lifecycle.md D9 / D10 / D13-D15 decision blocks:
  add a lead-in clarifying that "Initial strategy: ..." names the
  shipped default (concrete file paths added for QueueReturnStrategy
  and FullSnapshotStrategy). Resolves the "10 protocols documented as
  pluggable but no implementations exist" audit finding -- all 7
  protocols are Protocol + concrete subclass already.
• docs/design/verification-quality.md: new "Order of Operations"
  section with a table contrasting mid-execution AUTH_REQUIRED park
  vs post-completion IN_REVIEW review pipeline, plus the
  verification-stage-before-review-pipeline invariant.

Temporal drift

• docs/guides/agent-management.md (firing + rehire): reword "not yet
  implemented" claims about TaskReassignmentStrategy and
  MemoryArchivalStrategy; the strategies are implemented but not
  wired into the DELETE flow today.
• docs/guides/budget.md report-generation note: drop "planned but not
  yet implemented" framing.
• docs/design/a2a-protocol.md quadratic enforcement modes: describe
  alert_only as shipped and the other three modes as defined-in-config
  but not wired into MessageBus.publish.
• docs/research/multi-agent-failure-audit.md and
  docs/research/s1-multi-agent-decision.md: drop the v0.8+ forward
  references; describe the templates as backlog instead.
• docs/guides/memory.md and docs/design/tools.md: rewrite the
  "planned" REST endpoint and "not yet wired" tool notes to point at
  the GitHub issue tracker.

Config example schema drift

• docs/guides/company-config.md: expand the persistence example with
  every Postgres + SQLite field (defaults, validation constraints, the
  TimescaleDB hypertable block). Add a Cross-provider Fallback tab to
  Provider Examples showing primary degradation pointing at a secondary
  provider. Promote the routing-rule "at least one of role_level or
  task_type" constraint out of a trailing admonition into the
  introductory paragraph.
• docs/guides/workflow-api.md: add a Company-Level Workflow
  Configuration section with the WorkflowConfig schema and a table of
  which sub-configs each workflow_type reads.
• A2AConfig: already in docs/design/security.md and
  docs/design/a2a-protocol.md; no new doc needed.

OpenAPI parameter descriptions

40+ Parameter(description=...) annotations added across 20 Litestar
controllers in src/synthorg/api/controllers/**/*.py. The pre-PR
review surfaced a Litestar shape bug: Annotated[X, Parameter(...)] | None = None silently drops Parameter metadata from the OpenAPI schema;
the canonical shape is Annotated[X | None, Parameter(...)] = None
(union inside Annotated). All 15 affected query params refactored;
descriptions now surface correctly in web/src/api/types/openapi.gen.ts.
Two test status-code assertions updated to accept both 400 and 422
because Litestar's validation pipeline returns 400 for the canonical
shape (both reject the oversized query equivalently).

Audit reported 72 missing descriptions; an AST walk found 30
Parameter() instances without description= plus 71 handler params
without Parameter() wrappers. This PR addresses 40+ of those by
either adding Parameter(description=...) directly or wrapping the
type in Annotated[..., Parameter(...)]. Remaining path parameters
are already documented via the path template syntax ({name:type}).

Test plan

• uv run ruff check src/ tests/: clean
• uv run ruff format src/ tests/: clean
• uv run mypy src/ tests/: clean (3797 files)
• uv run python -m pytest tests/ -m unit -n 8 --no-cov: 28906 passed,
  18 skipped (Windows symlink / POSIX / logfire-extra skips only)
• uv run python scripts/check_doc_numeric_macros.py: clean
• uv run python scripts/inject_runtime_stats.py: idempotent
• uv run python scripts/generate_dto_types_ts.py: in sync
• caddy validate --config web/Caddyfile: valid configuration
• pre-commit + pre-push hooks: all gates pass

Review coverage

Pre-PR review ran 6 agents in parallel: docs-consistency, code-reviewer,
python-reviewer, security-reviewer, api-contract-drift,
issue-resolution-verifier. Five findings surfaced; 4 valid and fixed
in commit b8630ad, 1 false positive (auto-generated comparison.md
header).

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

OpenSSF Scorecard

Package	Version	Score	Details
pip/mkdocs-redirects	1.2.2	Unknown	Unknown

Scanned Files

• uv.lock

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: e354e031-a817-4f43-9757-6580bf0e8f31

📥 Commits

Reviewing files that changed from the base of the PR and between 0a249ec and 042bbf6.

📒 Files selected for processing (2)

• docs/design/a2a-protocol.md
• src/synthorg/api/controllers/ceremony_policy.py

📜 Recent review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (13)

• GitHub Check: Build Backend
• GitHub Check: Build Fine-Tune (cpu, fine-tune-cpu)
• GitHub Check: Build Fine-Tune (gpu, fine-tune-gpu)
• GitHub Check: Build Web Assets (melange)
• GitHub Check: Lighthouse Dashboard
• GitHub Check: Lighthouse Site
• GitHub Check: CodSpeed Python benchmarks
• GitHub Check: CodSpeed Web benchmarks
• GitHub Check: Test (Python 3.14)
• GitHub Check: Dashboard Test
• GitHub Check: Build Preview
• GitHub Check: Analyze (javascript-typescript)
• GitHub Check: Analyze (python)

🧰 Additional context used

📓 Path-based instructions (3)

**/*.md

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.md: Numerics in README and public docs must be sourced from data/runtime_stats.yaml via markers; enforce Doc Numeric Claims
Use D2 for architecture / nested containers diagrams; use mermaid for flowcharts / sequence / pipelines; use Markdown tables for tabular data; D2 theme 200 (Dark Mauve), D2 CLI pinned to v0.7.1 in CI

Files:

• docs/design/a2a-protocol.md

src/synthorg/**/*.py

📄 CodeRabbit inference engine (CLAUDE.md)

src/synthorg/**/*.py: Configuration precedence: DB > env > code default via SettingsService/ConfigResolver (Cat-1) or env > code default (Cat-2, read_only_post_init); Cat-3 bootstrap secrets are pure env at boot site; YAML is ingestion format only; no os.environ.get outside startup; pre-init Cat-2 reads use settings.bootstrap_resolver.resolve_init_value
No hardcoded numeric values; numerics live in settings/definitions/; allowlist 0/1/-1, HTTP codes, hex masks, powers-of-2, and module-level annotated named constants (NAME: int|float|Final|Final[int]|Final[float] = literal); enforced by scripts/check_no_magic_numbers.py
Comments should explain WHY only; no reviewer citations, issue back-refs, or migration framing; enforced by check_no_review_origin_in_code.py and check_no_migration_framing.py
No from __future__ import annotations (Python 3.14 has PEP 649); use PEP 758 except: except A, B: no parens unless binding
Type hints required on public functions; mypy strict mode; use Google-style docstrings; line length 88; functions <50 lines; files <800 lines
Errors: use <Domain><Condition>Error form inheriting from DomainError; never inherit directly from Exception/RuntimeError/etc; enforced by check_domain_error_hierarchy.py
Pydantic v2: use frozen + extra="forbid" on API DTOs (Request/Response/Snapshot/Result/Envelope/Status/Info/Summary suffixes); use @computed_field for derived; use NotBlankStr for identifiers
Use args models at every system boundary; use parse_typed() for every external dict ingestion; enforced by check_boundary_typed.py
Immutability: use model_copy(update=...) or copy.deepcopy(); deepcopy at system boundaries
Async: use asyncio.TaskGroup for fan-out/fan-in; helpers catch Exception and re-raise MemoryError/RecursionError
Clock seam: use clock: Clock | None = None; tests inject FakeClock; lifecycle: services own _lifecycle_lock; timed-out stops mark unrestartable
Untrusted content (SEC-1): use `wrap_u...

Files:

• src/synthorg/api/controllers/ceremony_policy.py

src/**/*.py

⚙️ CodeRabbit configuration file

This project uses Python 3.14+ with PEP 758 except syntax: "except A, B:" (comma-separated, no parentheses) is correct and mandatory -- do NOT flag it as a typo or suggest parenthesized form. The "except builtins.MemoryError, RecursionError: raise" pattern is intentional project convention for system-error propagation. When evaluating the 50-line function limit, count only the function body excluding the signature lines, decorators, and docstring. Functions 1-5 lines over due to docstrings or multi-line signatures should not be flagged. Do not suggest extracting single-use helper functions called exactly once -- this reduces readability without improving maintainability.

Files:

• src/synthorg/api/controllers/ceremony_policy.py

🧠 Learnings (1)

📚 Learning: 2026-05-05T09:04:46.195Z

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+.

Applied to files:

• src/synthorg/api/controllers/ceremony_policy.py

🔇 Additional comments (2)

docs/design/a2a-protocol.md (1)

97-107: LGTM!

src/synthorg/api/controllers/ceremony_policy.py (1)

18-18: LGTM!

Also applies to: 65-68

---

Walkthrough

This PR refreshes public-facing documentation and data (runtime stats, README, competitors), corrects roadmap/site claims and autonomy-tier wording, clarifies multiple design and guide documents, adds a Cross-provider Fallback config example and persistence tuning, expands Litestar Parameter metadata across many API controllers (updating generated OpenAPI TypeScript JSDoc), relaxes two validation tests to accept 400/422, and configures documentation redirect mappings plus Caddy legacy redirects and docs-build dependency.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs(wp5): public-facing truth refresh' accurately describes the PR's core objective: a comprehensive documentation and data synchronization update (WP-5) to align public-facing content with current code and shipped features.
Description check	✅ Passed	The description provides detailed coverage of all changes: numeric updates (tests 30k+, featured providers), claim corrections (autonomy tiers 5→4, notification sink promoted), docs reference fixes, API parameter enhancements, redirects, and design clarifications. It directly relates to the changeset.
Linked Issues check	✅ Passed	All major PR deliverables from issue #1920 are addressed: numeric regeneration (runtime_stats.yaml, provider counts), claim drift corrections (competitors.yaml, roadmap/future-vision.md), autonomy tier fix (5→4), docs reference updates (CLI commands, setup-wizard order, 404 redirects), temporal-drift rewording, config examples expansion, and OpenAPI parameter descriptions. Design-spec clarifications for HR-lifecycle and verification-quality are included.
Out of Scope Changes check	✅ Passed	All changes align directly with issue #1920 objectives: data regeneration, docs synchronization, autonomy tier correction, competitor table update, CLI documentation, redirects, and API schema enhancements. No unrelated scope creep detected.
Docstring Coverage	✅ Passed	Docstring coverage is 93.94% which is sufficient. The required threshold is 40.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codspeed-hq]

Merging this PR will not alter performance

✅ 54 untouched benchmarks

---

_{Comparing docs/wp5-public-facing-truth-refresh (042bbf6) with main (d296214)¹}

Footnotes

1. No successful run was found on main (9317ed1) during the generation of this report, so d296214 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/roadmap/index.md`:
- Line 5: Replace the hardcoded rounded test count in docs/roadmap/index.md with
the exact value sourced from data/runtime_stats.yaml by using the RS marker for
tests: change the current `<!--RS:tests-->30,000+<!--/RS-->` fragment to
`<!--RS:tests-->30,536<!--/RS-->` (i.e., bind the numeric token named "tests" to
the value emitted from data/runtime_stats.yaml) so the page uses the canonical
runtime_stats "tests" value; ensure the marker name "tests" matches the key in
data/runtime_stats.yaml and that the doc generation pipeline recognizes
<!--RS:tests-->...<!--/RS--> markers.

In `@src/synthorg/api/controllers/meta_analytics.py`:
- Around line 117-122: Replace the hardcoded literal default in the Parameter
declaration for min_deployments with the module constant: change default=3 to
default=_DEFAULT_MIN_DEPLOYMENTS_FLOOR in the min_deployments Parameter (the
declaration using Parameter(..., ge=1, le=100, description=...)) so the
parameter uses the existing module-level constant _DEFAULT_MIN_DEPLOYMENTS_FLOOR
per the numeric-literal policy.

In `@src/synthorg/api/controllers/providers.py`:
- Around line 593-599: The preset_hint parameter description currently names
real vendors; update the description string for the Annotated parameter
preset_hint (in providers.py) to remove vendor names and use repository-approved
neutral examples (e.g., "example-provider" or "test-provider", or
"example-large-001") so the description reads something like "Canonical preset
hint (e.g. example-provider)." Ensure the change is made on the Annotated
preset_hint declaration to keep max_length and other Parameter settings
unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: d6b99a06-bafd-4cb5-a693-6a3a2bf8a3e6

📥 Commits

Reviewing files that changed from the base of the PR and between d296214 and b8630ad.

⛔ Files ignored due to path filters (1)

• uv.lock is excluded by !**/*.lock

📒 Files selected for processing (49)

• README.md
• data/competitors.yaml
• data/runtime_stats.yaml
• docs/design/a2a-protocol.md
• docs/design/hr-lifecycle.md
• docs/design/tools.md
• docs/design/verification-quality.md
• docs/guides/agent-management.md
• docs/guides/budget.md
• docs/guides/company-config.md
• docs/guides/memory.md
• docs/guides/workflow-api.md
• docs/reference/cli-commands.md
• docs/research/multi-agent-failure-audit.md
• docs/research/s1-multi-agent-decision.md
• docs/roadmap/future-vision.md
• docs/roadmap/index.md
• docs/user_guide.md
• mkdocs.yml
• pyproject.toml
• scripts/generate_runtime_stats.py
• site/src/components/FeatureShowcase.astro
• site/src/pages/compare.astro
• site/src/pages/index.astro
• src/synthorg/api/controllers/agent_identity_versions.py
• src/synthorg/api/controllers/approvals.py
• src/synthorg/api/controllers/audit.py
• src/synthorg/api/controllers/budget.py
• src/synthorg/api/controllers/budget_config_versions.py
• src/synthorg/api/controllers/ceremony_policy.py
• src/synthorg/api/controllers/company_versions.py
• src/synthorg/api/controllers/coordination_metrics.py
• src/synthorg/api/controllers/escalations.py
• src/synthorg/api/controllers/evaluation_config_versions.py
• src/synthorg/api/controllers/events.py
• src/synthorg/api/controllers/meetings.py
• src/synthorg/api/controllers/messages.py
• src/synthorg/api/controllers/meta_analytics.py
• src/synthorg/api/controllers/ontology.py
• src/synthorg/api/controllers/providers.py
• src/synthorg/api/controllers/requests.py
• src/synthorg/api/controllers/role_versions.py
• src/synthorg/api/controllers/subworkflows.py
• src/synthorg/api/controllers/tasks.py
• src/synthorg/api/controllers/workflow_versions.py
• tests/unit/api/controllers/test_approvals.py
• tests/unit/api/controllers/test_meetings.py
• web/Caddyfile
• web/src/api/types/openapi.gen.ts

📜 Review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (13)

• GitHub Check: Build Backend
• GitHub Check: Build Fine-Tune (gpu, fine-tune-gpu)
• GitHub Check: Build Fine-Tune (cpu, fine-tune-cpu)
• GitHub Check: Build Web Assets (melange)
• GitHub Check: Dashboard Test
• GitHub Check: Test (Python 3.14)
• GitHub Check: CodSpeed Python benchmarks
• GitHub Check: CodSpeed Web benchmarks
• GitHub Check: Lighthouse Site
• GitHub Check: Lighthouse Dashboard
• GitHub Check: Analyze (go)
• GitHub Check: Analyze (javascript-typescript)
• GitHub Check: Analyze (python)

🧰 Additional context used

📓 Path-based instructions (13)

**/*.md

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.md: Numerics in README and public docs must be sourced from data/runtime_stats.yaml via markers; enforce Doc Numeric Claims
Use D2 for architecture / nested containers diagrams; use mermaid for flowcharts / sequence / pipelines; use Markdown tables for tabular data; D2 theme 200 (Dark Mauve), D2 CLI pinned to v0.7.1 in CI

Files:

• docs/design/a2a-protocol.md
• README.md
• docs/research/multi-agent-failure-audit.md
• docs/research/s1-multi-agent-decision.md
• docs/guides/workflow-api.md
• docs/roadmap/future-vision.md
• docs/roadmap/index.md
• docs/user_guide.md
• docs/guides/memory.md
• docs/design/hr-lifecycle.md
• docs/design/tools.md
• docs/guides/budget.md
• docs/guides/agent-management.md
• docs/design/verification-quality.md
• docs/reference/cli-commands.md
• docs/guides/company-config.md

src/synthorg/**/*.py

📄 CodeRabbit inference engine (CLAUDE.md)

src/synthorg/**/*.py: Configuration precedence: DB > env > code default via SettingsService/ConfigResolver (Cat-1) or env > code default (Cat-2, read_only_post_init); Cat-3 bootstrap secrets are pure env at boot site; YAML is ingestion format only; no os.environ.get outside startup; pre-init Cat-2 reads use settings.bootstrap_resolver.resolve_init_value
No hardcoded numeric values; numerics live in settings/definitions/; allowlist 0/1/-1, HTTP codes, hex masks, powers-of-2, and module-level annotated named constants (NAME: int|float|Final|Final[int]|Final[float] = literal); enforced by scripts/check_no_magic_numbers.py
Comments should explain WHY only; no reviewer citations, issue back-refs, or migration framing; enforced by check_no_review_origin_in_code.py and check_no_migration_framing.py
No from __future__ import annotations (Python 3.14 has PEP 649); use PEP 758 except: except A, B: no parens unless binding
Type hints required on public functions; mypy strict mode; use Google-style docstrings; line length 88; functions <50 lines; files <800 lines
Errors: use <Domain><Condition>Error form inheriting from DomainError; never inherit directly from Exception/RuntimeError/etc; enforced by check_domain_error_hierarchy.py
Pydantic v2: use frozen + extra="forbid" on API DTOs (Request/Response/Snapshot/Result/Envelope/Status/Info/Summary suffixes); use @computed_field for derived; use NotBlankStr for identifiers
Use args models at every system boundary; use parse_typed() for every external dict ingestion; enforced by check_boundary_typed.py
Immutability: use model_copy(update=...) or copy.deepcopy(); deepcopy at system boundaries
Async: use asyncio.TaskGroup for fan-out/fan-in; helpers catch Exception and re-raise MemoryError/RecursionError
Clock seam: use clock: Clock | None = None; tests inject FakeClock; lifecycle: services own _lifecycle_lock; timed-out stops mark unrestartable
Untrusted content (SEC-1): use `wrap_u...

Files:

• src/synthorg/api/controllers/messages.py
• src/synthorg/api/controllers/budget_config_versions.py
• src/synthorg/api/controllers/meetings.py
• src/synthorg/api/controllers/company_versions.py
• src/synthorg/api/controllers/events.py
• src/synthorg/api/controllers/tasks.py
• src/synthorg/api/controllers/approvals.py
• src/synthorg/api/controllers/subworkflows.py
• src/synthorg/api/controllers/coordination_metrics.py
• src/synthorg/api/controllers/role_versions.py
• src/synthorg/api/controllers/escalations.py
• src/synthorg/api/controllers/ceremony_policy.py
• src/synthorg/api/controllers/budget.py
• src/synthorg/api/controllers/meta_analytics.py
• src/synthorg/api/controllers/agent_identity_versions.py
• src/synthorg/api/controllers/requests.py
• src/synthorg/api/controllers/workflow_versions.py
• src/synthorg/api/controllers/evaluation_config_versions.py
• src/synthorg/api/controllers/audit.py
• src/synthorg/api/controllers/providers.py
• src/synthorg/api/controllers/ontology.py

src/**/*.py

⚙️ CodeRabbit configuration file

This project uses Python 3.14+ with PEP 758 except syntax: "except A, B:" (comma-separated, no parentheses) is correct and mandatory -- do NOT flag it as a typo or suggest parenthesized form. The "except builtins.MemoryError, RecursionError: raise" pattern is intentional project convention for system-error propagation. When evaluating the 50-line function limit, count only the function body excluding the signature lines, decorators, and docstring. Functions 1-5 lines over due to docstrings or multi-line signatures should not be flagged. Do not suggest extracting single-use helper functions called exactly once -- this reduces readability without improving maintainability.

Files:

• src/synthorg/api/controllers/messages.py
• src/synthorg/api/controllers/budget_config_versions.py
• src/synthorg/api/controllers/meetings.py
• src/synthorg/api/controllers/company_versions.py
• src/synthorg/api/controllers/events.py
• src/synthorg/api/controllers/tasks.py
• src/synthorg/api/controllers/approvals.py
• src/synthorg/api/controllers/subworkflows.py
• src/synthorg/api/controllers/coordination_metrics.py
• src/synthorg/api/controllers/role_versions.py
• src/synthorg/api/controllers/escalations.py
• src/synthorg/api/controllers/ceremony_policy.py
• src/synthorg/api/controllers/budget.py
• src/synthorg/api/controllers/meta_analytics.py
• src/synthorg/api/controllers/agent_identity_versions.py
• src/synthorg/api/controllers/requests.py
• src/synthorg/api/controllers/workflow_versions.py
• src/synthorg/api/controllers/evaluation_config_versions.py
• src/synthorg/api/controllers/audit.py
• src/synthorg/api/controllers/providers.py
• src/synthorg/api/controllers/ontology.py

tests/**/*.py

📄 CodeRabbit inference engine (CLAUDE.md)

tests/**/*.py: Testing: use markers @pytest.mark.{unit,integration,e2e,slow}; async tests use auto; timeout 30s global; coverage 80% min
Windows: unit tests use WindowsSelectorEventLoopPolicy (3.14 IOCP teardown race); subprocess tests override back
Test doubles: use ladder from conventions.md; use FakeClock for Clock seam, mock_of[T](**overrides) for typed-boundary substitutions, SimpleNamespace for attribute-bags; bare MagicMock at typed boundary is blocked by check_mock_spec.py (zero-tolerance, no baseline)
Import FakeClock and mock_of from tests._shared; inject via clock= and helper's spec subscript
Flaky tests: NEVER skip/xfail; fix fundamentally; use asyncio.Event().wait() not sleep(large)

Files:

• tests/unit/api/controllers/test_meetings.py
• tests/unit/api/controllers/test_approvals.py

---

⚙️ CodeRabbit configuration file

Test files do not require Google-style docstrings on classes or functions -- ruff D rules are only enforced on src/. A bare @settings() decorator with no arguments on Hypothesis property tests is a no-op and should not be suggested -- the HYPOTHESIS_PROFILE env var controls example counts via registered profiles, which @given() honors automatically.

Files:

• tests/unit/api/controllers/test_meetings.py
• tests/unit/api/controllers/test_approvals.py

tests/**/*test*.py

📄 CodeRabbit inference engine (CLAUDE.md)

Hypothesis: use 10 deterministic CI examples; failures are real bugs (fix + add @example(...)) for property-based testing

Files:

• tests/unit/api/controllers/test_meetings.py
• tests/unit/api/controllers/test_approvals.py

pyproject.toml

📄 CodeRabbit inference engine (CLAUDE.md)

Testing: xdist -n 8 --dist=loadfile auto-applied via pyproject addopts (loadfile prevents 3.14+ Windows ProactorEventLoop leak)

Files:

• pyproject.toml

src/synthorg/**/{app,main,startup}*.py

📄 CodeRabbit inference engine (CLAUDE.md)

src/synthorg/**/{app,main,startup}*.py: API startup lifecycle: construction phase (create_app body) wires synchronous services; on_startup phase (_build_lifecycle.on_startup) wires services needing connected persistence backend
Construction-phase ordering invariants: agent_registry must be built BEFORE auto_wire_meetings; tunnel_provider is wired unconditionally (not gated by integrations.enabled)
On-startup ordering invariants: SettingsService auto-wire must precede WorkflowExecutionObserver registration; OntologyService wires after persistence.connect() via _wire_ontology_service

Files:

• src/synthorg/api/controllers/approvals.py

src/synthorg/**/provider*.py

📄 CodeRabbit inference engine (CLAUDE.md)

Resilience: provider calls go through BaseCompletionProvider for retry + rate limit; never implement retry in driver subclasses; retryable: RateLimitError, Provider{Timeout,Connection,Internal}Error

Files:

• src/synthorg/api/controllers/providers.py

web/src/**/*.{tsx,ts}

📄 CodeRabbit inference engine (CLAUDE.md)

Reuse web/src/components/ui/ design tokens only in React web dashboard; see web/CLAUDE.md for Web Dashboard Design System

Files:

• web/src/api/types/openapi.gen.ts

web/src/**/*.{ts,tsx}

📄 CodeRabbit inference engine (web/CLAUDE.md)

web/src/**/*.{ts,tsx}: Always use createLogger from @/lib/logger; never use bare console.warn/console.error/console.debug in application code
Always use variable name log for logger instances (e.g., const log = createLogger('module-name'))
Pass dynamic/untrusted values as separate args to logger (not interpolated into the message string) so they go through sanitizeArg
Wrap attacker-controlled fields inside structured objects in sanitizeForLog() before embedding in logs
Callers MUST NOT wrap store mutation calls in try/catch; the store owns the error UX
Display counts must come from data.length; the wire envelope no longer carries total
Import ErrorCode and ErrorCategory from @/api/types/errors (re-exported from web/src/api/types/error-codes.gen.ts); discriminate on ErrorCode.<NAME>, never on raw integer literals
Generated DTO types re-export components['schemas']['X'] with no hand-written tightening because the generator handles response optionality
Import DTOs via the barrel (import type { AgentConfig } from '@/api/types') or directly from the generated module (import type { AgentConfig } from '@/api/types/dtos.gen')
ALWAYS reuse existing components from web/src/components/ui/ before creating new ones
A PostToolUse hook (scripts/check_web_design_system.py) flags hardcoded hex/rgba/fonts/Motion durations/locale literals/bare .toLocale*String() calls/missing Storybook stories/duplicate component patterns/complex .map() blocks; fix every violation before proceeding
Forbid passing async functions where the callsite ignores the returned promise via @typescript-eslint/no-misused-promises (with checksVoidReturn: { attributes: false }); React 19 async event handlers stay allowed

Files:

• web/src/api/types/openapi.gen.ts

web/src/{stores,api}/**/*.{ts,tsx}

📄 CodeRabbit inference engine (web/CLAUDE.md)

Use cursor-based paging via PaginationMeta for list endpoints; keep nextCursor + hasMore in state (not offset arithmetic) and early-return when !hasMore || !nextCursor

Files:

• web/src/api/types/openapi.gen.ts

web/src/api/**/*.{ts,tsx}

📄 CodeRabbit inference engine (web/CLAUDE.md)

getLiveness() is always 200 while the process is alive; getReadiness() is 200 healthy / 503 unavailable (binary 'ok' | 'unavailable' outcome, no tri-state). Any new caller must handle the 503 path explicitly.

Files:

• web/src/api/types/openapi.gen.ts

web/src/api/types/**/*.gen.ts

📄 CodeRabbit inference engine (web/CLAUDE.md)

NEVER hand-edit a *.gen.ts file; regenerate with uv run python scripts/generate_dto_types_ts.py

Files:

• web/src/api/types/openapi.gen.ts

🧠 Learnings (1)

📚 Learning: 2026-05-05T09:04:46.195Z

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+.

Applied to files:

• src/synthorg/api/controllers/messages.py
• tests/unit/api/controllers/test_meetings.py
• src/synthorg/api/controllers/budget_config_versions.py
• src/synthorg/api/controllers/meetings.py
• src/synthorg/api/controllers/company_versions.py
• src/synthorg/api/controllers/events.py
• src/synthorg/api/controllers/tasks.py
• src/synthorg/api/controllers/approvals.py
• src/synthorg/api/controllers/subworkflows.py
• src/synthorg/api/controllers/coordination_metrics.py
• src/synthorg/api/controllers/role_versions.py
• src/synthorg/api/controllers/escalations.py
• src/synthorg/api/controllers/ceremony_policy.py
• src/synthorg/api/controllers/budget.py
• src/synthorg/api/controllers/meta_analytics.py
• src/synthorg/api/controllers/agent_identity_versions.py
• src/synthorg/api/controllers/requests.py
• src/synthorg/api/controllers/workflow_versions.py
• src/synthorg/api/controllers/evaluation_config_versions.py
• tests/unit/api/controllers/test_approvals.py
• src/synthorg/api/controllers/audit.py
• scripts/generate_runtime_stats.py
• src/synthorg/api/controllers/providers.py
• src/synthorg/api/controllers/ontology.py

🪛 LanguageTool

docs/reference/cli-commands.md

[locale-violation] ~84-~84: In American English, ‘afterward’ is the preferred variant. ‘Afterwards’ is more commonly used in British English and other dialects.
Context: ...| Restore without restarting containers afterwards | | backup restore | --timeout | `3...

(AFTERWARDS_US)

🔇 Additional comments (49)

mkdocs.yml (1)

34-41: LGTM!

Also applies to: 190-194

web/Caddyfile (1)

142-151: LGTM!

pyproject.toml (1)

94-94: LGTM!

README.md (1)

22-22: LGTM!

data/competitors.yaml (1)

116-117: LGTM!

data/runtime_stats.yaml (1)

1-32: LGTM!

scripts/generate_runtime_stats.py (1)

205-251: LGTM!

docs/design/a2a-protocol.md (1)

106-106: LGTM!

docs/design/hr-lifecycle.md (2)

296-315: LGTM!

---

498-502: LGTM!

docs/design/tools.md (1)

292-296: LGTM!

docs/design/verification-quality.md (1)

137-166: LGTM!

docs/guides/agent-management.md (1)

96-100: LGTM!

docs/guides/budget.md (1)

278-278: LGTM!

docs/guides/company-config.md (1)

191-225: LGTM!

Also applies to: 245-245, 335-355

docs/guides/memory.md (1)

371-374: LGTM!

docs/guides/workflow-api.md (1)

218-265: LGTM!

docs/roadmap/index.md (1)

17-17: LGTM!

Also applies to: 26-26, 40-40

docs/user_guide.md (1)

78-79: LGTM!

docs/roadmap/future-vision.md (1)

9-9: LGTM!

site/src/components/FeatureShowcase.astro (1)

19-19: LGTM!

site/src/pages/compare.astro (1)

103-106: LGTM!

site/src/pages/index.astro (1)

156-156: LGTM!

Also applies to: 159-159

docs/research/multi-agent-failure-audit.md (1)

423-423: LGTM!

docs/research/s1-multi-agent-decision.md (1)

62-62: LGTM!

docs/reference/cli-commands.md (1)

1-117: LGTM!

src/synthorg/api/controllers/agent_identity_versions.py (1)

181-187: LGTM!

src/synthorg/api/controllers/approvals.py (1)

517-531: LGTM!

src/synthorg/api/controllers/audit.py (1)

97-152: LGTM!

src/synthorg/api/controllers/budget.py (1)

300-313: LGTM!

src/synthorg/api/controllers/budget_config_versions.py (1)

84-90: LGTM!

src/synthorg/api/controllers/ceremony_policy.py (1)

64-67: LGTM!

src/synthorg/api/controllers/company_versions.py (1)

84-90: LGTM!

src/synthorg/api/controllers/coordination_metrics.py (1)

92-117: LGTM!

src/synthorg/api/controllers/escalations.py (1)

12-16: LGTM!

Also applies to: 137-142

src/synthorg/api/controllers/evaluation_config_versions.py (1)

84-90: LGTM!

src/synthorg/api/controllers/events.py (1)

549-550: LGTM!

Also applies to: 627-628

src/synthorg/api/controllers/meetings.py (1)

246-256: LGTM!

src/synthorg/api/controllers/messages.py (1)

3-7: LGTM!

Also applies to: 39-42

src/synthorg/api/controllers/ontology.py (1)

8-12: LGTM!

Also applies to: 135-138, 417-420

src/synthorg/api/controllers/providers.py (1)

880-887: LGTM!

Also applies to: 955-962

src/synthorg/api/controllers/requests.py (1)

3-3: LGTM!

Also applies to: 7-7, 89-92

src/synthorg/api/controllers/role_versions.py (1)

83-89: LGTM!

src/synthorg/api/controllers/subworkflows.py (1)

258-262: LGTM!

Also applies to: 287-291, 362-366

src/synthorg/api/controllers/tasks.py (1)

74-91: LGTM!

src/synthorg/api/controllers/workflow_versions.py (1)

99-105: LGTM!

web/src/api/types/openapi.gen.ts (1)

13141-13142: LGTM!

Also applies to: 13723-13732, 14378-14379, 14405-14412, 14511-14512, 14859-14860, 15240-15251, 15760-15761, 15822-15823, 16190-16191, 16257-16260, 16377-16378, 16561-16562, 17338-17339, 17527-17528, 18101-18102, 18235-18236, 18265-18266, 18911-18912, 19120-19139, 19996-19997, 20027-20028, 20064-20065, 20119-20128, 21201-21202

tests/unit/api/controllers/test_approvals.py (1)

705-705: LGTM!

tests/unit/api/controllers/test_meetings.py (1)

454-454: LGTM!

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Use the exact runtime-stats test count, not a rounded placeholder

Line 5 currently renders 30,000+, but this truth-refresh objective targets an exact refreshed count (30,536). Please bind this line to the exact value emitted from data/runtime_stats.yaml so public claims stay fully synchronized.

Suggested adjustment

-SynthOrg is in **active development**. The core subsystems are built, tested (<!--RS:tests-->30,000+<!--/RS--> tests in the latest run, 80%+ coverage), and integrated through a REST + WebSocket API, React 19 dashboard, and Go CLI. See the [releases page](https://github.com/Aureliolo/synthorg/releases) for the latest tagged build.
+SynthOrg is in **active development**. The core subsystems are built, tested (<!--RS:tests-->30,536<!--/RS--> tests in the latest run, 80%+ coverage), and integrated through a REST + WebSocket API, React 19 dashboard, and Go CLI. See the [releases page](https://github.com/Aureliolo/synthorg/releases) for the latest tagged build.

As per coding guidelines, "Numerics in README and public docs must be sourced from data/runtime_stats.yaml via markers; enforce Doc Numeric Claims".

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	SynthOrg is in **active development**. The core subsystems are built, tested (<!--RS:tests-->30,000+<!--/RS--> tests in the latest run, 80%+ coverage), and integrated through a REST + WebSocket API, React 19 dashboard, and Go CLI. See the [releases page](https://github.com/Aureliolo/synthorg/releases) for the latest tagged build.
	SynthOrg is in **active development**. The core subsystems are built, tested (<!--RS:tests-->30,536<!--/RS--> tests in the latest run, 80%+ coverage), and integrated through a REST + WebSocket API, React 19 dashboard, and Go CLI. See the [releases page](https://github.com/Aureliolo/synthorg/releases) for the latest tagged build.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/roadmap/index.md` at line 5, Replace the hardcoded rounded test count in
docs/roadmap/index.md with the exact value sourced from data/runtime_stats.yaml
by using the RS marker for tests: change the current
`<!--RS:tests-->30,000+<!--/RS-->` fragment to `<!--RS:tests-->30,536<!--/RS-->`
(i.e., bind the numeric token named "tests" to the value emitted from
data/runtime_stats.yaml) so the page uses the canonical runtime_stats "tests"
value; ensure the marker name "tests" matches the key in data/runtime_stats.yaml
and that the doc generation pipeline recognizes <!--RS:tests-->...<!--/RS-->
markers.

[gemini-code-assist]

Code Review

This pull request involves extensive documentation updates, including new CLI command references and expanded guides for workflows and security, alongside a refactoring of API controllers to improve OpenAPI metadata using Annotated type hints. Key technical changes include refactoring the runtime stats generator to use AST parsing, which prevents circular dependency issues. Review feedback correctly identifies an opportunity to improve consistency in the meta-analytics controller by refactoring the min_deployments parameter to use the Annotated pattern, ensuring it aligns with the rest of the codebase and supports better static analysis.

[gemini-code-assist]

For consistency with the other controllers refactored in this pull request and to adhere to the "canonical shape" mentioned in the PR description, this parameter should be refactored to use Annotated. This also avoids potential static analysis issues where the default value is an object (Parameter) instead of the declared type (int).

Suggested change

	min_deployments: int = Parameter(
	default=3,
	ge=1,
	le=100,
	description="Minimum deployment count for a pattern to be returned.",
	),
	min_deployments: Annotated[
	int,
	Parameter(
	ge=1,
	le=100,
	description="Minimum deployment count for a pattern to be returned.",
	),
	] = 3,

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.21%. Comparing base (d296214) to head (042bbf6).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1924      +/-   ##
==========================================
- Coverage   85.22%   85.21%   -0.01%     
==========================================
  Files        1834     1834              
  Lines      107191   107196       +5     
  Branches     9245     9245              
==========================================
- Hits        91349    91348       -1     
- Misses      13609    13614       +5     
- Partials     2233     2234       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/design/a2a-protocol.md`:
- Line 106: Update the contradictory status language around quadratic
enforcement so both the prose and the status table agree: change the sentence
that currently states "`alert_only` is the shipped enforcement strategy" and/or
the Status table titled "Quadratic communication enforcement strategies" so they
consistently indicate that alert_only is shipped and the other modes
(`soft_throttle`, `hard_block`, `disabled`) are planned; ensure any mention of
`MessageBus.publish` wiring reflects that per-mode behavior is not yet
implemented.

In `@src/synthorg/api/controllers/ceremony_policy.py`:
- Line 65: Replace the inline literal 128 used in the max_length parameter with
a named, annotated constant: either import the appropriate numeric from
settings.definitions (preferred) or add a module-level constant (e.g.,
CEREMONY_NAME_MAX_LENGTH: int = 128) at the top of ceremony_policy.py and use
that constant in the max_length=... argument where the current literal appears;
ensure the constant is typed and used everywhere this numeric would be reused
instead of hardcoding 128.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 590ee71e-9ecd-4cbd-85e0-7aa249ad43cf

📥 Commits

Reviewing files that changed from the base of the PR and between b8630ad and 0a249ec.

⛔ Files ignored due to path filters (1)

• uv.lock is excluded by !**/*.lock

📒 Files selected for processing (49)

• README.md
• data/competitors.yaml
• data/runtime_stats.yaml
• docs/design/a2a-protocol.md
• docs/design/hr-lifecycle.md
• docs/design/tools.md
• docs/design/verification-quality.md
• docs/guides/agent-management.md
• docs/guides/budget.md
• docs/guides/company-config.md
• docs/guides/memory.md
• docs/guides/workflow-api.md
• docs/reference/cli-commands.md
• docs/research/multi-agent-failure-audit.md
• docs/research/s1-multi-agent-decision.md
• docs/roadmap/future-vision.md
• docs/roadmap/index.md
• docs/user_guide.md
• mkdocs.yml
• pyproject.toml
• scripts/generate_runtime_stats.py
• site/src/components/FeatureShowcase.astro
• site/src/pages/compare.astro
• site/src/pages/index.astro
• src/synthorg/api/controllers/agent_identity_versions.py
• src/synthorg/api/controllers/approvals.py
• src/synthorg/api/controllers/audit.py
• src/synthorg/api/controllers/budget.py
• src/synthorg/api/controllers/budget_config_versions.py
• src/synthorg/api/controllers/ceremony_policy.py
• src/synthorg/api/controllers/company_versions.py
• src/synthorg/api/controllers/coordination_metrics.py
• src/synthorg/api/controllers/escalations.py
• src/synthorg/api/controllers/evaluation_config_versions.py
• src/synthorg/api/controllers/events.py
• src/synthorg/api/controllers/meetings.py
• src/synthorg/api/controllers/messages.py
• src/synthorg/api/controllers/meta_analytics.py
• src/synthorg/api/controllers/ontology.py
• src/synthorg/api/controllers/providers.py
• src/synthorg/api/controllers/requests.py
• src/synthorg/api/controllers/role_versions.py
• src/synthorg/api/controllers/subworkflows.py
• src/synthorg/api/controllers/tasks.py
• src/synthorg/api/controllers/workflow_versions.py
• tests/unit/api/controllers/test_approvals.py
• tests/unit/api/controllers/test_meetings.py
• web/Caddyfile
• web/src/api/types/openapi.gen.ts

📜 Review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (13)

• GitHub Check: Deploy Preview
• GitHub Check: Build Fine-Tune (gpu, fine-tune-gpu)
• GitHub Check: Build Fine-Tune (cpu, fine-tune-cpu)
• GitHub Check: Build Backend
• GitHub Check: Lighthouse Site
• GitHub Check: Lighthouse Dashboard
• GitHub Check: CodSpeed Python benchmarks
• GitHub Check: CodSpeed Web benchmarks
• GitHub Check: Build Web Assets (melange)
• GitHub Check: Dashboard Test
• GitHub Check: Test (Python 3.14)
• GitHub Check: Analyze (python)
• GitHub Check: Analyze (javascript-typescript)

🧰 Additional context used

📓 Path-based instructions (13)

**/*.md

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.md: Numerics in README and public docs must be sourced from data/runtime_stats.yaml via markers; enforce Doc Numeric Claims
Use D2 for architecture / nested containers diagrams; use mermaid for flowcharts / sequence / pipelines; use Markdown tables for tabular data; D2 theme 200 (Dark Mauve), D2 CLI pinned to v0.7.1 in CI

Files:

• README.md
• docs/guides/budget.md
• docs/roadmap/future-vision.md
• docs/guides/memory.md
• docs/design/a2a-protocol.md
• docs/guides/workflow-api.md
• docs/research/s1-multi-agent-decision.md
• docs/design/verification-quality.md
• docs/design/hr-lifecycle.md
• docs/research/multi-agent-failure-audit.md
• docs/reference/cli-commands.md
• docs/roadmap/index.md
• docs/user_guide.md
• docs/guides/agent-management.md
• docs/guides/company-config.md
• docs/design/tools.md

src/synthorg/**/*.py

📄 CodeRabbit inference engine (CLAUDE.md)

src/synthorg/**/*.py: Configuration precedence: DB > env > code default via SettingsService/ConfigResolver (Cat-1) or env > code default (Cat-2, read_only_post_init); Cat-3 bootstrap secrets are pure env at boot site; YAML is ingestion format only; no os.environ.get outside startup; pre-init Cat-2 reads use settings.bootstrap_resolver.resolve_init_value
No hardcoded numeric values; numerics live in settings/definitions/; allowlist 0/1/-1, HTTP codes, hex masks, powers-of-2, and module-level annotated named constants (NAME: int|float|Final|Final[int]|Final[float] = literal); enforced by scripts/check_no_magic_numbers.py
Comments should explain WHY only; no reviewer citations, issue back-refs, or migration framing; enforced by check_no_review_origin_in_code.py and check_no_migration_framing.py
No from __future__ import annotations (Python 3.14 has PEP 649); use PEP 758 except: except A, B: no parens unless binding
Type hints required on public functions; mypy strict mode; use Google-style docstrings; line length 88; functions <50 lines; files <800 lines
Errors: use <Domain><Condition>Error form inheriting from DomainError; never inherit directly from Exception/RuntimeError/etc; enforced by check_domain_error_hierarchy.py
Pydantic v2: use frozen + extra="forbid" on API DTOs (Request/Response/Snapshot/Result/Envelope/Status/Info/Summary suffixes); use @computed_field for derived; use NotBlankStr for identifiers
Use args models at every system boundary; use parse_typed() for every external dict ingestion; enforced by check_boundary_typed.py
Immutability: use model_copy(update=...) or copy.deepcopy(); deepcopy at system boundaries
Async: use asyncio.TaskGroup for fan-out/fan-in; helpers catch Exception and re-raise MemoryError/RecursionError
Clock seam: use clock: Clock | None = None; tests inject FakeClock; lifecycle: services own _lifecycle_lock; timed-out stops mark unrestartable
Untrusted content (SEC-1): use `wrap_u...

Files:

• src/synthorg/api/controllers/workflow_versions.py
• src/synthorg/api/controllers/messages.py
• src/synthorg/api/controllers/budget_config_versions.py
• src/synthorg/api/controllers/escalations.py
• src/synthorg/api/controllers/events.py
• src/synthorg/api/controllers/company_versions.py
• src/synthorg/api/controllers/subworkflows.py
• src/synthorg/api/controllers/meetings.py
• src/synthorg/api/controllers/meta_analytics.py
• src/synthorg/api/controllers/evaluation_config_versions.py
• src/synthorg/api/controllers/role_versions.py
• src/synthorg/api/controllers/requests.py
• src/synthorg/api/controllers/coordination_metrics.py
• src/synthorg/api/controllers/ontology.py
• src/synthorg/api/controllers/budget.py
• src/synthorg/api/controllers/ceremony_policy.py
• src/synthorg/api/controllers/audit.py
• src/synthorg/api/controllers/agent_identity_versions.py
• src/synthorg/api/controllers/providers.py
• src/synthorg/api/controllers/tasks.py
• src/synthorg/api/controllers/approvals.py

src/**/*.py

⚙️ CodeRabbit configuration file

This project uses Python 3.14+ with PEP 758 except syntax: "except A, B:" (comma-separated, no parentheses) is correct and mandatory -- do NOT flag it as a typo or suggest parenthesized form. The "except builtins.MemoryError, RecursionError: raise" pattern is intentional project convention for system-error propagation. When evaluating the 50-line function limit, count only the function body excluding the signature lines, decorators, and docstring. Functions 1-5 lines over due to docstrings or multi-line signatures should not be flagged. Do not suggest extracting single-use helper functions called exactly once -- this reduces readability without improving maintainability.

Files:

• src/synthorg/api/controllers/workflow_versions.py
• src/synthorg/api/controllers/messages.py
• src/synthorg/api/controllers/budget_config_versions.py
• src/synthorg/api/controllers/escalations.py
• src/synthorg/api/controllers/events.py
• src/synthorg/api/controllers/company_versions.py
• src/synthorg/api/controllers/subworkflows.py
• src/synthorg/api/controllers/meetings.py
• src/synthorg/api/controllers/meta_analytics.py
• src/synthorg/api/controllers/evaluation_config_versions.py
• src/synthorg/api/controllers/role_versions.py
• src/synthorg/api/controllers/requests.py
• src/synthorg/api/controllers/coordination_metrics.py
• src/synthorg/api/controllers/ontology.py
• src/synthorg/api/controllers/budget.py
• src/synthorg/api/controllers/ceremony_policy.py
• src/synthorg/api/controllers/audit.py
• src/synthorg/api/controllers/agent_identity_versions.py
• src/synthorg/api/controllers/providers.py
• src/synthorg/api/controllers/tasks.py
• src/synthorg/api/controllers/approvals.py

tests/**/*.py

📄 CodeRabbit inference engine (CLAUDE.md)

tests/**/*.py: Testing: use markers @pytest.mark.{unit,integration,e2e,slow}; async tests use auto; timeout 30s global; coverage 80% min
Windows: unit tests use WindowsSelectorEventLoopPolicy (3.14 IOCP teardown race); subprocess tests override back
Test doubles: use ladder from conventions.md; use FakeClock for Clock seam, mock_of[T](**overrides) for typed-boundary substitutions, SimpleNamespace for attribute-bags; bare MagicMock at typed boundary is blocked by check_mock_spec.py (zero-tolerance, no baseline)
Import FakeClock and mock_of from tests._shared; inject via clock= and helper's spec subscript
Flaky tests: NEVER skip/xfail; fix fundamentally; use asyncio.Event().wait() not sleep(large)

Files:

• tests/unit/api/controllers/test_meetings.py
• tests/unit/api/controllers/test_approvals.py

---

⚙️ CodeRabbit configuration file

Test files do not require Google-style docstrings on classes or functions -- ruff D rules are only enforced on src/. A bare @settings() decorator with no arguments on Hypothesis property tests is a no-op and should not be suggested -- the HYPOTHESIS_PROFILE env var controls example counts via registered profiles, which @given() honors automatically.

Files:

• tests/unit/api/controllers/test_meetings.py
• tests/unit/api/controllers/test_approvals.py

tests/**/*test*.py

📄 CodeRabbit inference engine (CLAUDE.md)

Hypothesis: use 10 deterministic CI examples; failures are real bugs (fix + add @example(...)) for property-based testing

Files:

• tests/unit/api/controllers/test_meetings.py
• tests/unit/api/controllers/test_approvals.py

pyproject.toml

📄 CodeRabbit inference engine (CLAUDE.md)

Testing: xdist -n 8 --dist=loadfile auto-applied via pyproject addopts (loadfile prevents 3.14+ Windows ProactorEventLoop leak)

Files:

• pyproject.toml

src/synthorg/**/provider*.py

📄 CodeRabbit inference engine (CLAUDE.md)

Resilience: provider calls go through BaseCompletionProvider for retry + rate limit; never implement retry in driver subclasses; retryable: RateLimitError, Provider{Timeout,Connection,Internal}Error

Files:

• src/synthorg/api/controllers/providers.py

src/synthorg/**/{app,main,startup}*.py

📄 CodeRabbit inference engine (CLAUDE.md)

src/synthorg/**/{app,main,startup}*.py: API startup lifecycle: construction phase (create_app body) wires synchronous services; on_startup phase (_build_lifecycle.on_startup) wires services needing connected persistence backend
Construction-phase ordering invariants: agent_registry must be built BEFORE auto_wire_meetings; tunnel_provider is wired unconditionally (not gated by integrations.enabled)
On-startup ordering invariants: SettingsService auto-wire must precede WorkflowExecutionObserver registration; OntologyService wires after persistence.connect() via _wire_ontology_service

Files:

• src/synthorg/api/controllers/approvals.py

web/src/**/*.{tsx,ts}

📄 CodeRabbit inference engine (CLAUDE.md)

Reuse web/src/components/ui/ design tokens only in React web dashboard; see web/CLAUDE.md for Web Dashboard Design System

Files:

• web/src/api/types/openapi.gen.ts

web/src/**/*.{ts,tsx}

📄 CodeRabbit inference engine (web/CLAUDE.md)

web/src/**/*.{ts,tsx}: Always use createLogger from @/lib/logger; never use bare console.warn/console.error/console.debug in application code
Always use variable name log for logger instances (e.g., const log = createLogger('module-name'))
Pass dynamic/untrusted values as separate args to logger (not interpolated into the message string) so they go through sanitizeArg
Wrap attacker-controlled fields inside structured objects in sanitizeForLog() before embedding in logs
Callers MUST NOT wrap store mutation calls in try/catch; the store owns the error UX
Display counts must come from data.length; the wire envelope no longer carries total
Import ErrorCode and ErrorCategory from @/api/types/errors (re-exported from web/src/api/types/error-codes.gen.ts); discriminate on ErrorCode.<NAME>, never on raw integer literals
Generated DTO types re-export components['schemas']['X'] with no hand-written tightening because the generator handles response optionality
Import DTOs via the barrel (import type { AgentConfig } from '@/api/types') or directly from the generated module (import type { AgentConfig } from '@/api/types/dtos.gen')
ALWAYS reuse existing components from web/src/components/ui/ before creating new ones
A PostToolUse hook (scripts/check_web_design_system.py) flags hardcoded hex/rgba/fonts/Motion durations/locale literals/bare .toLocale*String() calls/missing Storybook stories/duplicate component patterns/complex .map() blocks; fix every violation before proceeding
Forbid passing async functions where the callsite ignores the returned promise via @typescript-eslint/no-misused-promises (with checksVoidReturn: { attributes: false }); React 19 async event handlers stay allowed

Files:

• web/src/api/types/openapi.gen.ts

web/src/{stores,api}/**/*.{ts,tsx}

📄 CodeRabbit inference engine (web/CLAUDE.md)

Use cursor-based paging via PaginationMeta for list endpoints; keep nextCursor + hasMore in state (not offset arithmetic) and early-return when !hasMore || !nextCursor

Files:

• web/src/api/types/openapi.gen.ts

web/src/api/**/*.{ts,tsx}

📄 CodeRabbit inference engine (web/CLAUDE.md)

getLiveness() is always 200 while the process is alive; getReadiness() is 200 healthy / 503 unavailable (binary 'ok' | 'unavailable' outcome, no tri-state). Any new caller must handle the 503 path explicitly.

Files:

• web/src/api/types/openapi.gen.ts

web/src/api/types/**/*.gen.ts

📄 CodeRabbit inference engine (web/CLAUDE.md)

NEVER hand-edit a *.gen.ts file; regenerate with uv run python scripts/generate_dto_types_ts.py

Files:

• web/src/api/types/openapi.gen.ts

🧠 Learnings (1)

📚 Learning: 2026-05-05T09:04:46.195Z

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+.

Applied to files:

• src/synthorg/api/controllers/workflow_versions.py
• src/synthorg/api/controllers/messages.py
• src/synthorg/api/controllers/budget_config_versions.py
• src/synthorg/api/controllers/escalations.py
• tests/unit/api/controllers/test_meetings.py
• src/synthorg/api/controllers/events.py
• src/synthorg/api/controllers/company_versions.py
• src/synthorg/api/controllers/subworkflows.py
• src/synthorg/api/controllers/meetings.py
• tests/unit/api/controllers/test_approvals.py
• src/synthorg/api/controllers/meta_analytics.py
• src/synthorg/api/controllers/evaluation_config_versions.py
• src/synthorg/api/controllers/role_versions.py
• src/synthorg/api/controllers/requests.py
• src/synthorg/api/controllers/coordination_metrics.py
• src/synthorg/api/controllers/ontology.py
• src/synthorg/api/controllers/budget.py
• src/synthorg/api/controllers/ceremony_policy.py
• src/synthorg/api/controllers/audit.py
• src/synthorg/api/controllers/agent_identity_versions.py
• src/synthorg/api/controllers/providers.py
• src/synthorg/api/controllers/tasks.py
• scripts/generate_runtime_stats.py
• src/synthorg/api/controllers/approvals.py

🪛 LanguageTool

docs/reference/cli-commands.md

[locale-violation] ~84-~84: In American English, ‘afterward’ is the preferred variant. ‘Afterwards’ is more commonly used in British English and other dialects.
Context: ...| Restore without restarting containers afterwards | | backup restore | --timeout | `3...

(AFTERWARDS_US)

🔇 Additional comments (48)

site/src/components/FeatureShowcase.astro (1)

19-19: LGTM!

site/src/pages/compare.astro (1)

103-106: LGTM!

README.md (1)

22-22: LGTM!

src/synthorg/api/controllers/workflow_versions.py (1)

99-105: LGTM!

data/runtime_stats.yaml (1)

2-3: LGTM!

Also applies to: 6-6, 10-10, 14-15, 28-28

src/synthorg/api/controllers/messages.py (1)

3-3: LGTM!

Also applies to: 7-7, 39-42

src/synthorg/api/controllers/budget_config_versions.py (1)

84-90: LGTM!

src/synthorg/api/controllers/escalations.py (1)

12-12: LGTM!

Also applies to: 16-16, 137-142

tests/unit/api/controllers/test_meetings.py (1)

454-454: LGTM!

web/Caddyfile (1)

142-151: LGTM!

docs/guides/budget.md (1)

278-278: LGTM!

site/src/pages/index.astro (1)

156-159: LGTM!

docs/roadmap/future-vision.md (1)

9-9: LGTM!

src/synthorg/api/controllers/events.py (1)

549-549: LGTM!

Also applies to: 627-627

docs/guides/memory.md (1)

371-373: LGTM!

src/synthorg/api/controllers/company_versions.py (1)

84-90: LGTM!

docs/guides/workflow-api.md (1)

218-264: LGTM!

src/synthorg/api/controllers/subworkflows.py (1)

258-262: LGTM!

Also applies to: 287-291, 362-366

src/synthorg/api/controllers/meetings.py (1)

246-256: LGTM!

mkdocs.yml (1)

34-41: LGTM!

Also applies to: 190-194

docs/research/s1-multi-agent-decision.md (1)

62-62: LGTM!

docs/design/verification-quality.md (1)

137-167: LGTM!

pyproject.toml (1)

94-94: LGTM!

docs/design/hr-lifecycle.md (1)

296-315: LGTM!

Also applies to: 498-501

docs/research/multi-agent-failure-audit.md (1)

423-423: LGTM!

tests/unit/api/controllers/test_approvals.py (1)

705-705: LGTM!

src/synthorg/api/controllers/meta_analytics.py (1)

7-7: LGTM!

Also applies to: 117-124

src/synthorg/api/controllers/evaluation_config_versions.py (1)

84-90: LGTM!

src/synthorg/api/controllers/role_versions.py (1)

83-89: LGTM!

data/competitors.yaml (1)

116-117: LGTM!

docs/reference/cli-commands.md (1)

1-117: LGTM!

docs/roadmap/index.md (2)

5-5: Use the exact runtime-stats value in this RS marker.

<!--RS:tests-->30,000+<!--/RS--> is still a rounded placeholder and does not match the refreshed canonical count (30,536).

As per coding guidelines, "Numerics in README and public docs must be sourced from data/runtime_stats.yaml via markers; enforce Doc Numeric Claims".

---

17-17: LGTM!

Also applies to: 26-26, 40-40

src/synthorg/api/controllers/requests.py (1)

3-3: LGTM!

Also applies to: 7-7, 89-92

src/synthorg/api/controllers/coordination_metrics.py (1)

92-117: LGTM!

docs/user_guide.md (1)

78-79: LGTM!

src/synthorg/api/controllers/ontology.py (1)

8-8: LGTM!

Also applies to: 12-12, 135-138, 417-420

src/synthorg/api/controllers/budget.py (1)

300-313: LGTM!

docs/guides/agent-management.md (1)

96-96: LGTM!

Also applies to: 98-98, 100-100

src/synthorg/api/controllers/audit.py (1)

97-152: LGTM!

src/synthorg/api/controllers/agent_identity_versions.py (1)

181-187: LGTM!

src/synthorg/api/controllers/providers.py (1)

593-601: LGTM!

Also applies to: 882-889, 957-964

src/synthorg/api/controllers/tasks.py (1)

74-91: LGTM!

scripts/generate_runtime_stats.py (1)

8-9: LGTM!

Also applies to: 30-30, 69-70, 201-251

src/synthorg/api/controllers/approvals.py (1)

517-531: LGTM!

docs/guides/company-config.md (1)

191-225: LGTM!

Also applies to: 245-245, 335-355

docs/design/tools.md (1)

292-296: LGTM!

web/src/api/types/openapi.gen.ts (1)

13141-13141: LGTM!

Also applies to: 13723-13731, 14378-14378, 14405-14411, 14511-14511, 14859-14859, 15240-15250, 15760-15760, 15822-15822, 16190-16190, 16257-16259, 16377-16377, 16561-16561, 17338-17338, 17527-17527, 18101-18101, 18235-18235, 18265-18265, 18911-18911, 19120-19139, 19996-19996, 20027-20027, 20064-20064, 20119-20127, 21201-21201