Scenario 13 finds usages, groups migration candidates, estimates call-site impact, and proposes an execution sequence. It is a plan-only analysis surface: the workflow does not edit or rename source files; those changes run through a separate implementation workflow.
When to use it
Use it for a broad but explicit migration such as renaming a public symbol, replacing an API, or changing a signature across many call sites. State the source and destination symbols, affected component, compatibility rule, and revision.
Use Scenario 05 for a bounded behavior-preserving change. Use Scenario 10 first when several repositories are involved.
Prerequisites and scope
Bind the request to an accepted implementation task and current source revision. Define exclusions, generated code, public compatibility constraints, ownership, and the maximum migration slice.
The workflow may use query-derived fallback targets when a project CPG is unavailable. Use that list to clarify scope, then confirm the blast radius with the project CPG and repository checks.
Run the typed scenario
from src.digital_employees.runtime.scenarios import (
RoleBoundScenarioInvocationRequest,
invoke_role_bound_scenario_request,
)
request = RoleBoundScenarioInvocationRequest(
query="Plan renaming LegacyClient to ServiceClient across the bounded component.",
employee_id="codegraph_developer",
scenario_id="scenario_13",
event_type="implementation_start",
context={
"project_key": "codegraph",
"namespace": "default",
"task_id": "<task-id>",
"source_refs": ["<revision-ref>", "<compatibility-contract-ref>"],
"file_paths": ["<bounded-source-path>"],
},
)
result = invoke_role_bound_scenario_request(request)
An ambiguous rename request returns for clarification. A fallback target becomes an implementation task only after the owner confirms it.
Read the result
Review the target resolution metadata, retrieved functions, categorized call sites, evidence, and proposed order. Confirm each decision-relevant usage in the bound revision. Preserve the invocation evidence with the migration plan.
The terms “simple,” “signature change,” and “complex” describe heuristic categories. Compatibility and test analysis, followed by owner approval, authorize an implementation rewrite.
Governed mutation after planning
Create a separate exact-scope implementation slice for every approved group. Its minimum controls are:
approval: accountable human authorization for that slice;tests: RED/GREEN coverage for the intended contract and regressions;rollback: a revision-bound recovery procedure;- focused architecture, AppSec, QA, documentation, and traceability evidence as required.
Apply, review, and validate one slice before expanding the migration. The Scenario 13 result itself is never evidence that a rename was performed.
Failure and recovery
- Clarification requested: provide one source/destination pair and a bounded component.
- CPG unavailable: label query-derived output as preliminary and restore revision-bound CPG evidence.
- Unexpected call sites: stop the slice, update scope and tests, then request fresh approval.
- Regression after a slice: execute the recorded rollback and preserve failure evidence before replanning.
Source contract
This guide is bound to:
src/workflow/scenarios/refactoring/mass_migration.py— target resolution, CPG analysis, fallback, categorization, and plan generation;src/digital_employees/runtime/scenarios/role_bound_scenario_invoker.py— typed routing;src/digital_employees/runtime/scenarios/employee_scenario_invocation.py— developer ownership and conditional policy.
The workflow returns state and recommendations; no source-write implementation is called from this contract.