docs: engine architecture research (#688 #690 #848 #687)#1114
Merged
docs: engine architecture research (#688 #690 #848 #687)#1114
Conversation
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (1)
📜 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). (2)
🧰 Additional context used🧠 Learnings (7)📓 Common learnings📚 Learning: 2026-04-07T16:48:04.262ZApplied to files:
📚 Learning: 2026-03-15T19:14:27.144ZApplied to files:
📚 Learning: 2026-03-15T19:14:27.144ZApplied to files:
📚 Learning: 2026-03-16T23:05:29.577ZApplied to files:
📚 Learning: 2026-04-07T16:48:04.262ZApplied to files:
📚 Learning: 2026-03-15T21:49:53.264ZApplied to files:
🔇 Additional comments (1)
WalkthroughThis PR adds or expands documentation across seven files, introducing: multi-agent failure‑pattern guardrails (meeting protocols, delegation guards, conflict‑resolution behaviors), an ACG↔SynthOrg vocabulary mapping, agent‑controlled context compaction research, a control‑plane API surface audit, and design notes framing SynthOrg as an orchestrated agent control plane with policy/telemetry considerations. All changes are documentation‑only; no public APIs or exported entities were modified. 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
Contributor
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Snapshot WarningsEnsure that dependencies are being submitted on PR branches. Re-running this action after a short time may resolve the issue. See the documentation for more information and troubleshooting advice. Scanned FilesNone |
Contributor
There was a problem hiding this comment.
Code Review
This pull request introduces extensive documentation and research evaluations for the SynthOrg engine, covering its alignment with the Agentic Computation Graph (ACG) formalism, its role as an agent control plane, and strategies for context compaction and multi-agent failure prevention. The documentation identifies several architectural risks, such as meeting-task feedback loops and circuit breaker vulnerabilities, as well as API surface gaps like the lack of OTLP telemetry. Feedback focused on enhancing the documentation with specific implementation timelines, defining explicit backoff strategies for delegation guards, and detailing the TF-IDF proxy implementation for context compression.
|
|
||
| | # | Gap | Severity | Recommendation | | ||
| |---|-----|----------|----------------| | ||
| | G1 | No telemetry export (Prometheus `/metrics` or OTLP) | High | Add `/metrics` route + metrics aggregator. The 82+ structured events provide all raw data. | |
Contributor
There was a problem hiding this comment.
The lack of Prometheus /metrics or OTLP export is a critical gap for enterprise observability. Prioritizing this over other API surface gaps is correct, but consider adding a specific timeline or milestone for this implementation in the roadmap.
Comment on lines
+304
to
+310
| After cooldown (default 300s), the circuit breaker evicts the state entry entirely: | ||
|
|
||
| ```python | ||
| # circuit_breaker.py:112-114 | ||
| # Cooldown expired: evict the stale entry | ||
| del self._pairs[key] | ||
| ``` |
Contributor
There was a problem hiding this comment.
The circuit breaker bounce count reset vulnerability is a critical design flaw. The current implementation of evicting the state entry entirely after cooldown is too simplistic for production. Consider implementing a non-resetting global bounce counter or exponential backoff as suggested in the audit.
docs/design/communication.md
Outdated
Comment on lines
+493
to
+496
| **Known risk -- circuit breaker bounce count reset**: After cooldown, the state entry is | ||
| evicted entirely, resetting the bounce count to 0. Slow-burn delegation patterns (>60s | ||
| between delegations) can bypass all five guards after each cooldown expiry. Mitigation: | ||
| use exponential backoff on cooldown resets or a non-resetting global bounce counter. |
Contributor
There was a problem hiding this comment.
The circuit breaker bounce count reset vulnerability is a significant design flaw for production systems. While the research note is helpful, it is recommended to explicitly define the exponential backoff strategy or the global counter mechanism in the design document to ensure it is implemented consistently.
docs/design/engine.md
Outdated
Comment on lines
+1550
to
+1555
| **Phase 3**: Evaluate surprisal-based token cost (arXiv:2603.08462) -- per-token cost | ||
| weighted by surprisal under a frozen base model. Empirical results: 41% token reduction, | ||
| <1.5% accuracy drop. **Not recommended for Phase 1/2**: inference cost (forward pass | ||
| per token) is not justified until Phase 2 data validates the need. TF-IDF importance | ||
| weighting is the recommended lighter proxy if semantic token cost is needed before | ||
| Phase 3. |
Contributor
There was a problem hiding this comment.
The research evaluation correctly identifies that full surprisal-based token cost scoring is computationally expensive. It would be beneficial to document the specific TF-IDF proxy implementation details in the design roadmap to guide future developers.
There was a problem hiding this comment.
Actionable comments posted: 10
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/design/communication.md`:
- Around line 468-469: The docs refer to a non-existent method
`MeetingScheduler.trigger_event()`; update the text to reference the actual
scheduler API `MeetingScheduler.on_event(...)` (use the same signature/format
shown in code) and, while editing, mention the required deduplication/cooldown
guard by noting the `min_interval_seconds` parameter on the scheduler to prevent
runaway task/meeting cycles; ensure the section header and any inline examples
use `on_event(...)` consistently.
In `@docs/design/engine.md`:
- Around line 1502-1504: The doc currently references
CompactionConfig.threshold_percent but the code uses
CompactionConfig.fill_threshold_percent; update the design doc text to use the
real config key name (fill_threshold_percent) and adjust any example config
snippets or prose to match the implementation; mention invoke_compaction() from
engine/loop_helpers.py as the helper that reads
CompactionConfig.fill_threshold_percent so readers see the correct field name
and behavior.
In `@docs/research/acg-formalism-evaluation.md`:
- Around line 255-258: The doc currently only mentions creating an ApprovalItem
for PruningEvaluation with action_type="org:prune" and ApprovalRiskLevel.MEDIUM
but omits required fields; update the guidance to construct an ApprovalItem
including id (unique UUID per PruningEvaluation), title (short summary like
"Prune resource X" derived from PruningEvaluation.target or recommendation),
description (detailed rationale including PruningEvaluation.reason, evidence,
and affected resources), requested_by (agent or system id that produced the
recommendation, e.g., PruningEvaluation.requested_by or "autoprune-bot"),
risk_level (ApprovalRiskLevel.MEDIUM as noted), and created_at (ISO8601
timestamp from PruningEvaluation.created_at or now); reference the
PruningEvaluation and ApprovalItem symbols so implementers populate these fields
when recommendation=="PRUNE".
- Around line 318-323: Clarify and implement backward-compatible handling for
adding the NodeType enum: define a new NodeType enum (LLM_CALL, TOOL_INVOCATION,
QUALITY_CHECK, BUDGET_CHECK, STAGNATION_CHECK) but make the TurnRecord change
non-breaking by either (a) adding nodeType as an optional/nullable field with a
well-documented default value (e.g., UNKNOWN) in TurnRecord, (b) only populating
nodeType for newly created records and leaving existing persisted records
untouched with a migration plan, or (c) creating a separate TurnRecordEnrichment
model that references TurnRecord and contains nodeType metadata; update
serialization/deserialization, persistence routines, and any consumers (e.g.,
trace analyzers) to tolerate missing nodeType and prefer the enrichment model if
present.
- Around line 162-174: The proposal currently says "extend CoordinationResult"
but CoordinationResult sets model_config = ConfigDict(frozen=True), so clarify
the integration by specifying one concrete approach: either (A) add an
agent_contributions field to CoordinationResult and remove or alter the frozen
config (update CoordinationResult's model_config and migration path) with
mention of AgentContribution as the field type, or (B) introduce a separate
wrapper model CoordinationResultWithAttribution that contains a
CoordinationResult plus agent_contributions: list[AgentContribution], or (C)
store AgentContribution records externally and reference them (e.g., by
result_id) in CoordinationResult; update the doc to pick one approach and
reference the symbols CoordinationResult, model_config =
ConfigDict(frozen=True), AgentContribution, agent_contributions, and
CoordinationResultWithAttribution so reviewers can locate the exact change to
implement.
- Around line 133-134: Clarify which API surface lacks quality-cost tradeoff
exposure by explicitly naming the affected endpoints and types (e.g., REST
endpoint GET /tasks/{id} and the Python type CoordinationResult) and describing
the missing fields: list the specific REST response properties and Python
attributes that should surface cost, quality, and tradeoff metadata (for
example: estimated_cost, actual_cost, quality_score, confidence,
cost_quality_curve or tradeoffs array), and state whether both surfaces need
parity or one is authoritative; update the sentence to read something like
"Expose quality-cost tradeoffs in GET /tasks/{id} (add estimated_cost,
actual_cost, quality_score, confidence, cost_quality_curve) and in the Python
CoordinationResult class with matching attributes" so implementers know exactly
which endpoints/types and fields to change.
- Line 234: The fenced code block containing "PruningEvaluation (new model)" is
missing a language identifier; update that fence to include a language (e.g.,
change ``` to ```python or ```text) so linting passes and intent is clear,
targeting the code block that contains the text "PruningEvaluation (new model)"
in the document.
In `@docs/research/agent-controlled-compaction.md`:
- Around line 311-315: The example calls invoke_compaction with the wrong
argument order and misses the turn number; update the snippet in
execute_tool_calls (or the loop's per-turn handler) to call invoke_compaction
with the correct signature: pass ctx first, then compaction_callback, and
include the current turn_number (i.e., invoke_compaction(ctx,
compaction_callback, turn_number)) whenever any tool_result.metadata has
"compaction_directive". Ensure the variables used (ctx, compaction_callback,
turn_number, tool_results) match the surrounding code.
In `@docs/research/control-plane-audit.md`:
- Around line 51-62: The API endpoint table uses unversioned/divergent paths
(e.g., "GET /agents", "GET /agents/{id}", "PUT /agents/{id}/autonomy", "GET
/departments/{name}/health") that conflict with the defined contract; update
each table entry to the canonical routes under the API contract (prefix paths
with /api/v1 and ensure HTTP methods match the contract in
docs/design/operations.md), replacing instances at lines referenced (e.g., the
entries for List agents, Get agent, Set autonomy, Department health and the
other mentioned blocks) so they use the exact canonical endpoints and method
shapes from the operations.md spec and preserve the same Notes/permission text.
In `@docs/research/multi-agent-failure-audit.md`:
- Around line 174-191: The fenced fallback-chain diagram uses a plain ``` fence;
update the opening fence to include a language tag (e.g., change ``` to ```text)
so markdown linters accept it; modify the fenced block that contains
"HybridResolver", "DebateResolver", "HumanEscalationResolver", and
"AuthorityResolver" by adding the language after the opening backticks.
🪄 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: 4f51ea3b-ea7f-483e-b228-308a6ee7097e
📒 Files selected for processing (7)
docs/design/communication.mddocs/design/engine.mddocs/design/operations.mddocs/research/acg-formalism-evaluation.mddocs/research/agent-controlled-compaction.mddocs/research/control-plane-audit.mddocs/research/multi-agent-failure-audit.md
📜 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). (4)
- GitHub Check: Deploy Preview
- GitHub Check: Agent
- GitHub Check: Dependency Review
- GitHub Check: Analyze (python)
🧰 Additional context used
📓 Path-based instructions (2)
docs/design/*.md
📄 CodeRabbit inference engine (CLAUDE.md)
When approved deviations occur, update the relevant
docs/design/page to reflect the new reality.
Files:
docs/design/engine.mddocs/design/communication.mddocs/design/operations.md
docs/design/operations.md
📄 CodeRabbit inference engine (CLAUDE.md)
Vendor names may appear in: (1) Operations design page (
docs/design/operations.md), (2).claude/skill/agent files, (3) third-party import paths, (4) provider presets (src/synthorg/providers/presets.py).
Files:
docs/design/operations.md
🧠 Learnings (20)
📓 Common learnings
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to docs/design/*.md : Design spec pages: 7 pages in `docs/design/` — index, agents, organization, communication, engine, memory, operations
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-16T06:24:56.341Z
Learning: Applies to docs/design/**/*.md : Design specification pages in `docs/design/` must be consulted before implementing features (7 pages: index, agents, organization, communication, engine, memory, operations)
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:13:44.964Z
Learning: Always read the relevant `docs/design/` page before implementing any feature or planning any issue — DESIGN_SPEC.md is a pointer file linking to 7 design pages (Agents, Organization, Communication, Engine, Memory, Operations)
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-14T15:43:05.601Z
Learning: Applies to docs/** : Docs source in docs/ (Markdown, built with Zensical); design spec in docs/design/ (7 pages: index, agents, organization, communication, engine, memory, operations)
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Engine: Agent orchestration, execution loops, parallel execution, task decomposition, routing, task assignment, centralized single-writer task state engine (TaskEngine), task lifecycle, recovery, shutdown, workspace isolation, coordination (multi-agent pipeline: TopologyDispatcher protocol, 4 dispatchers — SAS/centralized/decentralized/context-dependent, wave execution, workspace lifecycle integration, CoordinationSectionConfig company config bridge, build_coordinator factory), coordination error classification, prompt policy validation, checkpoint recovery (checkpoint/, per-turn persistence, heartbeat detection, CheckpointRecoveryStrategy), approval gate (escalation detection, context parking/resume, EscalationInfo/ResumePayload models), stagnation detection (stagnation/, StagnationDetector protocol, ToolRepetitionDetector, dual-signal analysis, corrective prompt injection), agent runtime state (AgentRuntimeState, lightweight per-agent execution status for dashboard queries and recove...
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-06T16:35:12.934Z
Learning: Agents in the Parallel tier (Haiku-class) include 14 reviewers: async-concurrency-reviewer, comment-analyzer, design-token-audit, docs-consistency, go-conventions-enforcer, go-security-reviewer, infra-reviewer, issue-resolution-verifier, persistence-reviewer, pr-test-analyzer, security-reviewer, silent-failure-hunter, test-quality-reviewer, and type-design-analyzer
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T18:38:44.202Z
Learning: Always read the relevant `docs/design/` page before implementing any feature or planning any issue. DESIGN_SPEC.md is a pointer file linking to the 7 design pages (index, agents, organization, communication, engine, memory, operations).
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Documentation source in `docs/` (Markdown, built with Zensical). Design spec in `docs/design/` (7 pages: index, agents, organization, communication, engine, memory, operations). Architecture in `docs/architecture/` (overview, tech-stack, decision log). Roadmap in `docs/roadmap/`. Security in `docs/security.md`. Licensing in `docs/licensing.md`. Reference in `docs/reference/`. REST API reference in `docs/rest-api.md`. Library reference in `docs/api/` (auto-generated from docstrings). Custom templates in `docs/overrides/`. Config in `mkdocs.yml`.
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-07T16:48:04.262Z
Learning: See [DESIGN_SPEC.md](docs/DESIGN_SPEC.md) for the pointer to 12 design pages covering architecture, data models, and behavior.
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to docs/design/*.md : Design spec pages: 7 pages in `docs/design/` — index, agents, organization, communication, engine, memory, operations
Applied to files:
docs/design/engine.mddocs/research/control-plane-audit.mddocs/design/communication.mddocs/design/operations.mddocs/research/agent-controlled-compaction.mddocs/research/acg-formalism-evaluation.mddocs/research/multi-agent-failure-audit.md
📚 Learning: 2026-03-16T06:24:56.341Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-16T06:24:56.341Z
Learning: Applies to docs/design/**/*.md : Design specification pages in `docs/design/` must be consulted before implementing features (7 pages: index, agents, organization, communication, engine, memory, operations)
Applied to files:
docs/design/engine.mddocs/research/control-plane-audit.mddocs/design/communication.mddocs/design/operations.mddocs/research/agent-controlled-compaction.mddocs/research/acg-formalism-evaluation.mddocs/research/multi-agent-failure-audit.md
📚 Learning: 2026-03-19T07:13:44.964Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:13:44.964Z
Learning: Always read the relevant `docs/design/` page before implementing any feature or planning any issue — DESIGN_SPEC.md is a pointer file linking to 7 design pages (Agents, Organization, Communication, Engine, Memory, Operations)
Applied to files:
docs/design/engine.mddocs/design/communication.mddocs/design/operations.mddocs/research/agent-controlled-compaction.mddocs/research/multi-agent-failure-audit.md
📚 Learning: 2026-03-14T15:43:05.601Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-14T15:43:05.601Z
Learning: Applies to docs/** : Docs source in docs/ (Markdown, built with Zensical); design spec in docs/design/ (7 pages: index, agents, organization, communication, engine, memory, operations)
Applied to files:
docs/design/engine.mddocs/design/operations.mddocs/research/agent-controlled-compaction.mddocs/research/acg-formalism-evaluation.mddocs/research/multi-agent-failure-audit.md
📚 Learning: 2026-03-15T18:38:44.202Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T18:38:44.202Z
Learning: Always read the relevant `docs/design/` page before implementing any feature or planning any issue. DESIGN_SPEC.md is a pointer file linking to the 7 design pages (index, agents, organization, communication, engine, memory, operations).
Applied to files:
docs/design/engine.mddocs/design/communication.mddocs/design/operations.md
📚 Learning: 2026-03-17T22:08:13.456Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Engine: Agent orchestration, execution loops, parallel execution, task decomposition, routing, task assignment, centralized single-writer task state engine (TaskEngine), task lifecycle, recovery, shutdown, workspace isolation, coordination (multi-agent pipeline: TopologyDispatcher protocol, 4 dispatchers — SAS/centralized/decentralized/context-dependent, wave execution, workspace lifecycle integration, CoordinationSectionConfig company config bridge, build_coordinator factory), coordination error classification, prompt policy validation, checkpoint recovery (checkpoint/, per-turn persistence, heartbeat detection, CheckpointRecoveryStrategy), approval gate (escalation detection, context parking/resume, EscalationInfo/ResumePayload models), stagnation detection (stagnation/, StagnationDetector protocol, ToolRepetitionDetector, dual-signal analysis, corrective prompt injection), agent runtime state (AgentRuntimeState, lightweight per-agent execution status for dashboard queries and recove...
Applied to files:
docs/design/engine.mddocs/design/communication.mddocs/design/operations.mddocs/research/acg-formalism-evaluation.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to src/synthorg/engine/**/*.py : Engine package (engine/): agent orchestration, parallel execution, task decomposition, routing, TaskEngine (centralized single-writer), task lifecycle/recovery/shutdown, workspace isolation, coordination (4 dispatchers: SAS/centralized/decentralized/context-dependent, wave execution), approval gates (escalation detection, context parking/resume), stagnation detection (ToolRepetitionDetector, corrective prompt injection), AgentRuntimeState (execution status), context budget management, conversation compaction (oldest-turns summarizer)
Applied to files:
docs/design/engine.mddocs/design/operations.md
📚 Learning: 2026-03-17T06:30:14.180Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T06:30:14.180Z
Learning: Applies to src/synthorg/security/**/*.py : Security module includes SecOps agent, rule engine (soft-allow/hard-deny), audit log, output scanner, risk classifier, autonomy levels (4 strategies), timeout policies.
Applied to files:
docs/research/control-plane-audit.mddocs/design/communication.mddocs/design/operations.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to src/synthorg/security/**/*.py : Security package (security/): SecOps agent, rule engine (soft-allow/hard-deny, fail-closed), audit log, output scanner, output scan response policies (redact/withhold/log-only/autonomy-tiered), risk classifier, risk tier classifier, action type registry, ToolInvoker security integration, progressive trust (4 strategies), autonomy levels (presets, resolver, change strategy), timeout policies (park/resume)
Applied to files:
docs/research/control-plane-audit.mddocs/design/communication.mddocs/design/operations.md
📚 Learning: 2026-03-17T22:08:13.456Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Security: SecOps agent, rule engine (soft-allow/hard-deny, fail-closed), audit log, output scanner, output scan response policies (redact/withhold/log-only/autonomy-tiered), risk classifier, risk tier classifier, action type registry, ToolInvoker security integration, progressive trust (4 strategies: disabled/weighted/per-category/milestone), autonomy levels (presets, resolver, change strategy), timeout policies (park/resume).
Applied to files:
docs/research/control-plane-audit.mddocs/design/communication.mddocs/design/operations.mddocs/research/multi-agent-failure-audit.md
📚 Learning: 2026-03-17T06:30:14.180Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T06:30:14.180Z
Learning: Applies to src/synthorg/engine/coordination/**/*.py : Task coordination uses multi-agent pipeline with 4 dispatchers (SAS/centralized/decentralized/context-dependent), wave execution, and workspace lifecycle integration.
Applied to files:
docs/design/communication.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to src/synthorg/communication/**/*.py : Communication package (communication/): message bus, dispatcher, messenger, channels, delegation, loop prevention, conflict resolution; meeting/ subpackage for meeting protocol (round-robin, position papers, structured phases), scheduler (frequency, participant resolver), orchestrator
Applied to files:
docs/design/communication.md
📚 Learning: 2026-04-06T16:35:12.934Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-06T16:35:12.934Z
Learning: Agents in the Parallel tier (Haiku-class) include 14 reviewers: async-concurrency-reviewer, comment-analyzer, design-token-audit, docs-consistency, go-conventions-enforcer, go-security-reviewer, infra-reviewer, issue-resolution-verifier, persistence-reviewer, pr-test-analyzer, security-reviewer, silent-failure-hunter, test-quality-reviewer, and type-design-analyzer
Applied to files:
docs/design/communication.md
📚 Learning: 2026-04-07T16:48:04.262Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-07T16:48:04.262Z
Learning: Applies to docs/design/operations.md : Vendor names may appear in: (1) Operations design page (`docs/design/operations.md`), (2) `.claude/` skill/agent files, (3) third-party import paths, (4) provider presets (`src/synthorg/providers/presets.py`).
Applied to files:
docs/design/operations.md
📚 Learning: 2026-03-17T22:08:13.456Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Documentation source in `docs/` (Markdown, built with Zensical). Design spec in `docs/design/` (7 pages: index, agents, organization, communication, engine, memory, operations). Architecture in `docs/architecture/` (overview, tech-stack, decision log). Roadmap in `docs/roadmap/`. Security in `docs/security.md`. Licensing in `docs/licensing.md`. Reference in `docs/reference/`. REST API reference in `docs/rest-api.md`. Library reference in `docs/api/` (auto-generated from docstrings). Custom templates in `docs/overrides/`. Config in `mkdocs.yml`.
Applied to files:
docs/design/operations.md
📚 Learning: 2026-03-31T14:31:11.894Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:31:11.894Z
Learning: Applies to docs/design/*.md : Update the relevant `docs/design/` page when approved deviations occur to reflect the new reality
Applied to files:
docs/design/operations.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to src/synthorg/**/*.py : Package structure: src/synthorg/ organized as: api/ (REST+WebSocket, Litestar), auth/ (auth subpackage), backup/ (scheduled/manual backups), budget/ (cost tracking, CFO), cli/ (superseded by Go CLI), communication/ (message bus, meetings), config/ (YAML loading), core/ (domain models, resilience config), engine/ (orchestration, task state, coordination, approval gates, stagnation detection, context budget, compaction), hr/ (hiring, performance, promotion), memory/ (pluggable backend, Mem0, retrieval, consolidation), persistence/ (operational data, SQLite, settings), observability/ (logging, correlation, sinks), providers/ (LLM abstraction, LiteLLM, auth types, presets, runtime CRUD), settings/ (runtime-editable, typed definitions, encryption, config bridge), security/ (SecOps, rule engine, output scanning, progressive trust, autonomy levels), templates/ (company templates, personalities), tools/ (registry, built-in tools, git, sandbox, code_runner, MCP...
Applied to files:
docs/design/operations.md
📚 Learning: 2026-03-17T06:30:14.180Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T06:30:14.180Z
Learning: Applies to src/synthorg/observability/**/*.py : Observability includes structured logging via `get_logger(__name__)`, correlation tracking, and log sinks.
Applied to files:
docs/design/operations.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to src/synthorg/api/**/*.py : API package (api/): Litestar REST + WebSocket with controllers, guards, channels, JWT + API key + WS ticket auth, approval gate integration, coordination endpoint, collaboration endpoint, settings endpoint, provider management endpoint (CRUD + test + presets), backup endpoint, RFC 9457 structured errors, AppState hot-reload slots, service auto-wiring (Phase 1 at construction, Phase 2 on startup), lifecycle helpers
Applied to files:
docs/design/operations.md
🪛 LanguageTool
docs/research/control-plane-audit.md
[style] ~276-~276: To elevate your writing, try using a synonym here.
Context: ...rades. This integration is genuine and hard to replicate by composing separate tool...
(HARD_TO)
docs/research/multi-agent-failure-audit.md
[grammar] ~325-~325: Ensure spelling is correct
Context: ...uit breaker reset (e.g., first reset at 5min, second at 10min, third at 20min) or a ...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~325-~325: Ensure spelling is correct
Context: ...t (e.g., first reset at 5min, second at 10min, third at 20min) or a global per-pair b...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~325-~325: Ensure spelling is correct
Context: ...eset at 5min, second at 10min, third at 20min) or a global per-pair bounce counter th...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🪛 markdownlint-cli2 (0.22.0)
docs/research/acg-formalism-evaluation.md
[warning] 234-234: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
docs/research/multi-agent-failure-audit.md
[warning] 174-174: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (5)
docs/design/operations.md (1)
1793-1854: Control-plane section is clear and implementation-alignedThe added framing, constraints, and G1–G6 gap table are consistent and actionable for follow-on work.
docs/research/acg-formalism-evaluation.md (4)
1-336: Well-structured research document with actionable recommendations.This research document provides a thorough evaluation of the ACG formalism mapping to SynthOrg and proposes valuable extensions for structural credit assignment and agent pruning. The mapping tables are comprehensive, the survey validation is evidence-based, and the recommendations are concrete. The document successfully addresses the objectives from issue
#848.
34-34: No action needed — WorkflowDefinition is a concrete, documented class.The research document's reference to
WorkflowDefinitionfor workflow templates is accurate.WorkflowDefinitionexists atsrc/synthorg/engine/workflow/definition.pyas a complete BaseModel class with full documentation. The mapping table note is correct and does not require clarification or source file references beyond what the document already provides.
187-190: All integration points are confirmed to exist in the codebase. No changes needed.The referenced infrastructure is real:
_post_execution_pipelineexists atsrc/synthorg/engine/agent_engine.py:668PerformanceTracker.record_task_metricexists atsrc/synthorg/hr/performance/tracker.py:155GET /tasks/{id}endpoint exists atsrc/synthorg/api/controllers/tasks.py:201The documentation accurately reflects existing, integrated components.
> Likely an incorrect or invalid review comment.
211-212: FiringReason.PERFORMANCE is defined but never programmatically invoked.Line 212 claim verified. Across the codebase,
FiringReason.PERFORMANCEis defined in the enum but appears only in unit tests validating enum values. No production code creates aFiringRequestwith thePERFORMANCEreason, and there is no automated trigger inOffboardingService.offboard()or any performance monitoring system that invokes offboarding based on performance data.
Comment on lines
+468
to
+469
| `MeetingScheduler.trigger_event()` has no deduplication or cooldown. Event-triggered | ||
| meetings should use a `min_interval_seconds` guard to prevent runaway task/meeting cycles. |
There was a problem hiding this comment.
Use the current scheduler method name
Line 468 references MeetingScheduler.trigger_event(), but the implementation surface shown is MeetingScheduler.on_event(...). Please update the identifier in this section to match code.
As per coding guidelines, “When approved deviations occur, update the relevant docs/design/ page to reflect the new reality.”
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/design/communication.md` around lines 468 - 469, The docs refer to a
non-existent method `MeetingScheduler.trigger_event()`; update the text to
reference the actual scheduler API `MeetingScheduler.on_event(...)` (use the
same signature/format shown in code) and, while editing, mention the required
deduplication/cooldown guard by noting the `min_interval_seconds` parameter on
the scheduler to prevent runaway task/meeting cycles; ensure the section header
and any inline examples use `on_event(...)` consistently.
Comment on lines
+318
to
+323
| **Formal node typing** is the one ACG concept that could benefit from a lightweight code | ||
| adoption. Introducing a `NodeType` enum with values `LLM_CALL`, `TOOL_INVOCATION`, | ||
| `QUALITY_CHECK`, `BUDGET_CHECK`, `STAGNATION_CHECK` and tagging `TurnRecord` with the | ||
| node types executed in that turn would improve execution trace analysis without | ||
| significant refactoring. This is optional but would directly enable structural credit | ||
| assignment (knowing which node type failed). |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Address backward compatibility for TurnRecord modification.
The optional recommendation to add a NodeType enum to TurnRecord (lines 318-323) doesn't address backward compatibility concerns. TurnRecord is part of execution results and likely persisted. Adding a required field would break existing data and APIs. Clarify whether this field should be:
- Optional with a default value
- Added only to new records (with migration plan)
- A separate enrichment model
Based on learnings, the engine uses TurnRecord in execution traces with per-turn cost and token usage, so changes impact serialization and storage.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/research/acg-formalism-evaluation.md` around lines 318 - 323, Clarify
and implement backward-compatible handling for adding the NodeType enum: define
a new NodeType enum (LLM_CALL, TOOL_INVOCATION, QUALITY_CHECK, BUDGET_CHECK,
STAGNATION_CHECK) but make the TurnRecord change non-breaking by either (a)
adding nodeType as an optional/nullable field with a well-documented default
value (e.g., UNKNOWN) in TurnRecord, (b) only populating nodeType for newly
created records and leaving existing persisted records untouched with a
migration plan, or (c) creating a separate TurnRecordEnrichment model that
references TurnRecord and contains nodeType metadata; update
serialization/deserialization, persistence routines, and any consumers (e.g.,
trace analyzers) to tolerate missing nodeType and prefer the enrichment model if
present.
Contributor
There was a problem hiding this comment.
Pull request overview
Docs-only engine architecture research deliverables covering planned dependency order across issues #688, #690, #848, and #687, plus design-page updates that integrate the findings into the canonical design docs.
Changes:
- Added four new research documents under
docs/research/(control plane audit, multi-agent failure audit, ACG formalism evaluation, agent-controlled compaction evaluation). - Updated design docs (
operations.md,communication.md,engine.md) to summarize and cross-reference the research findings. - Documented concrete gap/recommendation lists (e.g., telemetry export, meeting/task feedback loop, compaction roadmap).
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/research/multi-agent-failure-audit.md | New research writeup auditing meeting protocols, conflict resolution termination, and loop-prevention guardrails. |
| docs/research/control-plane-audit.md | New research mapping modules to “agent control plane” primitives + API surface gap analysis. |
| docs/research/agent-controlled-compaction.md | New research evaluating current compaction + proposing agent-controlled compaction roadmap. |
| docs/research/acg-formalism-evaluation.md | New research mapping engine concepts to ACG vocabulary + proposing credit assignment/pruning directions. |
| docs/design/operations.md | Adds “SynthOrg as Agent Control Plane” section summarizing #688 findings and gaps. |
| docs/design/engine.md | Adds ACG glossary section + compaction roadmap section summarizing #848/#687. |
| docs/design/communication.md | Adds guardrails/risk summary section based on #690 findings. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
docs/design/engine.md
Outdated
| *Research findings from #687. See also: `docs/research/agent-controlled-compaction.md`.* | ||
|
|
||
| Context compaction is invoked at turn boundaries when context fill exceeds the configured | ||
| threshold (`CompactionConfig.threshold_percent`, default 80%). The `invoke_compaction()` |
There was a problem hiding this comment.
CompactionConfig doesn't have a threshold_percent field; the config uses fill_threshold_percent (default 80.0). Update the design text to reference the correct field name to avoid misleading readers and copy/paste errors.
Suggested change
| threshold (`CompactionConfig.threshold_percent`, default 80%). The `invoke_compaction()` | |
| threshold (`CompactionConfig.fill_threshold_percent`, default 80%). The `invoke_compaction()` |
docs/research/control-plane-audit.md
Outdated
| | Get autonomy config | `GET /agents/{id}/autonomy` | Per-agent override | | ||
| | Set autonomy config | `PUT /agents/{id}/autonomy` | Write access | | ||
| | List pending approvals | `GET /approvals` | Approval queue for escalated actions | | ||
| | Decide approval | `POST /approvals/{id}/decide` | CEO/manager/board | |
There was a problem hiding this comment.
The approval decision endpoint is documented as POST /approvals/{id}/decide, but the API exposes separate endpoints: POST /approvals/{approval_id}/approve and POST /approvals/{approval_id}/reject (see ApprovalsController). Update the table so it matches the actual routes.
Suggested change
| | Decide approval | `POST /approvals/{id}/decide` | CEO/manager/board | | |
| | Approve pending approval | `POST /approvals/{approval_id}/approve` | CEO/manager/board approval action | | |
| | Reject pending approval | `POST /approvals/{approval_id}/reject` | CEO/manager/board rejection action | |
Comment on lines
+206
to
+212
| | Operation | Endpoint | Notes | | ||
| |---|---|---| | ||
| | Analytics dashboard | `GET /analytics` | Summary metrics | | ||
| | Generate report | `POST /reports/generate` | Spending, performance, task completion | | ||
| | List log sinks | `GET /settings/observability/sinks` | Current sink configuration | | ||
| | Test sink connectivity | `POST /settings/observability/sinks/_test` | CEO/manager | | ||
| | Liveness/readiness | `GET /health` | Public, no auth | |
There was a problem hiding this comment.
GET /analytics isn't an actual endpoint; AnalyticsController defines GET /analytics/overview, /analytics/trends, and /analytics/forecast (no handler at the controller root). Consider updating this row to point at /analytics/overview (or listing the available analytics endpoints).
docs/research/control-plane-audit.md
Outdated
Comment on lines
+162
to
+175
| | Current budget status | `GET /budget` | Total spent, remaining, utilization % | | ||
| | Spending history | `GET /budget/history` | Historical records | | ||
| | Set/update budget | `POST /budget` | Write access | | ||
| | Generate report | `POST /reports/generate` | Spending, performance, risk trends | | ||
|
|
||
| **Coverage**: Basic budget queries are covered. `GET /budget` returns utilization percentage | ||
| and alert status. `GET /budget/history` returns spending records. | ||
|
|
||
| **Gap -- G6**: `CostTracker` is in-memory with TTL eviction; it is not a durable time-series | ||
| store. Budget history granularity is limited -- the tracker supports `get_agent_cost(agent_id, | ||
| start=)` and `get_total_cost(start=)` but the API endpoint does not expose multi-dimensional | ||
| queries (e.g., spending by provider X for agent Y during period Z). External cost dashboards | ||
| need this level of attribution. The persistence layer backing `GET /budget/history` needs | ||
| inspection to confirm whether it provides richer query semantics than the in-memory tracker. |
There was a problem hiding this comment.
The budget endpoints in this table don't match the current API surface. BudgetController exposes GET /budget/config, GET /budget/records, and GET /budget/agents/{agent_id}; there is no GET /budget, GET /budget/history, or POST /budget route in the controllers. Please update the listed endpoints (and the following paragraph that references them) to align with the actual routes.
Suggested change
| | Current budget status | `GET /budget` | Total spent, remaining, utilization % | | |
| | Spending history | `GET /budget/history` | Historical records | | |
| | Set/update budget | `POST /budget` | Write access | | |
| | Generate report | `POST /reports/generate` | Spending, performance, risk trends | | |
| **Coverage**: Basic budget queries are covered. `GET /budget` returns utilization percentage | |
| and alert status. `GET /budget/history` returns spending records. | |
| **Gap -- G6**: `CostTracker` is in-memory with TTL eviction; it is not a durable time-series | |
| store. Budget history granularity is limited -- the tracker supports `get_agent_cost(agent_id, | |
| start=)` and `get_total_cost(start=)` but the API endpoint does not expose multi-dimensional | |
| queries (e.g., spending by provider X for agent Y during period Z). External cost dashboards | |
| need this level of attribution. The persistence layer backing `GET /budget/history` needs | |
| inspection to confirm whether it provides richer query semantics than the in-memory tracker. | |
| | Budget configuration | `GET /budget/config` | Budget settings, thresholds, and enforcement config | | |
| | Spending records | `GET /budget/records` | Historical budget and cost records | | |
| | Agent budget records | `GET /budget/agents/{agent_id}` | Per-agent spending and budget details | | |
| | Generate report | `POST /reports/generate` | Spending, performance, risk trends | | |
| **Coverage**: Basic budget queries are covered. `GET /budget/config` exposes budget | |
| configuration, `GET /budget/records` returns spending records, and | |
| `GET /budget/agents/{agent_id}` provides agent-specific budget details. | |
| **Gap -- G6**: `CostTracker` is in-memory with TTL eviction; it is not a durable time-series | |
| store. Budget history granularity is limited -- the tracker supports `get_agent_cost(agent_id, | |
| start=)` and `get_total_cost(start=)` but the documented API surface still does not clearly | |
| expose multi-dimensional queries (e.g., spending by provider X for agent Y during period Z). | |
| External cost dashboards need this level of attribution. The persistence layer backing | |
| `GET /budget/records` and `GET /budget/agents/{agent_id}` needs inspection to confirm | |
| whether it provides richer query semantics than the in-memory tracker. |
- engine.md: fix CompactionConfig field name threshold_percent to fill_threshold_percent
- engine.md: expand TF-IDF proxy implementation details in Phase 3 roadmap
- agent-controlled-compaction.md: correct invoke_compaction() argument order and add missing turn_number
- control-plane-audit.md: fix approval endpoints (decide split into approve + reject)
- control-plane-audit.md: fix analytics endpoint (overview/trends/forecast)
- control-plane-audit.md: fix budget endpoints (config, records, agents/{id})
- acg-formalism-evaluation.md: clarify CoordinationResult frozen=True integration approach
- acg-formalism-evaluation.md: specify API surface for quality-cost tradeoff exposure
- acg-formalism-evaluation.md: add language tag to PruningEvaluation code block
- acg-formalism-evaluation.md: specify all required ApprovalItem fields for pruning gate
- acg-formalism-evaluation.md: add backward compat note for optional TurnRecord.node_types
- multi-agent-failure-audit.md: add language tag to fallback-chain code block
- communication.md: document concrete circuit breaker exponential backoff options
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (2)
docs/research/acg-formalism-evaluation.md (1)
202-205:⚠️ Potential issue | 🟠 MajorResolve the contradiction on attribution integration (
wrappervsextend).This document first recommends a wrapper because
CoordinationResultis frozen, but later reverts to “extendCoordinationResultwithAgentContribution.” Pick one approach consistently (preferably the wrapper already described) to avoid implementation ambiguity.Also applies to: 357-359
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/research/acg-formalism-evaluation.md` around lines 202 - 205, The document currently contradicts itself about how to integrate attribution: choose and document one consistent approach (prefer the wrapper pattern). Update all mentions to use the wrapper approach: describe creating a new WrapperCoordinationResult (or similar) that contains a CoordinationResult plus a list of AgentContribution populated by infer_failure_category() per-agent, remove or replace the lines that say “extend CoordinationResult with AgentContribution,” and ensure any examples and the referenced sections (including the later 357-359) reflect the wrapper design consistently.docs/research/control-plane-audit.md (1)
53-62:⚠️ Potential issue | 🟠 MajorNormalize API paths/methods to the canonical contract.
These tables still present unversioned/divergent routes (for example
/agents,/budget/...,/analytics/...). Please align them with the canonical/api/v1/...contract and exact method shapes used in the design/API docs so readers don’t get non-existent endpoints.Also applies to: 96-103, 161-167, 210-217
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/research/control-plane-audit.md` around lines 53 - 62, Update the API table entries to use the canonical versioned contract and exact method shapes from the design/API docs (replace unversioned routes like GET /agents, POST /agents, PUT /agents/{id}/autonomy, GET /departments, etc. with their /api/v1/... equivalents and exact parameter forms); locate the relevant table rows (entries showing routes such as GET /agents, GET /agents/{id}, POST /agents, PATCH /agents/{id}, DELETE /agents/{id}, GET /agents/{id}/autonomy, PUT /agents/{id}/autonomy, GET /departments, GET /departments/{name}/health) and change each path to the canonical /api/v1/... path and ensure HTTP methods and path parameter names match the API contract; apply the same normalization to the other table blocks noted in the comment (the duplicated blocks around the other line ranges) so all docs consistently reference the canonical API surface.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/design/engine.md`:
- Around line 1508-1511: Update the design doc to match the actual compaction
implementation: replace the referenced `_build_summary()` path in
`compaction/summarizer.py` with the real implementation location
`simple_strategy.py` (the consolidator that performs per-entry truncation), and
correct the behavior description to state that entries are truncated per-entry
(as implemented in the consolidator) rather than enforcing a 100-character
per-snippet and 500-character total hard cap; mention that no global total-cap
is applied and preserve any note about absence of LLM calls/semantic processing
if true. Ensure the doc text references the concrete function/class names found
in the implementation (e.g., the consolidator function in simple_strategy.py)
and follow the coding guideline by noting this approved deviation in the docs.
In `@docs/research/multi-agent-failure-audit.md`:
- Line 325: The phrase "reset at 5min, second at 10min, third at 20min" uses
compact time units—update these to spaced formats ("5 min", "10 min", "20 min")
for readability and consistency; scan the surrounding prose in the same
paragraph (the fragment containing "reset at 5min, second at 10min, third at
20min") and normalize any other occurrences of compact time units to the spaced
form throughout the document.
---
Duplicate comments:
In `@docs/research/acg-formalism-evaluation.md`:
- Around line 202-205: The document currently contradicts itself about how to
integrate attribution: choose and document one consistent approach (prefer the
wrapper pattern). Update all mentions to use the wrapper approach: describe
creating a new WrapperCoordinationResult (or similar) that contains a
CoordinationResult plus a list of AgentContribution populated by
infer_failure_category() per-agent, remove or replace the lines that say “extend
CoordinationResult with AgentContribution,” and ensure any examples and the
referenced sections (including the later 357-359) reflect the wrapper design
consistently.
In `@docs/research/control-plane-audit.md`:
- Around line 53-62: Update the API table entries to use the canonical versioned
contract and exact method shapes from the design/API docs (replace unversioned
routes like GET /agents, POST /agents, PUT /agents/{id}/autonomy, GET
/departments, etc. with their /api/v1/... equivalents and exact parameter
forms); locate the relevant table rows (entries showing routes such as GET
/agents, GET /agents/{id}, POST /agents, PATCH /agents/{id}, DELETE
/agents/{id}, GET /agents/{id}/autonomy, PUT /agents/{id}/autonomy, GET
/departments, GET /departments/{name}/health) and change each path to the
canonical /api/v1/... path and ensure HTTP methods and path parameter names
match the API contract; apply the same normalization to the other table blocks
noted in the comment (the duplicated blocks around the other line ranges) so all
docs consistently reference the canonical API surface.
🪄 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: 0845b70a-b389-46a5-adaa-06b1e5c68f7c
📒 Files selected for processing (6)
docs/design/communication.mddocs/design/engine.mddocs/research/acg-formalism-evaluation.mddocs/research/agent-controlled-compaction.mddocs/research/control-plane-audit.mddocs/research/multi-agent-failure-audit.md
📜 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). (2)
- GitHub Check: Dependency Review
- GitHub Check: Analyze (python)
🧰 Additional context used
📓 Path-based instructions (1)
docs/design/*.md
📄 CodeRabbit inference engine (CLAUDE.md)
When approved deviations occur, update the relevant
docs/design/page to reflect the new reality.
Files:
docs/design/communication.mddocs/design/engine.md
🧠 Learnings (24)
📓 Common learnings
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to docs/design/*.md : Design spec pages: 7 pages in `docs/design/` — index, agents, organization, communication, engine, memory, operations
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-16T06:24:56.341Z
Learning: Applies to docs/design/**/*.md : Design specification pages in `docs/design/` must be consulted before implementing features (7 pages: index, agents, organization, communication, engine, memory, operations)
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:13:44.964Z
Learning: Always read the relevant `docs/design/` page before implementing any feature or planning any issue — DESIGN_SPEC.md is a pointer file linking to 7 design pages (Agents, Organization, Communication, Engine, Memory, Operations)
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-14T15:43:05.601Z
Learning: Applies to docs/** : Docs source in docs/ (Markdown, built with Zensical); design spec in docs/design/ (7 pages: index, agents, organization, communication, engine, memory, operations)
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Engine: Agent orchestration, execution loops, parallel execution, task decomposition, routing, task assignment, centralized single-writer task state engine (TaskEngine), task lifecycle, recovery, shutdown, workspace isolation, coordination (multi-agent pipeline: TopologyDispatcher protocol, 4 dispatchers — SAS/centralized/decentralized/context-dependent, wave execution, workspace lifecycle integration, CoordinationSectionConfig company config bridge, build_coordinator factory), coordination error classification, prompt policy validation, checkpoint recovery (checkpoint/, per-turn persistence, heartbeat detection, CheckpointRecoveryStrategy), approval gate (escalation detection, context parking/resume, EscalationInfo/ResumePayload models), stagnation detection (stagnation/, StagnationDetector protocol, ToolRepetitionDetector, dual-signal analysis, corrective prompt injection), agent runtime state (AgentRuntimeState, lightweight per-agent execution status for dashboard queries and recove...
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T18:38:44.202Z
Learning: Always read the relevant `docs/design/` page before implementing any feature or planning any issue. DESIGN_SPEC.md is a pointer file linking to the 7 design pages (index, agents, organization, communication, engine, memory, operations).
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Documentation source in `docs/` (Markdown, built with Zensical). Design spec in `docs/design/` (7 pages: index, agents, organization, communication, engine, memory, operations). Architecture in `docs/architecture/` (overview, tech-stack, decision log). Roadmap in `docs/roadmap/`. Security in `docs/security.md`. Licensing in `docs/licensing.md`. Reference in `docs/reference/`. REST API reference in `docs/rest-api.md`. Library reference in `docs/api/` (auto-generated from docstrings). Custom templates in `docs/overrides/`. Config in `mkdocs.yml`.
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-07T16:48:04.262Z
Learning: See [DESIGN_SPEC.md](docs/DESIGN_SPEC.md) for the pointer to 12 design pages covering architecture, data models, and behavior.
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:28:28.895Z
Learning: Applies to docs/**/*.md : Documentation files in `docs/` (Markdown, built with Zensical, config: `mkdocs.yml`); design spec in `docs/design/` (11 pages)
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-07T16:48:04.262Z
Learning: Always read the relevant `docs/design/` page before implementing any feature or planning any issue. DESIGN_SPEC.md is a pointer file linking to the 12 design pages.
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to docs/design/*.md : Design spec pages: 7 pages in `docs/design/` — index, agents, organization, communication, engine, memory, operations
Applied to files:
docs/research/control-plane-audit.mddocs/design/communication.mddocs/design/engine.mddocs/research/agent-controlled-compaction.mddocs/research/acg-formalism-evaluation.md
📚 Learning: 2026-03-17T06:30:14.180Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T06:30:14.180Z
Learning: Applies to src/synthorg/security/**/*.py : Security module includes SecOps agent, rule engine (soft-allow/hard-deny), audit log, output scanner, risk classifier, autonomy levels (4 strategies), timeout policies.
Applied to files:
docs/research/control-plane-audit.mddocs/design/communication.md
📚 Learning: 2026-03-16T06:24:56.341Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-16T06:24:56.341Z
Learning: Applies to docs/design/**/*.md : Design specification pages in `docs/design/` must be consulted before implementing features (7 pages: index, agents, organization, communication, engine, memory, operations)
Applied to files:
docs/research/control-plane-audit.mddocs/design/communication.mddocs/design/engine.mddocs/research/multi-agent-failure-audit.mddocs/research/agent-controlled-compaction.mddocs/research/acg-formalism-evaluation.md
📚 Learning: 2026-03-18T08:23:08.912Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-18T08:23:08.912Z
Learning: When approved deviations occur, update the relevant `docs/design/` page to reflect the new reality.
Applied to files:
docs/research/control-plane-audit.md
📚 Learning: 2026-03-17T22:08:13.456Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Budget: Cost tracking, budget enforcement (pre-flight/in-flight checks, auto-downgrade), billing periods, cost tiers, quota/subscription tracking, CFO cost optimization (anomaly detection, efficiency analysis, downgrade recommendations, approval decisions), spending reports, budget errors (BudgetExhaustedError, DailyLimitExceededError, QuotaExhaustedError).
Applied to files:
docs/research/control-plane-audit.md
📚 Learning: 2026-03-19T07:13:44.964Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:13:44.964Z
Learning: Applies to src/synthorg/budget/**/*.py : Budget package (budget/): cost tracking, budget enforcement (pre-flight/in-flight checks, auto-downgrade), billing periods, cost tiers, quota/subscription tracking, CFO cost optimization (anomaly detection, efficiency analysis, downgrade recommendations, approval decisions), spending reports, budget errors (BudgetExhaustedError, DailyLimitExceededError, QuotaExhaustedError)
Applied to files:
docs/research/control-plane-audit.md
📚 Learning: 2026-03-17T06:30:14.180Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T06:30:14.180Z
Learning: Applies to src/synthorg/budget/**/*.py : Budget tracking includes pre-flight/in-flight checks, auto-downgrade, billing periods, cost tiers, quota/subscription. CFO includes anomaly detection, efficiency analysis, downgrade recommendations.
Applied to files:
docs/research/control-plane-audit.md
📚 Learning: 2026-03-17T22:08:13.456Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Security: SecOps agent, rule engine (soft-allow/hard-deny, fail-closed), audit log, output scanner, output scan response policies (redact/withhold/log-only/autonomy-tiered), risk classifier, risk tier classifier, action type registry, ToolInvoker security integration, progressive trust (4 strategies: disabled/weighted/per-category/milestone), autonomy levels (presets, resolver, change strategy), timeout policies (park/resume).
Applied to files:
docs/research/control-plane-audit.mddocs/design/communication.mddocs/research/multi-agent-failure-audit.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to src/synthorg/security/**/*.py : Security package (security/): SecOps agent, rule engine (soft-allow/hard-deny, fail-closed), audit log, output scanner, output scan response policies (redact/withhold/log-only/autonomy-tiered), risk classifier, risk tier classifier, action type registry, ToolInvoker security integration, progressive trust (4 strategies), autonomy levels (presets, resolver, change strategy), timeout policies (park/resume)
Applied to files:
docs/research/control-plane-audit.mddocs/design/communication.md
📚 Learning: 2026-03-19T07:13:44.964Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:13:44.964Z
Learning: Always read the relevant `docs/design/` page before implementing any feature or planning any issue — DESIGN_SPEC.md is a pointer file linking to 7 design pages (Agents, Organization, Communication, Engine, Memory, Operations)
Applied to files:
docs/design/communication.mddocs/design/engine.mddocs/research/agent-controlled-compaction.mddocs/research/acg-formalism-evaluation.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to src/synthorg/communication/**/*.py : Communication package (communication/): message bus, dispatcher, messenger, channels, delegation, loop prevention, conflict resolution; meeting/ subpackage for meeting protocol (round-robin, position papers, structured phases), scheduler (frequency, participant resolver), orchestrator
Applied to files:
docs/design/communication.md
📚 Learning: 2026-03-15T18:38:44.202Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T18:38:44.202Z
Learning: Always read the relevant `docs/design/` page before implementing any feature or planning any issue. DESIGN_SPEC.md is a pointer file linking to the 7 design pages (index, agents, organization, communication, engine, memory, operations).
Applied to files:
docs/design/communication.mddocs/design/engine.md
📚 Learning: 2026-03-14T15:43:05.601Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-14T15:43:05.601Z
Learning: Applies to docs/** : Docs source in docs/ (Markdown, built with Zensical); design spec in docs/design/ (7 pages: index, agents, organization, communication, engine, memory, operations)
Applied to files:
docs/design/communication.mddocs/design/engine.mddocs/research/agent-controlled-compaction.mddocs/research/acg-formalism-evaluation.md
📚 Learning: 2026-03-17T22:08:13.456Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Engine: Agent orchestration, execution loops, parallel execution, task decomposition, routing, task assignment, centralized single-writer task state engine (TaskEngine), task lifecycle, recovery, shutdown, workspace isolation, coordination (multi-agent pipeline: TopologyDispatcher protocol, 4 dispatchers — SAS/centralized/decentralized/context-dependent, wave execution, workspace lifecycle integration, CoordinationSectionConfig company config bridge, build_coordinator factory), coordination error classification, prompt policy validation, checkpoint recovery (checkpoint/, per-turn persistence, heartbeat detection, CheckpointRecoveryStrategy), approval gate (escalation detection, context parking/resume, EscalationInfo/ResumePayload models), stagnation detection (stagnation/, StagnationDetector protocol, ToolRepetitionDetector, dual-signal analysis, corrective prompt injection), agent runtime state (AgentRuntimeState, lightweight per-agent execution status for dashboard queries and recove...
Applied to files:
docs/design/communication.mddocs/design/engine.md
📚 Learning: 2026-04-06T16:35:12.934Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-04-06T16:35:12.934Z
Learning: Agents in the Parallel tier (Haiku-class) include 14 reviewers: async-concurrency-reviewer, comment-analyzer, design-token-audit, docs-consistency, go-conventions-enforcer, go-security-reviewer, infra-reviewer, issue-resolution-verifier, persistence-reviewer, pr-test-analyzer, security-reviewer, silent-failure-hunter, test-quality-reviewer, and type-design-analyzer
Applied to files:
docs/design/communication.md
📚 Learning: 2026-03-17T22:08:13.456Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Documentation source in `docs/` (Markdown, built with Zensical). Design spec in `docs/design/` (7 pages: index, agents, organization, communication, engine, memory, operations). Architecture in `docs/architecture/` (overview, tech-stack, decision log). Roadmap in `docs/roadmap/`. Security in `docs/security.md`. Licensing in `docs/licensing.md`. Reference in `docs/reference/`. REST API reference in `docs/rest-api.md`. Library reference in `docs/api/` (auto-generated from docstrings). Custom templates in `docs/overrides/`. Config in `mkdocs.yml`.
Applied to files:
docs/design/communication.mddocs/design/engine.md
📚 Learning: 2026-03-17T06:30:14.180Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T06:30:14.180Z
Learning: Applies to src/synthorg/engine/coordination/**/*.py : Task coordination uses multi-agent pipeline with 4 dispatchers (SAS/centralized/decentralized/context-dependent), wave execution, and workspace lifecycle integration.
Applied to files:
docs/design/communication.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to src/synthorg/engine/**/*.py : Engine package (engine/): agent orchestration, parallel execution, task decomposition, routing, TaskEngine (centralized single-writer), task lifecycle/recovery/shutdown, workspace isolation, coordination (4 dispatchers: SAS/centralized/decentralized/context-dependent, wave execution), approval gates (escalation detection, context parking/resume), stagnation detection (ToolRepetitionDetector, corrective prompt injection), AgentRuntimeState (execution status), context budget management, conversation compaction (oldest-turns summarizer)
Applied to files:
docs/design/engine.md
📚 Learning: 2026-04-07T16:48:04.262Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-07T16:48:04.262Z
Learning: Applies to src/**/*.py : For `dict`/`list` fields in frozen Pydantic models, rely on `frozen=True` for field reassignment prevention and `copy.deepcopy()` at system boundaries (tool execution, LLM provider serialization, inter-agent delegation, serializing for persistence).
Applied to files:
docs/research/acg-formalism-evaluation.md
📚 Learning: 2026-03-15T19:14:27.144Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T19:14:27.144Z
Learning: Applies to src/synthorg/**/*.py : For dict/list fields in frozen Pydantic models, rely on frozen=True for field reassignment prevention and copy.deepcopy() at system boundaries (tool execution, LLM provider serialization, inter-agent delegation, serializing for persistence).
Applied to files:
docs/research/acg-formalism-evaluation.md
📚 Learning: 2026-03-16T23:05:29.577Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-16T23:05:29.577Z
Learning: Applies to **/*.py : For dict/list fields in frozen Pydantic models, rely on frozen=True for field reassignment prevention and copy.deepcopy() at system boundaries (tool execution, LLM provider serialization, inter-agent delegation, serializing for persistence).
Applied to files:
docs/research/acg-formalism-evaluation.md
📚 Learning: 2026-03-15T19:14:27.144Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T19:14:27.144Z
Learning: Applies to src/synthorg/**/*.py : Use frozen Pydantic models for config/identity; use separate mutable-via-copy models (using model_copy(update=...)) for runtime state that evolves. Never mix static config fields with mutable runtime fields in one model.
Applied to files:
docs/research/acg-formalism-evaluation.md
📚 Learning: 2026-04-07T16:48:04.262Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-07T16:48:04.262Z
Learning: Applies to src/**/*.py : Use frozen Pydantic models for config/identity; use separate mutable-via-copy models (using `model_copy(update=...)`) for runtime state that evolves. Never mix static config fields with mutable runtime fields in one model.
Applied to files:
docs/research/acg-formalism-evaluation.md
🪛 LanguageTool
docs/research/control-plane-audit.md
[style] ~280-~280: To elevate your writing, try using a synonym here.
Context: ...rades. This integration is genuine and hard to replicate by composing separate tool...
(HARD_TO)
docs/research/multi-agent-failure-audit.md
[grammar] ~325-~325: Ensure spelling is correct
Context: ...uit breaker reset (e.g., first reset at 5min, second at 10min, third at 20min) or a ...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~325-~325: Ensure spelling is correct
Context: ...t (e.g., first reset at 5min, second at 10min, third at 20min) or a global per-pair b...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[grammar] ~325-~325: Ensure spelling is correct
Context: ...eset at 5min, second at 10min, third at 20min) or a global per-pair bounce counter th...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🪛 markdownlint-cli2 (0.22.0)
docs/research/agent-controlled-compaction.md
[warning] 37-37: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 45-45: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 63-63: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 78-78: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 346-346: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
🔇 Additional comments (2)
docs/design/communication.md (1)
451-521: Good addition: guardrails section is concrete and actionable.The new failure-pattern section is clear, bounded, and aligned with the current architecture and known risks.
docs/research/agent-controlled-compaction.md (1)
53-55:⚠️ Potential issue | 🔴 CriticalFix invalid Python 2 exception syntax in
invoke_compaction()exception handler.Line 680 in
src/synthorg/engine/loop_helpers.pyusesexcept MemoryError, RecursionError:, which is Python 2 syntax. Python 3 requiresexcept (MemoryError, RecursionError):with parentheses. This syntax error prevents the module from being imported and must be corrected. The doc assertion about re-raising these exceptions is correct per the function docstring, but the implementation syntax is broken.⛔ Skipped due to learnings
Learnt from: CR Repo: Aureliolo/synthorg PR: 0 File: CLAUDE.md:0-0 Timestamp: 2026-03-20T11:18:48.128Z Learning: Applies to src/synthorg/**/*.py : Retryable errors (`is_retryable=True`): `RateLimitError`, `ProviderTimeoutError`, `ProviderConnectionError`, `ProviderInternalError`. Non-retryable errors raise immediately without retry.Learnt from: CR Repo: Aureliolo/synthorg PR: 0 File: CLAUDE.md:0-0 Timestamp: 2026-03-15T16:55:07.730Z Learning: Applies to src/synthorg/**/*.py : All error paths must log at WARNING or ERROR with context before raising.Learnt from: CR Repo: Aureliolo/synthorg PR: 0 File: CLAUDE.md:0-0 Timestamp: 2026-03-19T11:33:01.580Z Learning: Applies to src/synthorg/**/*.py : Log all error paths at WARNING or ERROR with context before raising; log all state transitions at INFO; log object creation/internal flow/entry-exit at DEBUGLearnt from: CR Repo: Aureliolo/synthorg PR: 0 File: CLAUDE.md:0-0 Timestamp: 2026-04-01T17:49:14.133Z Learning: Applies to src/synthorg/{providers,engine}/**/*.py : Retryable errors are `RateLimitError`, `ProviderTimeoutError`, `ProviderConnectionError`, `ProviderInternalError`; non-retryable errors raise immediately; `RetryExhaustedError` signals all retries failedLearnt from: CR Repo: Aureliolo/synthorg PR: 0 File: CLAUDE.md:0-0 Timestamp: 2026-03-16T07:22:28.134Z Learning: Applies to src/synthorg/**/*.py : All error paths must log at WARNING or ERROR with context before raising. All state transitions must log at INFO. DEBUG for object creation, internal flow, and key function entry/exitLearnt from: CR Repo: Aureliolo/synthorg PR: 0 File: CLAUDE.md:0-0 Timestamp: 2026-03-31T20:07:03.035Z Learning: Applies to src/synthorg/**/*.py : All error paths must log at WARNING or ERROR with context before raising; all state transitions must log at INFO; DEBUG for object creation, internal flow, entry/exit of key functionsLearnt from: CR Repo: Aureliolo/synthorg PR: 0 File: CLAUDE.md:0-0 Timestamp: 2026-03-19T07:12:14.508Z Learning: Applies to src/synthorg/**/*.py : All error paths must log at WARNING or ERROR with context before raisingLearnt from: CR Repo: Aureliolo/synthorg PR: 0 File: CLAUDE.md:0-0 Timestamp: 2026-03-15T18:38:44.202Z Learning: Applies to src/synthorg/**/*.py : All error paths must log at WARNING or ERROR with context before raisingLearnt from: CR Repo: Aureliolo/synthorg PR: 0 File: CLAUDE.md:0-0 Timestamp: 2026-03-16T06:24:56.341Z Learning: Applies to src/synthorg/**/*.py : All error paths must log at WARNING or ERROR with context before raisingLearnt from: CR Repo: Aureliolo/synthorg PR: 0 File: CLAUDE.md:0-0 Timestamp: 2026-03-17T22:08:13.456Z Learning: Applies to src/synthorg/**/*.py : Handle errors explicitly, never silently swallow. Validate at system boundaries (user input, external APIs, config files).Learnt from: CR Repo: Aureliolo/synthorg PR: 0 File: CLAUDE.md:0-0 Timestamp: 2026-03-31T21:07:37.470Z Learning: Applies to **/*.py : Use `except A, B:` (no parentheses) per PEP 758 exception syntax on Python 3.14Learnt from: CR Repo: Aureliolo/synthorg PR: 0 File: CLAUDE.md:0-0 Timestamp: 2026-04-07T16:48:04.262Z Learning: Applies to **/*.py : Use `except A, B:` (no parentheses) instead of `except (A, B):` for multiple exceptions—PEP 758 except syntax enforced by ruff on Python 3.14.Learnt from: CR Repo: Aureliolo/synthorg PR: 0 File: CLAUDE.md:0-0 Timestamp: 2026-03-16T07:22:28.134Z Learning: Applies to **/*.py : Use `except A, B:` syntax (no parentheses) for exception handling — PEP 758 exception syntax enforced by ruff on Python 3.14Learnt from: CR Repo: Aureliolo/synthorg PR: 0 File: CLAUDE.md:0-0 Timestamp: 2026-03-20T21:44:04.528Z Learning: Applies to **/*.py : Use `except A, B:` syntax (without parentheses) per PEP 758 for exception handling in Python 3.14Learnt from: CR Repo: Aureliolo/synthorg PR: 0 File: CLAUDE.md:0-0 Timestamp: 2026-03-14T16:18:57.267Z Learning: Applies to **/*.py : Use PEP 758 except syntax with `except A, B:` (no parentheses) for multiple exceptions—ruff enforces this on Python 3.14.Learnt from: CR Repo: Aureliolo/synthorg PR: 0 File: CLAUDE.md:0-0 Timestamp: 2026-03-14T15:43:05.601Z Learning: Applies to **/*.py : Use PEP 758 except syntax: `except A, B:` (no parentheses) — enforced by ruff on Python 3.14Learnt from: CR Repo: Aureliolo/synthorg PR: 0 File: CLAUDE.md:0-0 Timestamp: 2026-03-15T16:55:07.730Z Learning: Applies to **/*.py : Use PEP 758 except syntax: use `except A, B:` (no parentheses) — ruff enforces this on Python 3.14.Learnt from: CR Repo: Aureliolo/synthorg PR: 0 File: CLAUDE.md:0-0 Timestamp: 2026-03-14T16:18:57.267Z Learning: Applies to **/*.py : Handle errors explicitly—never silently swallow exceptions.
Comment on lines
+1508
to
+1511
| The current `_build_summary()` in `compaction/summarizer.py` performs simple text | ||
| concatenation: assistant message snippets capped at 100 characters each, total summary | ||
| capped at 500 characters. No LLM calls, no semantic awareness, no preservation of | ||
| reasoning artifacts. |
There was a problem hiding this comment.
Compaction implementation details appear mismatched with the referenced code.
This section states _build_summary() in compaction/summarizer.py enforces 100-char snippets and a 500-char total cap, but the provided implementation evidence (src/synthorg/memory/consolidation/simple_strategy.py:159-181) shows per-entry truncation and no hard total cap. Please align the doc’s function path and limits to the actual implementation to avoid incorrect design guidance.
As per coding guidelines, “When approved deviations occur, update the relevant docs/design/ page to reflect the new reality.”
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/design/engine.md` around lines 1508 - 1511, Update the design doc to
match the actual compaction implementation: replace the referenced
`_build_summary()` path in `compaction/summarizer.py` with the real
implementation location `simple_strategy.py` (the consolidator that performs
per-entry truncation), and correct the behavior description to state that
entries are truncated per-entry (as implemented in the consolidator) rather than
enforcing a 100-character per-snippet and 500-character total hard cap; mention
that no global total-cap is applied and preserve any note about absence of LLM
calls/semantic processing if true. Ensure the doc text references the concrete
function/class names found in the implementation (e.g., the consolidator
function in simple_strategy.py) and follow the coding guideline by noting this
approved deviation in the docs.
- acg-formalism-evaluation.md: align Summary of Recommendations with Proposed Design -- replace "Extend CoordinationResult" with CoordinationResultWithAttribution wrapper approach to eliminate contradiction introduced in previous commit - multi-agent-failure-audit.md: fix spacing in time values (5min/10min/20min -> 5 min/10 min/20 min) engine.md:1508-1511 verified correct: _build_summary() is in compaction/summarizer.py with 100-char snippet cap and 500-char total cap exactly as documented; CodeRabbit's simple_strategy.py reference points to the unrelated memory consolidation module.
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
docs/research/acg-formalism-evaluation.md (1)
202-205:⚠️ Potential issue | 🟠 MajorResolve contradiction with the frozen-model integration approach.
Lines 202-205 reintroduce “extend
CoordinationResult,” which conflicts with Lines 167-172 recommendingCoordinationResultWithAttributionto preserve immutability. Keep one canonical path (wrapper) to avoid implementers choosing a breaking change.📝 Proposed doc fix
-**Scope note**: This is a research recommendation, not an implementation spec. The -minimum viable version extends `CoordinationResult` with a list of `AgentContribution` -objects populated by the existing keyword-heuristic from `infer_failure_category()` applied -per-agent subtask result. +**Scope note**: This is a research recommendation, not an implementation spec. The +minimum viable version should keep `CoordinationResult` unchanged and return a +`CoordinationResultWithAttribution` wrapper containing `agent_contributions` +populated by the existing keyword-heuristic from `infer_failure_category()` applied +per-agent subtask result.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/research/acg-formalism-evaluation.md` around lines 202 - 205, The doc currently contradicts itself by later suggesting to extend CoordinationResult; instead, keep the immutable-wrapper approach: remove or replace the lines proposing to "extend CoordinationResult" and explicitly state that attribution is provided via a separate CoordinationResultWithAttribution wrapper that contains a list of AgentContribution entries populated per-agent using the existing infer_failure_category() heuristic, so implementers do not change the original CoordinationResult type and immutability is preserved.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/research/multi-agent-failure-audit.md`:
- Around line 76-77: Update the documentation to reference the actual
orchestrator method name for traceability: replace the incorrect
`MeetingOrchestrator._create_tasks()` mention with the implemented method
`MeetingOrchestrator._perform_auto_create_tasks` (the method that spawns Task
objects from action items), so readers and code search will resolve to the real
implementation.
---
Duplicate comments:
In `@docs/research/acg-formalism-evaluation.md`:
- Around line 202-205: The doc currently contradicts itself by later suggesting
to extend CoordinationResult; instead, keep the immutable-wrapper approach:
remove or replace the lines proposing to "extend CoordinationResult" and
explicitly state that attribution is provided via a separate
CoordinationResultWithAttribution wrapper that contains a list of
AgentContribution entries populated per-agent using the existing
infer_failure_category() heuristic, so implementers do not change the original
CoordinationResult type and immutability is preserved.
🪄 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: 4e48eee3-605f-43d0-986e-2e8db1d4ad48
📒 Files selected for processing (2)
docs/research/acg-formalism-evaluation.mddocs/research/multi-agent-failure-audit.md
📜 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). (3)
- GitHub Check: Deploy Preview
- GitHub Check: Dependency Review
- GitHub Check: Analyze (python)
🧰 Additional context used
🧠 Learnings (14)
📓 Common learnings
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to docs/design/*.md : Design spec pages: 7 pages in `docs/design/` — index, agents, organization, communication, engine, memory, operations
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-16T06:24:56.341Z
Learning: Applies to docs/design/**/*.md : Design specification pages in `docs/design/` must be consulted before implementing features (7 pages: index, agents, organization, communication, engine, memory, operations)
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:13:44.964Z
Learning: Always read the relevant `docs/design/` page before implementing any feature or planning any issue — DESIGN_SPEC.md is a pointer file linking to 7 design pages (Agents, Organization, Communication, Engine, Memory, Operations)
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-14T15:43:05.601Z
Learning: Applies to docs/** : Docs source in docs/ (Markdown, built with Zensical); design spec in docs/design/ (7 pages: index, agents, organization, communication, engine, memory, operations)
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Engine: Agent orchestration, execution loops, parallel execution, task decomposition, routing, task assignment, centralized single-writer task state engine (TaskEngine), task lifecycle, recovery, shutdown, workspace isolation, coordination (multi-agent pipeline: TopologyDispatcher protocol, 4 dispatchers — SAS/centralized/decentralized/context-dependent, wave execution, workspace lifecycle integration, CoordinationSectionConfig company config bridge, build_coordinator factory), coordination error classification, prompt policy validation, checkpoint recovery (checkpoint/, per-turn persistence, heartbeat detection, CheckpointRecoveryStrategy), approval gate (escalation detection, context parking/resume, EscalationInfo/ResumePayload models), stagnation detection (stagnation/, StagnationDetector protocol, ToolRepetitionDetector, dual-signal analysis, corrective prompt injection), agent runtime state (AgentRuntimeState, lightweight per-agent execution status for dashboard queries and recove...
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T18:38:44.202Z
Learning: Always read the relevant `docs/design/` page before implementing any feature or planning any issue. DESIGN_SPEC.md is a pointer file linking to the 7 design pages (index, agents, organization, communication, engine, memory, operations).
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Documentation source in `docs/` (Markdown, built with Zensical). Design spec in `docs/design/` (7 pages: index, agents, organization, communication, engine, memory, operations). Architecture in `docs/architecture/` (overview, tech-stack, decision log). Roadmap in `docs/roadmap/`. Security in `docs/security.md`. Licensing in `docs/licensing.md`. Reference in `docs/reference/`. REST API reference in `docs/rest-api.md`. Library reference in `docs/api/` (auto-generated from docstrings). Custom templates in `docs/overrides/`. Config in `mkdocs.yml`.
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-07T16:48:04.262Z
Learning: See [DESIGN_SPEC.md](docs/DESIGN_SPEC.md) for the pointer to 12 design pages covering architecture, data models, and behavior.
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-31T14:28:28.895Z
Learning: Applies to docs/**/*.md : Documentation files in `docs/` (Markdown, built with Zensical, config: `mkdocs.yml`); design spec in `docs/design/` (11 pages)
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-07T16:48:04.262Z
Learning: Always read the relevant `docs/design/` page before implementing any feature or planning any issue. DESIGN_SPEC.md is a pointer file linking to the 12 design pages.
📚 Learning: 2026-03-16T06:24:56.341Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-16T06:24:56.341Z
Learning: Applies to docs/design/**/*.md : Design specification pages in `docs/design/` must be consulted before implementing features (7 pages: index, agents, organization, communication, engine, memory, operations)
Applied to files:
docs/research/multi-agent-failure-audit.mddocs/research/acg-formalism-evaluation.md
📚 Learning: 2026-03-17T06:30:14.180Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T06:30:14.180Z
Learning: Applies to src/synthorg/security/**/*.py : Security module includes SecOps agent, rule engine (soft-allow/hard-deny), audit log, output scanner, risk classifier, autonomy levels (4 strategies), timeout policies.
Applied to files:
docs/research/multi-agent-failure-audit.md
📚 Learning: 2026-03-19T07:12:14.508Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:12:14.508Z
Learning: Applies to docs/design/*.md : Design spec pages: 7 pages in `docs/design/` — index, agents, organization, communication, engine, memory, operations
Applied to files:
docs/research/multi-agent-failure-audit.mddocs/research/acg-formalism-evaluation.md
📚 Learning: 2026-03-17T22:08:13.456Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-17T22:08:13.456Z
Learning: Security: SecOps agent, rule engine (soft-allow/hard-deny, fail-closed), audit log, output scanner, output scan response policies (redact/withhold/log-only/autonomy-tiered), risk classifier, risk tier classifier, action type registry, ToolInvoker security integration, progressive trust (4 strategies: disabled/weighted/per-category/milestone), autonomy levels (presets, resolver, change strategy), timeout policies (park/resume).
Applied to files:
docs/research/multi-agent-failure-audit.md
📚 Learning: 2026-03-19T07:13:44.964Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-19T07:13:44.964Z
Learning: Always read the relevant `docs/design/` page before implementing any feature or planning any issue — DESIGN_SPEC.md is a pointer file linking to 7 design pages (Agents, Organization, Communication, Engine, Memory, Operations)
Applied to files:
docs/research/acg-formalism-evaluation.md
📚 Learning: 2026-03-14T15:43:05.601Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-14T15:43:05.601Z
Learning: Applies to docs/** : Docs source in docs/ (Markdown, built with Zensical); design spec in docs/design/ (7 pages: index, agents, organization, communication, engine, memory, operations)
Applied to files:
docs/research/acg-formalism-evaluation.md
📚 Learning: 2026-03-15T18:38:44.202Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T18:38:44.202Z
Learning: Always read the relevant `docs/design/` page before implementing any feature or planning any issue. DESIGN_SPEC.md is a pointer file linking to the 7 design pages (index, agents, organization, communication, engine, memory, operations).
Applied to files:
docs/research/acg-formalism-evaluation.md
📚 Learning: 2026-04-07T16:48:04.262Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-07T16:48:04.262Z
Learning: Applies to src/**/*.py : For `dict`/`list` fields in frozen Pydantic models, rely on `frozen=True` for field reassignment prevention and `copy.deepcopy()` at system boundaries (tool execution, LLM provider serialization, inter-agent delegation, serializing for persistence).
Applied to files:
docs/research/acg-formalism-evaluation.md
📚 Learning: 2026-03-15T19:14:27.144Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T19:14:27.144Z
Learning: Applies to src/synthorg/**/*.py : For dict/list fields in frozen Pydantic models, rely on frozen=True for field reassignment prevention and copy.deepcopy() at system boundaries (tool execution, LLM provider serialization, inter-agent delegation, serializing for persistence).
Applied to files:
docs/research/acg-formalism-evaluation.md
📚 Learning: 2026-03-15T19:14:27.144Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T19:14:27.144Z
Learning: Applies to src/synthorg/**/*.py : Use frozen Pydantic models for config/identity; use separate mutable-via-copy models (using model_copy(update=...)) for runtime state that evolves. Never mix static config fields with mutable runtime fields in one model.
Applied to files:
docs/research/acg-formalism-evaluation.md
📚 Learning: 2026-03-16T23:05:29.577Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-16T23:05:29.577Z
Learning: Applies to **/*.py : For dict/list fields in frozen Pydantic models, rely on frozen=True for field reassignment prevention and copy.deepcopy() at system boundaries (tool execution, LLM provider serialization, inter-agent delegation, serializing for persistence).
Applied to files:
docs/research/acg-formalism-evaluation.md
📚 Learning: 2026-04-07T16:48:04.262Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-04-07T16:48:04.262Z
Learning: Applies to src/**/*.py : Use frozen Pydantic models for config/identity; use separate mutable-via-copy models (using `model_copy(update=...)`) for runtime state that evolves. Never mix static config fields with mutable runtime fields in one model.
Applied to files:
docs/research/acg-formalism-evaluation.md
📚 Learning: 2026-03-15T21:49:53.264Z
Learnt from: CR
Repo: Aureliolo/synthorg PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-03-15T21:49:53.264Z
Learning: Fix everything valid — never skip when review agents find valid issues (including pre-existing issues in surrounding code, suggestions, and findings adjacent to the PR's changes). No deferring, no 'out of scope' skipping.
Applied to files:
docs/research/acg-formalism-evaluation.md
Comment on lines
+76
to
+77
| `MeetingOrchestrator._create_tasks()` spawns `Task` objects from action items extracted | ||
| from meeting minutes. These tasks can be assigned to agents who execute them. If task |
There was a problem hiding this comment.
Use the actual orchestrator method name for traceability.
The method cited here is MeetingOrchestrator._create_tasks(), but the implementation is _perform_auto_create_tasks (src/synthorg/communication/meeting/orchestrator.py:313-360). Updating the symbol avoids dead-end code navigation.
📝 Proposed doc fix
-`MeetingProtocolConfig.auto_create_tasks` defaults to `True`. When enabled,
-`MeetingOrchestrator._create_tasks()` spawns `Task` objects from action items extracted
+`MeetingProtocolConfig.auto_create_tasks` defaults to `True`. When enabled,
+`MeetingOrchestrator._perform_auto_create_tasks()` spawns `Task` objects from action items extracted📝 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
| `MeetingOrchestrator._create_tasks()` spawns `Task` objects from action items extracted | |
| from meeting minutes. These tasks can be assigned to agents who execute them. If task | |
| `MeetingOrchestrator._perform_auto_create_tasks()` spawns `Task` objects from action items extracted | |
| from meeting minutes. These tasks can be assigned to agents who execute them. If task |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/research/multi-agent-failure-audit.md` around lines 76 - 77, Update the
documentation to reference the actual orchestrator method name for traceability:
replace the incorrect `MeetingOrchestrator._create_tasks()` mention with the
implemented method `MeetingOrchestrator._perform_auto_create_tasks` (the method
that spawns Task objects from action items), so readers and code search will
resolve to the real implementation.
The scope note at line 202 still said "extends CoordinationResult" after the Proposed Design and Summary sections were updated to use the CoordinationResultWithAttribution wrapper. Align it with the rest of the document so all three sections consistently recommend the wrapper approach. Finding about MeetingOrchestrator._perform_auto_create_tasks verified invalid: actual method is _create_tasks (orchestrator.py:313).
Aureliolo
added a commit
that referenced
this pull request
Apr 7, 2026
🤖 I have created a release *beep* *boop* --- ## [0.6.4](v0.6.3...v0.6.4) (2026-04-07) ### Features * analytics and metrics runtime pipeline ([#226](#226), [#225](#225), [#227](#227), [#224](#224)) ([#1127](#1127)) ([ec57641](ec57641)) * engine intelligence -- quality signals, health monitoring, trajectory scoring, coordination metrics ([#1099](#1099)) ([aac2029](aac2029)), closes [#697](#697) [#707](#707) [#705](#705) [#703](#703) * enterprise-grade auth -- HttpOnly cookie sessions, CSRF, lockout, session limits ([#1102](#1102)) ([d3022c7](d3022c7)), closes [#1068](#1068) * implement core tool categories and granular sub-constraints ([#1101](#1101)) ([0611b53](0611b53)), closes [#1034](#1034) [#220](#220) * memory evolution -- GraphRAG/consistency research + SelfEditingMemoryStrategy ([#1036](#1036), [#208](#208)) ([#1129](#1129)) ([a9acda3](a9acda3)) * security hardening -- sandbox, risk override, SSRF self-heal, DAST fix ([#1100](#1100)) ([31e7273](31e7273)), closes [#1098](#1098) [#696](#696) [#222](#222) [#671](#671) ### Bug Fixes * harden agent identity versioning post-review ([#1128](#1128)) ([8eb2859](8eb2859)), closes [#1076](#1076) ### Documentation * engine architecture research ([#688](#688) [#690](#690) [#848](#848) [#687](#687)) ([#1114](#1114)) ([59b31f9](59b31f9)) ### Maintenance * add .claudeignore and split CLAUDE.md for token optimization ([#1112](#1112)) ([b0fbd18](b0fbd18)) * bump github.com/sigstore/protobuf-specs from 0.5.0 to 0.5.1 in /cli in the all group ([#1106](#1106)) ([73089c9](73089c9)) * bump jsdom from 29.0.1 to 29.0.2 in /site in the all group ([#1107](#1107)) ([8e99dce](8e99dce)) * bump jsdom from 29.0.1 to 29.0.2 in /web in the all group ([#1108](#1108)) ([ce8c749](ce8c749)) * bump python from `fb83750` to `6869258` in /docker/backend in the all group ([#1104](#1104)) ([4911726](4911726)) * bump python from `fb83750` to `6869258` in /docker/web in the all group ([#1103](#1103)) ([87bdf09](87bdf09)) * bump the all group across 1 directory with 4 updates ([#1111](#1111)) ([f702464](f702464)) * bump the all group in /docker/sandbox with 2 updates ([#1105](#1105)) ([05a91ca](05a91ca)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Engine architecture research covering four issues in the planned dependency order (#688 + #690 in parallel, then #848 building on #690, then #687 standalone). Pure research output -- no code changes.
Deliverables:
docs/research/docs/design/#688 -- API Surface as Control-Plane Architecture
docs/research/control-plane-audit.md+docs/design/operations.mdMaps SynthOrg's modules (HR, security, budget, observability) to control-plane primitives and audits the gap between internal capability and external API surface. Key findings:
/metricsor OTLP export -- blocks enterprise monitoring integrationGET /agents/{id}/healthendpoint -- performance data exists inhr/performance/tracker.pybut is only exposed at department levelValidates "write once, enforce everywhere" with one documented constraint:
SecOpsServicetakes config at construction -- policy changes apply to new sessions, not active ones.#690 -- Multi-Agent Failure Pattern Audit
docs/research/multi-agent-failure-audit.md+docs/design/communication.mdAudits all meeting protocols, conflict resolution strategies, and delegation guard mechanisms against CIO/Medium failure mode research. Key findings:
auto_create_tasks=Truedefault +trigger_event()has no deduplication. Recommendation: addmin_interval_secondstoMeetingTypeConfig.del self._pairs[key]atcircuit_breaker.py:114) -- slow-burn delegation vulnerability. Recommendation: exponential backoff on reset.HumanEscalationResolveris a stub pending Implement human approval queue API (Litestar controller + guards) #37 -- conflicts requiring human judgment are silently unresolved.#848 -- ACG Formalism Adoption
docs/research/acg-formalism-evaluation.md+docs/design/engine.mdMaps SynthOrg's engine to ACG vocabulary (arXiv:2603.22386). Strong coverage of realized graph, execution trace, parallel composition, resource constraints, termination conditions, and node cost. Partial coverage of node typing and conditional branching. Recommends bidirectional glossary (not a full code refactor).
Also covers:
AgentContributionmodel with topological failure attribution -- currentinfer_failure_category()is keyword-based per-execution with no per-agent attribution in multi-agent pipelinesOffboardingService,FiringReason.PERFORMANCE) but no automated trigger -- proposesPruningEvaluationmodel with Jaccard skill overlap and Theil-Sen quality trend signals#687 -- Agent-Controlled Compaction
docs/research/agent-controlled-compaction.md+docs/design/engine.mdEvaluates replacing fixed-threshold compaction with agent-guided compaction. Key findings:
_build_summary()is simple concatenation (100 chars/snippet, 500 chars total) -- no semantic awarenesscompress_contexttool using "compaction directive" metadata pattern to preserve immutableAgentContextarchitectureTest Plan
Research-only -- no code changes. No tests required.
Docs build:
uv run zensical build(not run locally as docs build requiresuv sync --group docsand is validated in CI).Review Coverage
Quick mode (docs-only changes). Automated checks skipped (no Python/Go/web files changed).
Closes #688
Closes #690
Closes #848
Closes #687