Scenario 13 finds usages, groups migration candidates, estimates call-site impact, and proposes an execution sequence. The result is a migration plan for a separate implementation task; the workflow preserves source files.
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
Prepare the Python environment and local configuration using the CLI guide and programmatic guide. Confirm graph-service availability and configure the LLM used by the planning workflow. Agree on migration scope with the owner before implementation.
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
Save the example as a Python file in the configured environment. Replace project, namespace, task, evidence-reference and path placeholders with the accepted scope. Replace the illustrative symbol names with the actual source and destination symbols.
from src.digital_employees.runtime.scenarios import (
RoleBoundScenarioInvocationRequest,
invoke_role_bound_scenario_request,
)
request = RoleBoundScenarioInvocationRequest(
query="Rename 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)
if result.get("error"):
raise RuntimeError(result["error"])
if not result.get("scenario_id") or not result.get("answer"):
raise RuntimeError("Scenario returned no scenario identity or answer")
print(result["answer"])
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.
Inspect metadata.refactoring_target_resolution, especially needs_clarification, the selected target and its origin. When needs_clarification is set, refine the inputs and repeat the request. Confirm fallback candidate usages through the CPG and source files. Check result.get("error") alongside the answer.
Check the selected target
For the example query, this fragment of metadata.refactoring_target_resolution contains:
{
"operation_intent": "rename",
"target_symbol": "LegacyClient",
"destination_symbol": "ServiceClient",
"needs_clarification": false,
"clarification_reason": null,
"resolution_source": "user_input"
}
Compare target_symbol with the original symbol and destination_symbol with its new name. needs_clarification=false means the resolver identified the rename direction. The workflow then searches for usages of the selected target and prepares a plan.
The query Rename LegacyClient and ServiceClient leaves the direction open. The resolver returns a clarification:
{
"candidate_symbols": [
"LegacyClient",
"ServiceClient"
],
"needs_clarification": true,
"clarification_reason": "ambiguous_rename_target",
"clarification_question": "Please clarify the target symbol and expected result for: LegacyClient, ServiceClient."
}
Repeat the query as Rename LegacyClient to ServiceClient across the bounded component.. Check the selected pair and the CPG usages in the response.
Both fragments show target resolution. Retrieved call sites and the migration plan depend on your project source and graph.
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. Verify the rename through the changed files and test results.
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.