DoctorContractProtocol for runtime config migration

[MervinPraison]

Problem

Migrating from agent-level cli_backend to model-scoped runtime requires repeatable, plugin-extensible doctor rules so legacy configs are detected and rewritten safely.

Current state

• Legacy field cli_backend in YAML and Python (praisonai/agents_generator.py, praisonai/agent.py, praisonaiagents/agent/agent.py).
• Doctor infrastructure in praisonai/cli/commands/doctor.py without a DoctorContractProtocol for third-party migration rules.
• Deploy doctor helpers in praisonai/deploy/doctor.py are deployment-focused, not agent runtime schema.

Proposed design

• Add DoctorContractProtocol in praisonaiagents/runtime/doctor_protocol.py (or praisonaiagents/hooks/ if shared): collect_findings(config) -> list[Finding], apply_fix(config) -> config, rule_id.
• Core registers built-in rule: migrate cli_backend → models.<default>.runtime with mapping table for known ids (claude-code → same runtime id).
• Plugins register additional rules via entry point praisonai.doctor_contracts.
• Wire into praisonai doctor runtime --fix (extends preflight issue).

Acceptance criteria

• Protocol defined with lazy plugin discovery.
• Built-in migration rule covered by unit test on sample YAML.
• --fix is idempotent and creates backup hint in doctor output.
• Does not auto-fix without explicit --fix flag.

Layer

Primary: core (DoctorContractProtocol, built-in rule)

Secondary: wrapper (praisonai doctor runtime), plugins (custom rules)

3-way parity (Python / YAML / CLI)

Surface	Supported
Python	yes — programmatic lint/fix API
YAML	yes — primary migration target
CLI	yes — praisonai doctor runtime --fix

Priority

P2

Related modules

praisonai/cli/commands/doctor.py, praisonai/agents_generator.py, praisonaiagents/agent/agent.py, praisonaiagents/plugins/

Related issues

• Model-scoped runtime selection policy #1935 — Model-scoped runtime selection policy
• Multi-agent runtime preflight (doctor runtime --team) #1937 — Multi-agent runtime preflight (doctor runtime --team)
• Deprecate agent-level cli_backend and external runtime pins #1942 — Deprecate agent-level cli_backend and external runtime pins

[MervinPraison]

Cross-links: #1942

[praisonai-triage-agent]

Claude finished @MervinPraison's task —— View job • claude/issue-1941-20260613-0842 • Create PR ➔

---

Implementing DoctorContractProtocol for runtime config migration ✅

Todo List:

• Read AGENTS.md for architecture guidelines
• Analyze existing doctor infrastructure
• Create DoctorContractProtocol definition
• Implement built-in cli_backend migration rule
• Update CLI command to support --fix flag
• Add unit tests for migration
• Test implementation
• Commit and push changes

Implementation Complete

I've successfully implemented the DoctorContractProtocol for runtime config migration as requested in issue #1941. Here's what was delivered:

Core SDK (praisonaiagents):

• ✅ DoctorContractProtocol defined in praisonaiagents/runtime/doctor_protocol.py
• ✅ Built-in CliBackendMigrationRule with mapping table (claude-code → same runtime id)
• ✅ Plugin discovery registry via praisonai.doctor_contracts entry points
• ✅ Lazy plugin loading for performance

Wrapper Layer (praisonai):

• ✅ praisonai doctor runtime --fix command added
• ✅ Idempotent migrations with backup creation
• ✅ Dry-run mode by default (use --execute to apply changes)

Testing & Validation:

• ✅ Comprehensive unit tests covering protocol compliance and migration scenarios
• ✅ Real-world testing with sample YAML configuration
• ✅ Verified idempotent behavior and backup creation hints

Key Features:

• Protocol-driven design: Core protocols in SDK, implementations in wrapper (per AGENTS.md)
• Plugin extensibility: Third-parties can register custom migration rules
• Safety: Creates backups before applying fixes, dry-run by default
• Backward compatibility: No breaking changes to existing APIs

The implementation follows all acceptance criteria:

• Protocol defined with lazy plugin discovery ✅
• Built-in migration rule with unit test coverage ✅
• --fix is idempotent and creates backup hints ✅
• Does not auto-fix without explicit --fix flag ✅

---