EXECUTION-PRIORITIES-unified-ownership.md

Unified Ownership Execution Priorities

Objective

Deliver a contract-first, multi-adapter architecture that makes this codebase the canonical unified tool backend for LLM runtimes while preserving production stability.

Success Metrics

• 0 known metadata/schema drift defects in consolidated tools
• 100 percent of consolidated tools use explicit context injection
• 100 percent of consolidated handlers depend on domain facades, not direct DB access
• Legacy tool surface traffic below 5 percent before removal
• p95 tool latency does not regress by more than 10 percent during migration

Priority 1: Lock Architectural Decisions and Guardrails

Deliverables

1. Decision closure

• Finalize ADR-004 as compatibility mode with a clear deprecation trigger.
• Keep ADR-005 as the ownership architecture baseline.

2. Contract model and generators (thin slice)

• Define ToolContract type and generator interfaces.
• Migrate a representative thin slice (one combat, one world, one utility tool).
• Generate registry metadata and meta-tool outputs for migrated tools.

3. Safety rails

• Add parity tests ensuring generated metadata/actions/schemas match runtime behavior.
• Add CI gate that fails on contract drift for migrated tools.

Exit Criteria

• Contract generation is running in CI for thin-slice tools.
• No behavioral regressions in migrated tools.
• ADR-004 decision is documented and discoverable.

Priority 2: Migrate Core Runtime to Contracts and Explicit Context

Deliverables

1. Contract migration

• Migrate consolidated tools to ToolContract objects.
• Remove manual metadata maps in consolidated-registry after parity passes.

2. Context hardening

• Remove module-level mutable context usage.
• Thread SessionContext via router and service signatures.
• Add parallel multi-session tests for combat/world/spatial scenarios.

3. Service facade rollout

• Introduce facades for combat, world, inventory, party, and session domains.
• Route consolidated handlers through facades first.

Exit Criteria

• Majority of consolidated tool calls run through contract-generated registry.
• No module-level mutable context remains in migrated modules.
• Domain facade coverage includes critical gameplay paths.

Priority 3: Complete Adapters and Prepare Legacy Removal

Deliverables

1. Adapter completion

• MCP adapter fully generated from contracts.
• Add at least one non-MCP adapter spec target generated from the same contracts.

2. Legacy compatibility mode

• Implement forwarding from legacy surface to consolidated contracts.
• Add parity matrix tests for top workflows.
• Add runtime telemetry to measure legacy endpoint usage.

3. Planner metadata and workflows

• Publish prerequisites, next actions, and canonical workflows in contracts.
• Extend meta-tools to expose planner metadata for orchestration clients.

4. Removal readiness package

• Release notes, migration guide, and deprecation checklist.

Exit Criteria

• 100 percent consolidated tools are contract-backed.
• Compatibility matrix is green for critical workflows.
• Legacy usage is below threshold and removal is announced.

Workstreams

1. Platform contracts

• Scope: ToolContract model, registry/spec/doc generators, parity tests.

2. Runtime correctness

• Scope: context threading, race/leak testing, session isolation.

3. Domain services

• Scope: facade interfaces, handler rewiring, repository boundary cleanup.

4. Compatibility and migration

• Scope: legacy forwarding, telemetry, release communication.

Risks and Mitigations

1. Migration churn across many files

• Mitigation: domain-by-domain rollout with parity tests per domain.

2. Behavior regressions during handler rewiring

• Mitigation: freeze action semantics; enforce snapshot and contract parity tests.

3. Performance overhead from extra abstraction

• Mitigation: benchmark before/after each domain migration; tune hot paths in services.

4. Consumer breakage from legacy removal

• Mitigation: compatibility mode, telemetry-based threshold, staged deprecation notices.