Scenario 18 analyzes bounded files and returns optimization suggestions by category. The current public contract is analysis-only: no documented Scenario 18 route applies source changes.
Choose a supported analysis route
For a reproducible source-checkout scan:
python -m src.cli optimize analyze PATH --output suggestions.json
python -m src.cli optimize patterns
analyze reads a file or directory and may write the suggestion JSON only to the explicit output path. patterns lists available rules. Neither command edits the analyzed source.
Run the typed scenario
from src.digital_employees.runtime.scenarios import (
RoleBoundScenarioInvocationRequest,
invoke_role_bound_scenario_request,
)
request = RoleBoundScenarioInvocationRequest(
query="Analyze optimization opportunities in src/import_pipeline.py.",
employee_id="codegraph_developer",
scenario_id="scenario_18",
event_type="implementation_start",
context={
"project_key": "codegraph",
"namespace": "default",
"task_id": "<task-id>",
"source_refs": ["<revision-ref>", "<measurement-ref>"],
"file_paths": ["src/import_pipeline.py"],
},
)
result = invoke_role_bound_scenario_request(request)
The workflow returns optimization_suggestions in result state. Persist approval and call a source
writer through a separate governed implementation task.
MCP and composite analysis
The registered codegraph_runtime_composition_workflow_run tool accepts orchestrator="s18", plus governed namespace and task_id. The current MCP mapping invokes role-bound scenario_18 analysis and returns answer, evidence, and metadata.
The CLI python -m src.cli composition run "<query>" -o s18 runs a broader composite analysis and stores its session only in the current process. Treat both routes as analysis evidence; source mutation uses a separate implementation workflow.
Unsupported stateful loop
The optimize parser registers list-suggestions, approve, reject, apply, and undo, but their handlers print not yet implemented and return exit code 1. Use the supported analysis workflow and a governed implementation task for automation or approval.
composition apply remains a demonstration path: it depends on process-local state, prints Edit application not implemented in CLI demo, leaves source files unchanged, and returns zero. The MCP composition tool returns suggestions for a separate implementation task.
Read and verify suggestions
Confirm each suggestion against the bound revision, a measurable objective, compatibility constraints, and focused tests. Performance measurements, security checks, and maintainability review establish the resulting benefit.
Create a separate governed implementation slice for an accepted suggestion, then use RED/GREEN tests, measurement, review, AppSec/QA evidence, and rollback as required.
Failure and recovery
- Path not found: correct the exact file or directory scope.
- No suggestions: do not infer that the code is optimal; check category and analysis coverage.
- Stub command invoked: treat the nonzero result as unsupported and return to analysis output.
- Composite session missing: rerun analysis for evidence only; do not attempt to reconstruct mutation state.
Source contract
This guide is bound to:
src/cli/analysis_commands/optimize_commands.py— implemented analyze/patterns and stateful stubs;src/workflow/scenarios/code_quality/code_optimization.py— typed analysis state;src/cli/domain_suite/composition_commands.py— composite analysis and non-applying demo command;src/mcp/tools/core/compose.py— MCP role-bound mapping;src/digital_employees/runtime/scenarios/employee_scenario_invocation.py— developer ownership and policy.