Jier reorganize code base, 80 % done , 20% on another branch

[jier]

PR: Reorganize codebase + fix collection template bug + improve test coverage

What changed
Bug fix

• document_collection.py: collection roles were using the legacy monolithic standard.jinja2 template instead of standard_modular.jinja2. This caused malformed markdown tables (blank lines between header and separator row) whenever optional columns like Tags/Comments were absent. Now aligned with standalone role behavior.

Codebase reorganization (items B, D, E, F, G, H, I from FOLDER_REORGANIZATION_REPORT.md)

• diagrams/ — consolidated all diagram logic from diagram_builders/, utils/mermaid/, utils/mermaid_sequence/, and 4 scattered utils/*.py files into one module
• validation/ — renamed from validators/ to reflect it's a subsystem
• formatters/text/ and formatters/help/ — centralized formatters from 3 locations
• helpers/ — migrated guides/tips from help/, with new getting-started, smart-defaults, and troubleshooting guides
• utils/template/ and utils/validators/ — extracted from the utils/ catch-all
• commands/legacy/role.py — moved deprecated docsible role command to a clearly bounded location
• analyzers/complexity/phase.py — merged phase_detector/ into complexity analyzer

Test script modernization

• Rewrote test_orchestrator_cli.sh — replaced all docsible role + DOCSIBLE_USE_ORCHESTRATOR=true patterns with docsible document role, docsible analyze role, docsible validate role
• Deleted test_implementation_comparison.sh — premise (comparing two implementations) no longer applies

Test fixtures + coverage

• Added tests/fixtures/edge_case_role/ — covers block/rescue/always, include_role, import_role, handlers with listen aliases, 20+ defaults, runtime vars, missing optional dirs
• Added tests/end_to_end/test_edge_cases.py — 5 passing tests against the new fixture

Housekeeping

• Deleted .docsible/ at project root (duplicate of docsible/phase_patterns.example.yml)
• Added .docsible/ to .gitignore

Items deferred to next branch

• A — Consolidate duplicate complexity analysis systems (defaults/detectors/complexity.py + analyzers/complexity_analyzer/)
• C — Refactor document_role/ dual implementation (core.py + core_orchestrated.py)

Validation

• 990 tests passed · 0 mypy errors · ruff clean (as of 2026-03-07 baseline)