feat: prioritize execution graph insights in generated readmes

Standard README order is now:
Overview
Architecture Overview
Execution Graph Summary
Execution Routes
Recommendations
Variable Reference
Task File Reference
Handlers

Author: jier

docsible/analyzers/recommendations/__init__.py

@@ -1,13 +1,14 @@
 from pathlib import Path
 
 from docsible.models.recommendation import Recommendation
+from docsible.models.severity import Severity
 
 from .enhancement import EnhancementRecommendationGenerator
 from .quality import QualityRecommendationGenerator
 from .security import SecurityRecommendationGenerator
 
 
-def generate_all_recommendations(role_path: Path) -> list[Recommendation]:
+def generate_all_recommendations(role_path: Path, analysis_report=None) -> list[Recommendation]:
     """Generate all recommendations for a role.
 
     Args:
@@ -30,6 +31,31 @@ def generate_all_recommendations(role_path: Path) -> list[Recommendation]:
     enhancement_gen = EnhancementRecommendationGenerator()
     all_recommendations.extend(enhancement_gen.analyze_role(role_path))
 
+    if analysis_report is not None:
+        metrics = analysis_report.metrics
+        if metrics.dynamic_boundaries:
+            all_recommendations.append(
+                Recommendation(
+                    severity=Severity.INFO,
+                    category="execution_graph",
+                    message=f"{metrics.dynamic_boundaries} dynamic execution boundaries need runtime review",
+                    rationale="Templated includes cannot be resolved to one static execution path.",
+                    remediation="Review the Execution Graph Summary and validate each dynamic path.",
+                    confidence=1.0,
+                )
+            )
+        if metrics.collection_dependencies:
+            all_recommendations.append(
+                Recommendation(
+                    severity=Severity.INFO,
+                    category="execution_graph",
+                    message=f"Role depends on {metrics.collection_dependencies} Ansible collections",
+                    rationale="Collection availability affects portability and runtime module resolution.",
+                    remediation="Pin and document collection requirements.",
+                    confidence=1.0,
+                )
+            )
+
     # Sort by severity (critical first)
     all_recommendations.sort(key=lambda r: r.severity.priority, reverse=True)
 

docsible/commands/document_role/orchestrators/role_orchestrator.py

@@ -85,7 +85,7 @@ def execute(self) -> None:
             self._validate_documentation(role_info, analysis_report, diagrams, dependency_data)
 
         # Step 7.5: Generate recommendations (use validated role_path from step 1)
-        recommendations = generate_all_recommendations(role_path)
+        recommendations = generate_all_recommendations(role_path, analysis_report)
 
         if self.context.analysis.apply_suppressions:
             from docsible.suppression.engine import apply_suppressions

docsible/templates/role/sections/adaptive_diagrams.jinja2

@@ -61,6 +61,16 @@ This role contains **{{ complexity_report.metrics.total_tasks }} tasks** across
 - Task Includes: {{ complexity_report.metrics.task_includes }}
 - Role Dependencies: {{ complexity_report.metrics.role_dependencies }}
 
+### Execution Graph Summary
+- Collection dependencies: {{ complexity_report.metrics.collection_dependencies }}
+- Conditional decision points: {{ complexity_report.metrics.conditional_decision_points }}
+- Statically reachable task files: {{ complexity_report.metrics.static_reachable_task_files }}
+- Dynamic boundaries: {{ complexity_report.metrics.dynamic_boundaries }}
+- Unknown boundaries: {{ complexity_report.metrics.unknown_boundaries }}
+- Handler notification edges: {{ complexity_report.metrics.notification_edges }}
+- Loop-bearing tasks: {{ complexity_report.metrics.loop_tasks }}
+- Orphan task files: {{ complexity_report.metrics.orphan_task_files }}
+
 {% if architecture_diagram %}
 ### Component Architecture
 This diagram shows the internal structure and data flow of the role:

docsible/templates/role/standard_modular.jinja2

@@ -13,24 +13,28 @@
 {% include 'sections/argument_specs.jinja2' %}
 {% endif %}
 {% endif %}
+{% if not no_diagrams %}
+{% include 'sections/complexity_analysis.jinja2' %}
+{% include 'sections/simplification_suggestions.jinja2' %}
+{% include 'sections/adaptive_diagrams.jinja2' %}
+{% include 'sections/integration_boundary.jinja2' %}
+{% endif %}
+{% if role.defaults or role.vars %}
+## Variable Reference
+{% endif %}
 {% if role.defaults %}
 {% include 'sections/defaults.jinja2' %}
 {% endif %}
 {% if role.vars %}
 {% include 'sections/vars.jinja2' %}
 {% endif %}
 {% if not no_tasks %}
+## Task File Reference
 {% include 'sections/tasks.jinja2' %}
 {% endif %}
 {% if not no_handlers %}
 {% include 'sections/handlers.jinja2' %}
 {% endif %}
-{% if not no_diagrams %}
-{% include 'sections/complexity_analysis.jinja2' %}
-{% include 'sections/simplification_suggestions.jinja2' %}
-{% include 'sections/adaptive_diagrams.jinja2' %}
-{% include 'sections/integration_boundary.jinja2' %}
-{% endif %}
 {% include 'sections/playbook.jinja2' %}
 {% include 'sections/dependencies.jinja2' %}
 <!-- DOCSIBLE END -->