docs: add v2→v3 mapping matrix and migration slice plan

implementation_plan.md

@@ -674,6 +674,30 @@ All 10 ADRs have been created in `docs/architecture/decisions/`:
 - Approach: produce a v2→v3 mapping matrix (actor-only, CLEVERAGENTS_* envs), fold missing Behave coverage into `features/` with updated steps/fixtures, translate Robot suites into `robot/` using current helpers, and relocate examples into the current examples/docs tree with actor-first configs (no provider/model flags).
 - Validation: run `nox -s unit_tests` and `nox -s integration_tests` after each migration slice; spawn `Fix – …` tasks for any failures; record mapping/coverage deltas and example moves in Phase 2 Notes.
 
+**2026-01-15 (cont.): Initial v2→v3 mapping results**
+- Categorized v2 Behave suites under `v2/tests/features/`: CLI/runtime (`cli_*`, `load_context_cli`, `interactive_session_test`), config/parser/Jinja/templates (`config_*`, `inline_jinja*`, `inline_yaml_jinja*`, `yaml_template_engine*`, `template_*`, `smart_yaml_loader*`, `jinja_yaml_preprocessor*`, `template_store_coverage`, `graph_templates_*`), LangGraph/agent workflows (`langgraph_*`, `agent_*`, `chain_agent_*`, `composite_agent_*`, `reactive_*`, `stream_router_*`, `tool_agent_*`, `langgraph_rxpy_operator`, `langgraph_state_management`, `langgraph_visualization`), routing/context (`route_*`, `routing_prefix_stripping`, `unified_routes`, `context_manager`, `context_delete_all_yes`, `load_context_cli`), and error/logging/misc suites (`error_verbosity`, `verbose_logging_levels`, `stderr_suppression`, `network_coverage`, `unit_temperature_override`, `unit_json_sanitization`, `unit_tool_command_processing`).
+- Cataloged Robot suites under `v2/tests/integration/` for commands/context/routing/rendering (`commands_test.robot`, `context_management_test.robot`, `load_context_test.robot`, `routing_prefix_stripping_test.robot`, `rxpy_route_validation_test.robot`, `error_verbosity_integration_test.robot`, `stderr_suppression_test.robot`, `temperature_override.robot`, `verbose_logging_test.robot`, `version*.robot`, `discovery_topic_progression_test.robot`, `generate_examples_test.robot`, `scientific_paper_*` suites).
+- Gap assessment: current actor-first coverage in `features/actor_*`, `features/cli_plan_context_commands.feature`, provider/plan streaming suites, and actor registry/config tests does not cover the v2 config/parser/Jinja/template suites, langgraph routing/reactive/stream_router suites, or the Robot command/context/routing flows; these require migration with actor-only flags and CLEVERAGENTS_* env defaults.
+- Migration order proposal: (1) port CLI + config/parser/Jinja Behave suites to actor-first steps and modern fixtures; (2) port langgraph/agent/routing Behave suites with PlanGenerationGraph + ContextService hooks; (3) port Robot suites using existing helpers (`robot/common.resource`, `robot/helper_actor_config.py`, `robot/helper_context_analysis.py`); (4) relocate `v2/tests/fixtures` and `v2/examples` assets into current fixtures/examples after actor-only normalization and delete `./v2` once complete.
+- Next actions tracked in Stage 7.5 checklist; hold further Stage 7.5 items until these migrations are recorded and executed.
+
+**2026-01-15 (cont.): v2→v3 mapping matrix (actor-first)**
+| Category | v2 suite patterns | Target v3 home (actor-first) | Status / action |
+| --- | --- | --- | --- |
+| CLI + runtime + context | `cli_*`, `load_context_cli`, `interactive_session_test` | Extend `features/cli_plan_context_commands.feature` + `features/cli.feature`; reuse `robot/cli_plan_context_commands.robot` with actor-only flags/default resolution | Partial coverage exists for actor CLI; port v2 scenarios with actor/default guards and context flags |
+| Config/parser/Jinja/templates | `config_*`, `inline_jinja*`, `inline_yaml_jinja*`, `yaml_template_engine*`, `template_*`, `smart_yaml_loader*`, `jinja_yaml_preprocessor*`, `template_store_coverage`, `graph_templates_*` | Merge into `features/yaml_template_engine_coverage.feature`, `features/actor_config_coverage.feature`, and new/extended template store steps; rely on existing CLEVERAGENTS_* env defaults | Gap – port v2 expectations and fixtures; ensure actor-only step text and env renames |
+| LangGraph/agent/routing/reactive | `langgraph_*`, `agent_*`, `chain_agent_*`, `composite_agent_*`, `reactive_*`, `stream_router_*`, `tool_agent_*`, `langgraph_rxpy_operator`, `langgraph_state_management`, `langgraph_visualization`, `route_*`, `routing_prefix_stripping`, `unified_routes`, `context_manager`, `context_delete_all_yes`, `load_context_cli` | Add scenarios to `features/plan_generation_langgraph_coverage.feature`, `features/context_analysis_agent_coverage.feature`, streaming/auto-debug suites; backfill Robot parity in `robot/plan_generation_graph.robot` and `robot/context_analysis_agent.robot` | Gap – actor-first LangGraph/routing flows missing; port v2 graph/rxpy/routing behaviors and context deletion safeguards |
+| Error/logging/misc | `error_verbosity`, `verbose_logging_levels`, `stderr_suppression`, `network_coverage`, `unit_temperature_override`, `unit_json_sanitization`, `unit_tool_command_processing` | Fold into `features/cli_coverage.feature`, `features/auto_debug_integration.feature`, provider/plan service suites; create Robot smoke in `robot/cli.robot`/`robot/provider_registry.robot` as needed | Gap – create actor-only coverage for verbosity/temperature/network/JSON sanitization with current mocks |
+| Robot integration suites | `v2/tests/integration/*.robot` (commands/context/routing/rendering/version/scientific_paper/generate_examples/rxpy) | Translate into `robot/` using `robot/common.resource`, `robot/helper_actor_config.py`, `robot/helper_context_analysis.py`; keep actor flags + CLEVERAGENTS_* envs | Gap – no v3 equivalents yet; port after Behave slices land |
+| Fixtures + examples | `v2/tests/fixtures/**/*`, `v2/tests/mocks/llm_providers.py`, `v2/examples/*.yaml`, `v2/examples/make_context.sh` | Relocate fixtures under `features/fixtures/` or `robot/` resources; swap mocks for existing test providers; move examples into `examples/`/`docs/` with actor-first configs | Gap – relocate after scenario ports; remove provider/model flags and align env vars |
+
+**2026-01-15 (cont.): Migration slice #1 plan – CLI + config/Jinja/templates**
+- Port v2 CLI/runtime/context suites (`cli_coverage`, `cli_comprehensive`, `cli_command_coverage`, `cli_main_module`, `cli_integration`, `cli_sandbox_coverage`, `load_context_cli`) into actor-first flows in `features/cli_plan_context_commands.feature`, `features/cli.feature`, and `robot/cli_plan_context_commands.robot`, enforcing `--actor`/default-actor selection and CLEVERAGENTS_* envs.
+- Port config parser/core/specific suites (`config_parser_*`, `config_core_coverage`, `config_specific_coverage`, `config_module_coverage`, `configuration_management`) into `features/actor_config_coverage.feature` plus new step hooks that exercise the actor config parser and settings loader without provider/model flags.
+- Port inline Jinja/template suites (`inline_yaml_jinja*`, `inline_jinja_handler_*`, `yaml_template_engine*`, `templates_*`, `template_store_coverage`, `graph_templates_*`, `smart_yaml_loader_coverage`) into `features/yaml_template_engine_coverage.feature` and YAML template step definitions, reusing `YAMLTemplateEngine` and actor config fixtures with CLEVERAGENTS_* envs.
+- Normalize required fixtures from `v2/tests/fixtures` and example YAMLs for this slice into `features/fixtures/` with actor-first defaults; drop `tests/mocks/llm_providers.py` in favor of existing mocks.
+- Validation for this slice: run `nox -s unit_tests` (targeting the migrated CLI/config/template features) and `nox -s integration_tests` for the updated CLI Robot suite; spawn `Fix – …` tasks for any failures.
+
 **2025-12-09: Provider streaming normalization + Behave coverage refresh**
 - `PlanService.generate_plan_streaming` now consumes the new provider iterator contract, normalizes nested `__end__/response` payloads, validates streamed `Change` objects, persists token counts, and still emits the legacy CLI end event for compatibility (`src/cleveragents/application/services/plan_service.py:858`).
 - `LangChainChatProvider.stream_changes` (plus both mock providers) now yield LangGraph workflow events followed by `{"__end__": {"response": ProviderResponse}}`, guaranteeing a consistent exit shape and structured usage logging (`src/cleveragents/providers/llm/langchain_chat_provider.py:154`, `features/mocks/langchain_mock_provider.py:269`, `features/mocks/mock_ai_provider.py:218`).
@@ -4478,7 +4502,9 @@ If you can do all of the above by end of Day 1, you're on track!
       - [X] Merge CLI-supplied actor option overrides into canonical blobs without injecting provider/model metadata into options and only persist options when provided (`src/cleveragents/cli/commands/actor.py:65-189`, `src/cleveragents/actor/config.py:82-138`, `src/cleveragents/actor/registry.py:52-73`).
       - [X] Wire actor options into graph/context invocation (package defaults + initial context variables), ensure graph execution receives merged options (package options → CLI overrides → defaults), and keep config hash/unsafe persistence semantics with audit timestamps intact.
       - [X] Port git `v2` tag API/CLI documentation relevant to actors/configuration into docs; scrub `--model/--provider` references and any `v2` naming; update CLI help/man pages and `agents --help` output to describe `--actor`, unsafe semantics, default resolution, and removal guards.
-      - [ ] Build a v2→v3 mapping matrix covering all `v2/tests/features/*.feature` suites (config/parser/routing/langgraph/context/CLI) and update/migrate missing Behave coverage into `features/` with actor-only flags, CLEVERAGENTS_* envs, and relocated fixtures.
+      - [X] Build a v2→v3 mapping matrix covering all `v2/tests/features/*.feature` suites (config/parser/routing/langgraph/context/CLI) and update/migrate missing Behave coverage into `features/` with actor-only flags, CLEVERAGENTS_* envs, and relocated fixtures (Phase 2 Notes 2026-01-15 mapping matrix).
+      - [ ] Port v2 CLI + config/parser/Jinja Behave suites to actor-first coverage with CLEVERAGENTS_* env defaults and actor-only flags (source: `v2/tests/features/cli_*`, `config_*`, `inline_*`, `yaml_template_engine*`, `template_*`, `jinja_yaml_preprocessor*`, `smart_yaml_loader*`, `template_store_coverage`, `graph_templates_*`).
+      - [ ] Port v2 LangGraph/agent/routing Behave suites to actor-first LangGraph paths (source: `v2/tests/features/langgraph_*`, `agent_*`, `chain_agent_*`, `composite_agent_*`, `reactive_*`, `stream_router_*`, `tool_agent_*`, `langgraph_rxpy_operator`, `langgraph_state_management`, `langgraph_visualization`, `route_*`, `routing_prefix_stripping`, `unified_routes`, `context_manager`, `context_delete_all_yes`, `load_context_cli`).
       - [ ] Port `v2/tests/integration/*.robot` suites to `robot/` using current helpers/resources; relocate `v2/tests/fixtures/**/*`, replace `tests/mocks/llm_providers.py` with existing mocks, and drop any provider/model flag usage.
       - [ ] Move `v2/examples/*.yaml` and `v2/examples/make_context.sh` into the current examples/docs tree with actor-first configuration, documenting runnable commands and aligning with LangGraph agents.
       - [ ] Delete the temporary `./v2` reference directory once Stage 7.5 actor porting and documentation are complete (final cleanup step).
@@ -4488,7 +4514,7 @@ If you can do all of the above by end of Day 1, you're on track!
       - [X] Replace CLI help/man output and README/guide snippets to show actor-only flags, removing provider/model examples and legacy option mentions before finalizing the actor-first surface.
       - [X] Update architecture references/ADRs (ADR-008/ADR-011 or addenda) to capture actor registry boundaries, actor package responsibilities, dependency on provider registry + `ContextService`, default pointer storage, built-in immutability, and removal of `--model/--provider` in favor of `--actor`.
       - [X] Include migrated API documentation from git's v2 tag describing actor configuration fields, supported options, graph descriptor semantics, unsafe detection rules, and how actor package outputs map to provider/model selection and LangGraph invocation.
-      - [ ] Update **Phase 2 Notes** with the mapping table, coverage deltas, fixture/example destinations, and any deviations; record new follow-up tasks spawned by the migration.
+      - [X] Update **Phase 2 Notes** with the mapping table, coverage deltas, fixture/example destinations, and any deviations; record new follow-up tasks spawned by the migration.
     - [ ] Tests:
       - [X] Add v2-format actor config parsing coverage (Behave + Robot) for YAML inference of provider/model/graph/options (format unchanged between v2 and v3).
       - [X] Port git v2's tag unit coverage into Behave features covering actor configuration parsing (valid/invalid blobs, option normalization), actor package outputs (graph_descriptor, provider/model requirements), unsafe detection, registry CRUD (hash stability, default guard, removal requiring `local/<id>`), built-in enumeration, default selection, warning emission at verbosity ≥ warning, and chat/plan flows with `--actor` plus context flags.