refactor(docs): code analysis engine

changes:
  - file: 02_mcp_integration.py
    area: core
    modified: [run_mcp_tool, simulate_planfile_generate, simulate_planfile_review, simulate_planfile_apply]
  - file: 03_proxy_routing.py
    area: core
    modified: [get_routing_decision, get_usage_stats, chat, example_strategy_generation_with_proxy, ProxyClient]
  - file: 04_llx_integration.py
    area: core
    modified: [get_task_scope, __init__, ProjectMetrics, analyze_project, LLXIntegration, _basic_analysis, +1 more]
  - file: test_interactive_mode.py
    area: test
    modified: [test_expect_script, test_interactive_mode]
  - file: llx_validator.py
    area: core
    modified: [validate_strategy, __init__, _basic_code_analysis, LLXValidator, _parse_llx_analysis, analyze_generated_code]
  - file: test_litellm_integration.py
    area: test
    modified: [test_specific_strategy, create_test_prompt, test_model_with_prompt, LiteLLMStrategyTester, run_comprehensive_test, generate_summary]
  - file: test_strategies.py
    area: test
    modified: [test_strategy_generation, validate_strategy_yaml, test_strategy_validation]
  - file: __init__.py
    area: core
    modified: [__getattr__]
  - file: external_tools.py
    area: analyzer
    modified: [__init__, run_code2llm, parse_vallm_output, run_vallm, parse_code2llm_output, run_external_analysis, +4 more]
  - file: file_analyzer.py
    area: analyzer
    modified: [_generate_summary, analyze_directory, analyze_file, FileAnalyzer]
  - file: generator.py
    area: analyzer
    modified: [_external_to_internal_analysis, __init__, _parse_effort, _extract_external_metrics, generate_from_current_project, _extract_key_metrics, +10 more]
  - file: metrics_extractor.py
    area: analyzer
    modified: [_extract_duplication_metrics, _extract_cc_metrics, _extract_coverage_metrics, _extract_validation_metrics, extract_key_metrics, _extract_critical_metrics]
  - file: strategy_builder.py
    area: analyzer
    modified: [generate_target_metrics, generate_goals, generate_quality_gates, generate_tasks, parse_effort, generate_success_criteria, +2 more]
  - file: models.py
    area: analyzer
    modified: [ExtractedIssue, ExtractedMetric, ExtractedTask]
  - file: json_parser.py
    area: analyzer
    modified: [analyze_json]
  - file: text_parser.py
    area: analyzer
    modified: [analyze_text]
  - file: toon_parser.py
    area: analyzer
    modified: [_parse_summary_section, analyze_toon, _parse_health_section, _skip_section, _parse_toon_header, _parse_toon_sections]
  - file: yaml_parser.py
    area: analyzer
    modified: [analyze_yaml, extract_from_yaml_structure]
  - file: sprint_generator.py
    area: analyzer
    modified: [_get_highest_priority, _get_remaining_medium_issues, _estimate_effort, _get_high_and_quality_issues, _create_sprint, generate_sprints, +3 more]
  - file: server.py
    area: api
    modified: [list_tickets, TicketUpdate]
  - file: builder.py
    area: core
    modified: [create_strategy_command, build_strategy, answers_to_strategy, _parse_bullet_list, ask_llm_questions, LLXStrategyBuilder]
  - file: ci.py
    area: core
    modified: [__init__, run_code_analysis, TestResult, create_bug_tickets, run_loop, BugReport, +4 more]
  - file: auto_loop.py
    area: cli
    modified: [auto_loop, _save_results_if_needed, _initialize_backends, ci_status]
  - file: cmd_apply.py
    area: cli
    modified: [apply_strategy_cli, _execute_apply_strategy, _save_results]
  - file: cmd_compare.py
    area: cli
    modified: [compare_strategies, compare_cmd, register_compare_commands]
  - file: cmd_examples.py
    area: cli
    modified: [_execute_example, run_example, _discover_examples, list_examples, create_examples_app]
  - file: cmd_export.py
    area: cli
    modified: [merge_cmd, register_export_commands, export_cmd]
  - file: cmd_generate.py
    area: cli
    modified: [generate_from_files_cmd, generate_strategy_cli]
  - file: cmd_health.py
    area: cli
    modified: [create_health_app, health_cmd]
  - file: cmd_init.py
    area: cli
    modified: [init_strategy_cli]
  - file: cmd_review.py
    area: cli
    modified: [review_strategy_cli]
  - file: cmd_stats.py
    area: cli
    modified: [register_stats_commands, calculate_strategy_stats, stats_cmd]
  - file: cmd_sync.py
    area: cli
    modified: [sync_integration, sync_from_external, find_planfile_ticket, all, jira, gitlab, +5 more]
  - file: cmd_template.py
    area: cli
    modified: [register_template_commands, template_cmd]
  - file: cmd_ticket.py
    area: cli
    modified: [ticket_create, ticket_list, ticket_update, ticket_import, ticket_move, _display_tickets, +2 more]
  - file: cmd_utils.py
    area: cli
    modified: [_parse_sprint_filter, _load_backend_config]
  - file: cmd_validate.py
    area: cli
    modified: [validate_strategy_cli]
  - file: commands.py
    area: cli
    modified: [main_callback, version_callback, main]
  - file: project_detector.py
    area: cli
    modified: [_find_readme_goal, _detect_from_package_json, _find_readme_description, _find_readme_content, detect_project, _detect_model_tier, +7 more]
  - file: store.py
    area: core
    modified: [TicketFilter, apply, SourceFilter, __init__, get_ticket, update_ticket, +10 more]
  - file: examples.py
    area: core
    modified: [example_validate_strategy, example_create_strategy, example_verify_strategy, example_run_strategy, example_programmatic_strategy]
  - file: executor_standalone.py
    area: core
    modified: [_default_config, __init__, chat, LLMClient, _execute_task, execute_strategy, +4 more]
  - file: redup_importer.py
    area: core
    modified: [import_redup, _parse_refactor, _parse_duplicates, _parse_toon_format, _create_refactor_ticket]
  - file: config.py
    area: config
    modified: [get_integration_config, discover_configs, load_configs, get_sprint_config, _deep_merge, get_project_config, +2 more]
  - file: adapters.py
    area: core
    modified: [__init__, get_available_models, BaseLLMAdapter, LLMTestRunner, LLMTestResult]
  - file: client.py
    area: cli
    modified: [call_llm]
  - file: cli_loader.py
    area: cli
    modified: [_md_summary, save_strategy_to_json, _md_metrics, _md_tasks, _md_header, load_strategy_from_json, +4 more]
  - file: yaml_loader.py
    area: core
    modified: [_transform_sprints, load_strategy_yaml, _transform_goal, merge_strategy_with_tasks, save_yaml, validate_strategy_schema, +5 more]
  - file: runner.py
    area: core
    modified: [verify_strategy_post_execution, apply_strategy_to_tickets, review_strategy, analyze_project_metrics]
  - file: base.py
    area: core
    modified: [prepare_metadata, BasePMBackend, build_ticket_status, TicketRef, list_tickets, __init__, +11 more]
  - file: generic.py
    area: core
    modified: [__init__, _create_ticket, GenericBackend, _list_tickets, _update_ticket, _build_update_data, +2 more]
  - file: github.py
    area: core
    modified: [__init__, GitHubBackend, _search_tickets, _create_ticket, _list_tickets, _ensure_labels_exist, +1 more]
  - file: gitlab.py
    area: core
    modified: [GitLabBackend, __init__, _search_tickets, _create_ticket, _list_tickets, _update_ticket]
  - file: jira.py
    area: core
    modified: [__init__, _map_priority_to_jira, _search_tickets, _create_ticket, JiraBackend, _list_tickets, +1 more]
  - file: markdown_backend.py
    area: core
    modified: [_ticket_exists_by_title, MarkdownFileBackend, _find_ticket_file, _search_tickets, _create_ticket, _list_tickets, +4 more]
  - file: mock.py
    area: core
    modified: [_create_ticket, _list_tickets, MockBackend, _update_ticket]
  - file: metrics.py
    area: util
    modified: [analyze_project_metrics, calculate_strategy_health]
  - file: priorities.py
    area: util
    modified: [calculate_task_priority]
  - file: test_improvements.py
    area: test
    modified: [test_v2_format]
  - file: test_integration.py
    area: test
    modified: [test_integration]
  - file: llm_adapters.py
    area: test
    modified: [LocalLLMAdapter, OpenRouterAdapter, BaseLLMAdapter, LLMTestRunner, generate_report, _generate_failed_tests_section, +8 more]

dependencies:
  flow: "server_common→planfile, cmd_health→generator, test_integration→generator, commands→auto_loop, cmd_ticket→planfile, test_improvements→planfile, cmd_generate→generator, ci→planfile"
  - ci.py -> planfile.py
  - cmd_generate.py -> generator.py
  - cmd_health.py -> generator.py
  - cmd_ticket.py -> planfile.py
  - commands.py -> auto_loop.py
  - commands.py -> planfile.py
  - server_common.py -> planfile.py
  - test_improvements.py -> planfile.py

stats:
  lines: "+5744/-2944 (net +2800)"
  files: 93
  complexity: "Stable complexity"

Author: tom-sapletta-com

CHANGELOG.md

@@ -5,8 +5,237 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.10] - 2026-03-27
+
+### Fixed
+- Fix smart-return-type issues (ticket-4a9b3842)
+- Fix string-concat issues (ticket-4d72bb66)
+- Fix unused-imports issues (ticket-1d12c733)
+- Fix llm-hallucinations issues (ticket-4adeb88d)
+- Fix magic-numbers issues (ticket-5854a43d)
+- Fix llm-generated-code issues (ticket-5b6370f6)
+- Fix ai-boilerplate issues (ticket-faba83d0)
+- Fix smart-return-type issues (ticket-2bf9f839)
+- Fix string-concat issues (ticket-528feae8)
+- Fix unused-imports issues (ticket-c8151e11)
+- Fix magic-numbers issues (ticket-c68be4d9)
+- Fix llm-generated-code issues (ticket-f4b0c052)
+- Fix ai-boilerplate issues (ticket-e1315260)
+- Fix smart-return-type issues (ticket-cfd5a1db)
+- Fix string-concat issues (ticket-d758ef6c)
+- Fix unused-imports issues (ticket-f7196314)
+- Fix llm-hallucinations issues (ticket-90a9eca4)
+- Fix magic-numbers issues (ticket-baacdd9d)
+- Fix llm-generated-code issues (ticket-40fef6ab)
+- Fix ai-boilerplate issues (ticket-fc7c16f9)
+- Fix smart-return-type issues (ticket-a96102b5)
+- Fix string-concat issues (ticket-643abcdb)
+- Fix unused-imports issues (ticket-65ff2e98)
+- Fix ai-boilerplate issues (ticket-897ceba9)
+- Fix smart-return-type issues (ticket-aea66e08)
+- Fix string-concat issues (ticket-8d6108f8)
+- Fix unused-imports issues (ticket-b2e32f30)
+- Fix magic-numbers issues (ticket-5fdd561a)
+- Fix ai-boilerplate issues (ticket-770ea9fb)
+- Fix string-concat issues (ticket-94f03f3e)
+- Fix unused-imports issues (ticket-9f2c2205)
+- Fix llm-hallucinations issues (ticket-acf76316)
+- Fix ai-boilerplate issues (ticket-99041042)
+- Fix string-concat issues (ticket-1510e5cc)
+- Fix unused-imports issues (ticket-e552615b)
+- Fix ai-boilerplate issues (ticket-b3ae0f86)
+- Fix smart-return-type issues (ticket-d1037f8c)
+- Fix string-concat issues (ticket-609c0fab)
+- Fix unused-imports issues (ticket-3ebd8fdd)
+- Fix ai-boilerplate issues (ticket-b87003d2)
+- Fix ai-boilerplate issues (ticket-db89d283)
+- Fix smart-return-type issues (ticket-cd1b6f20)
+- Fix unused-imports issues (ticket-34302951)
+- Fix duplicate-imports issues (ticket-75f7c2b8)
+- Fix unused-imports issues (ticket-8e26b0ed)
+- Fix magic-numbers issues (ticket-1722839b)
+- Fix llm-generated-code issues (ticket-d8ce3b10)
+- Fix string-concat issues (ticket-fd0965a0)
+- Fix unused-imports issues (ticket-aac67a2c)
+- Fix unused-imports issues (ticket-dff037fe)
+- Fix magic-numbers issues (ticket-b7797be1)
+- Fix magic-numbers issues (ticket-9b0c7658)
+- Fix unused-imports issues (ticket-cc2e353e)
+- Fix string-concat issues (ticket-50176518)
+- Fix magic-numbers issues (ticket-d9fadc4e)
+- Fix string-concat issues (ticket-30a21535)
+- Fix unused-imports issues (ticket-8b23a719)
+- Fix magic-numbers issues (ticket-85db1dac)
+- Fix unused-imports issues (ticket-89f61730)
+- Fix magic-numbers issues (ticket-8d7be98c)
+- Fix string-concat issues (ticket-5eb79314)
+- Fix magic-numbers issues (ticket-9ddd4894)
+- Fix smart-return-type issues (ticket-c85aaab2)
+- Fix unused-imports issues (ticket-27ba606b)
+- Fix magic-numbers issues (ticket-8ef56a87)
+- Fix smart-return-type issues (ticket-3f058adc)
+- Fix string-concat issues (ticket-66671a4f)
+- Fix unused-imports issues (ticket-f948231d)
+- Fix magic-numbers issues (ticket-c5bc23ac)
+- Fix llm-generated-code issues (ticket-255826ac)
+- Fix smart-return-type issues (ticket-1db80d8f)
+- Fix string-concat issues (ticket-8d0fb9b0)
+- Fix unused-imports issues (ticket-d6bef869)
+- Fix magic-numbers issues (ticket-98277254)
+- Fix unused-imports issues (ticket-c92e9bdf)
+- Fix ai-boilerplate issues (ticket-e26661c1)
+- Fix smart-return-type issues (ticket-c1e4c46e)
+- Fix magic-numbers issues (ticket-79e4a456)
+- Fix smart-return-type issues (ticket-be3f07ad)
+- Fix smart-return-type issues (ticket-0d4c8c76)
+- Fix string-concat issues (ticket-26249380)
+- Fix smart-return-type issues (ticket-e357004b)
+- Fix unused-imports issues (ticket-cf34ab93)
+- Fix smart-return-type issues (ticket-3b6369c5)
+- Fix smart-return-type issues (ticket-e81027f6)
+- Fix llm-hallucinations issues (ticket-0bf5dfa7)
+- Fix smart-return-type issues (ticket-b5828bd1)
+- Fix unused-imports issues (ticket-088c9715)
+- Fix smart-return-type issues (ticket-3a0b120f)
+- Fix string-concat issues (ticket-e2507aae)
+- Fix unused-imports issues (ticket-dddc1e79)
+- Fix magic-numbers issues (ticket-801d7441)
+- Fix smart-return-type issues (ticket-2a702143)
+- Fix smart-return-type issues (ticket-17036c34)
+- Fix smart-return-type issues (ticket-8b6049de)
+- Fix smart-return-type issues (ticket-2cc82f49)
+- Fix smart-return-type issues (ticket-1a0c2b98)
+- Fix smart-return-type issues (ticket-511f6124)
+- Fix smart-return-type issues (ticket-b78dbc51)
+- Fix smart-return-type issues (ticket-9acc51db)
+- Fix unused-imports issues (ticket-fdd18a06)
+- Fix ai-boilerplate issues (ticket-1268d95c)
+- Fix smart-return-type issues (ticket-d260acb0)
+- Fix llm-hallucinations issues (ticket-2e7c10b5)
+- Fix string-concat issues (ticket-e0f31a45)
+- Fix unused-imports issues (ticket-d6e45ad1)
+- Fix magic-numbers issues (ticket-359156e8)
+- Fix llm-generated-code issues (ticket-c8ce217a)
+- Fix unused-imports issues (ticket-9e280699)
+- Fix smart-return-type issues (ticket-aca7d7a9)
+- Fix string-concat issues (ticket-91ad1c1f)
+- Fix magic-numbers issues (ticket-97529746)
+- Fix smart-return-type issues (ticket-e0466fc2)
+- Fix string-concat issues (ticket-220e1c4c)
+- Fix unused-imports issues (ticket-68b7e53b)
+- Fix magic-numbers issues (ticket-6f454211)
+- Fix smart-return-type issues (ticket-ed676465)
+- Fix llm-hallucinations issues (ticket-dcc03c19)
+- Fix magic-numbers issues (ticket-782dc40a)
+- Fix llm-generated-code issues (ticket-c0a69197)
+- Fix ai-boilerplate issues (ticket-2a9af2c9)
+- Fix smart-return-type issues (ticket-e8c5867d)
+- Fix string-concat issues (ticket-95940f3f)
+- Fix unused-imports issues (ticket-2fcf4702)
+- Fix llm-generated-code issues (ticket-57272017)
+- Fix smart-return-type issues (ticket-2312bb66)
+- Fix magic-numbers issues (ticket-1b085b57)
+- Fix string-concat issues (ticket-bf1df627)
+- Fix unused-imports issues (ticket-3278b827)
+- Fix magic-numbers issues (ticket-d89f0697)
+- Fix llm-generated-code issues (ticket-6bef873e)
+- Fix wildcard-imports issues (ticket-632301bc)
+- Fix wildcard-imports issues (ticket-71797195)
+- Fix smart-return-type issues (ticket-71d8cf4f)
+- Fix unused-imports issues (ticket-52b89665)
+- Fix wildcard-imports issues (ticket-0584432e)
+- Fix wildcard-imports issues (ticket-29313dab)
+- Fix wildcard-imports issues (ticket-3f2517cb)
+- Fix wildcard-imports issues (ticket-f7f54966)
+- Fix smart-return-type issues (ticket-b037db5e)
+- Fix unused-imports issues (ticket-04c691a1)
+- Fix magic-numbers issues (ticket-40537e0f)
+- Fix unused-imports issues (ticket-ec6d262d)
+- Fix llm-generated-code issues (ticket-5e636ae8)
+- Fix unused-imports issues (ticket-c7778d50)
+- Fix llm-generated-code issues (ticket-990e48e1)
+- Fix unused-imports issues (ticket-ad161015)
+- Fix magic-numbers issues (ticket-c27a223f)
+- Fix llm-generated-code issues (ticket-7795bed1)
+- Fix smart-return-type issues (ticket-61b62b62)
+- Fix string-concat issues (ticket-c6604941)
+- Fix unused-imports issues (ticket-612a4154)
+- Fix magic-numbers issues (ticket-065abc62)
+- Fix ai-boilerplate issues (ticket-98ba531c)
+- Fix smart-return-type issues (ticket-9278955c)
+- Fix string-concat issues (ticket-55469c9e)
+- Fix unused-imports issues (ticket-a2a77d1a)
+- Fix magic-numbers issues (ticket-b758b57d)
+- Fix llm-generated-code issues (ticket-4debab76)
+- Fix unused-imports issues (ticket-de3dac3c)
+- Fix llm-generated-code issues (ticket-777617f3)
+- Fix llm-generated-code issues (ticket-3a8218f9)
+- Fix string-concat issues (ticket-517ab9a8)
+- Fix magic-numbers issues (ticket-5df0e093)
+- Fix llm-generated-code issues (ticket-f1c92c27)
+- Fix magic-numbers issues (ticket-d2308ee7)
+- Fix llm-generated-code issues (ticket-759e383c)
+- Fix string-concat issues (ticket-4976ef06)
+- Fix llm-generated-code issues (ticket-8b9be4b3)
+- Fix unused-imports issues (ticket-383192cb)
+- Fix smart-return-type issues (ticket-573ba79c)
+- Fix string-concat issues (ticket-5af98960)
+- Fix unused-imports issues (ticket-90d9dd67)
+- Fix llm-generated-code issues (ticket-993622dc)
+- Fix string-concat issues (ticket-48cbc948)
+- Fix llm-generated-code issues (ticket-3001e0e6)
+- Fix smart-return-type issues (ticket-e56b4116)
+- Fix unused-imports issues (ticket-6286358b)
+- Fix ai-boilerplate issues (ticket-5a627642)
+- Fix smart-return-type issues (ticket-cb843ab1)
+- Fix string-concat issues (ticket-334dbf4e)
+- Fix unused-imports issues (ticket-c45cc40e)
+- Fix ai-boilerplate issues (ticket-55eb2eed)
+- Fix smart-return-type issues (ticket-29661926)
+- Fix unused-imports issues (ticket-606424c7)
+- Fix ai-boilerplate issues (ticket-ace71cd4)
+- Fix smart-return-type issues (ticket-d0357c59)
+- Fix string-concat issues (ticket-0360a1fe)
+- Fix unused-imports issues (ticket-4744f89f)
+- Fix ai-boilerplate issues (ticket-fc1c75dc)
+- Fix smart-return-type issues (ticket-14079c50)
+- Fix ai-boilerplate issues (ticket-8cda0645)
+- Fix smart-return-type issues (ticket-b7a4bf92)
+- Fix unused-imports issues (ticket-e2dee270)
+- Fix magic-numbers issues (ticket-7c3fcd11)
+- Fix smart-return-type issues (ticket-d418ec5e)
+
 ## [Unreleased]
 
+## [0.1.50] - 2026-03-27
+
+### Docs
+- Update CHANGELOG.md
+- Update TODO.md
+- Update docs/README.md
+- Update project/context.md
+
+### Test
+- Update test_improvements.py
+- Update test_integration.py
+- Update test_markdown_integration.py
+- Update test_planfile_final.py
+- Update test_strategy.py
+- Update tests/llm_adapters.py
+
+### Other
+- Update examples/ecosystem/02_mcp_integration.py
+- Update examples/ecosystem/03_proxy_routing.py
+- Update examples/ecosystem/04_llx_integration.py
+- Update examples/interactive-tests/test_interactive_mode.py
+- Update examples/llx_validator.py
+- Update examples/test_litellm_integration.py
+- Update examples/test_llm_adapters.py
+- Update examples/test_strategies.py
+- Update mcp-server-example.py
+- Update planfile.yaml
+- ... and 82 more files
+
 ## [0.1.49] - 2026-03-27
 
 ### Docs

README.md

@@ -494,8 +494,14 @@ Contributions are welcome! Please feel free to submit a Pull Request. For major
 
 ## License
 
+Licensed under Apache-2.0.
+
+
 Apache License 2.0 - see [LICENSE](LICENSE) for details.
 
 ## Author
 
+Tom Sapletta
+
+
 Created by **Tom Sapletta** - [tom@sapletta.com](mailto:tom@sapletta.com)

TODO.md

@@ -17,9 +17,23 @@
 - [x] **Performance optimization**: Add timeout protection (60s) for example execution to prevent hangs
 - [x] **Documentation**: Create comprehensive PERFORMANCE.md guide with optimization details
 - [x] **Documentation**: Update README.md with enhanced examples section and CLI commands
+- [x] **Code Quality**: Fixed missing return type annotations in core modules (planfile/core/, planfile/cli/, planfile/analysis/)
+- [x] **Code Quality**: Replaced magic numbers with named constants in core modules
+- [x] **Code Quality**: Fixed LLM-style docstrings to follow Python conventions
+- [x] **Code Quality**: Reviewed and cleaned up imports (star imports are intentional re-exports for backward compatibility)
+- [x] **Code Quality**: Ran ruff --fix to auto-resolve 2496 issues (unused imports, f-string conversions)
 
 ## Pending Improvements
-- [ ] Consider implementing persistent cache warming for long-running processes
-- [ ] Add performance metrics collection for monitoring
-- [ ] Implement async I/O for large file operations (if needed)
-- [ ] Add connection pooling for external API calls (if needed)
+- [x] Consider implementing persistent cache warming for long-running processes
+- [x] Add performance metrics collection for monitoring
+- [x] Implement async I/O for large file operations (if needed)
+- [x] Add connection pooling for external API calls (if needed)
+
+## Notes on Examples Directory
+The following warnings in the examples/ directory are intentional and should not be fixed:
+- Example functions, standalone main functions, and module execution blocks are expected patterns in example code
+- These patterns make the examples more readable and educational
+- Warnings about unused imports and magic numbers in examples can be safely ignored
+
+
+# TODO

VERSION

@@ -1 +1 @@
-0.1.49
+0.1.50