Correct control-loop Layer 7 semantics

docs/architecture-diagrams.md

@@ -6,28 +6,51 @@ implemented by this repository. The only executable path currently supported
 is the bounded synthetic workflow documented under
 [`examples/canonical-workflow/`](../examples/canonical-workflow/README.md).
 
+The diagrams preserve the seven distinct F7-LAS responsibility layers. To keep
+the enforced runtime sequence legible, they compress the handoffs into six
+workflow stages. This is workflow compression, not a merger or redefinition of
+the architectural layers.
+
 ## Executive control loop
 
-![F7-LAS executive control loop for agentic systems](images/F7-LAS-Executive-Control-Loop.png)
+![F7-LAS executive control loop showing six numbered runtime stages governed across all seven layers, conditional human approval, PDP and PEP gates, scoped execution, lifecycle-wide Layer 7 monitoring and governed feedback](images/F7-LAS-Executive-Control-Loop.png)
+
+[Open the full-resolution executive control-loop diagram](images/F7-LAS-Executive-Control-Loop.png)
 
 This view summarizes the governance path for an executive audience: mission
 context, an action proposal, policy decision, conditional human approval,
 enforcement, scoped execution, validation, monitoring, and governed feedback.
+Its numbered elements are runtime stages, not F7-LAS layer numbers: **six-stage
+runtime flow governed across all seven F7-LAS layers**.
+
 An approval-required outcome returns to the PDP for reevaluation. Only a PDP
 permit may proceed to PEP enforcement, and PEP authorization occurs before tool
 access or execution. Deny/block and clarify/refer-to-human are distinct terminal
-outcomes.
+outcomes. The lifecycle-wide **L7 Monitoring & Evaluation** band observes the
+complete flow, and the feedback band represents governed changes produced from
+Layer 7 observations.
 
 ## Layer-specific execution control loop
 
-![F7-LAS agentic execution control loop](images/F7-LAS-Agentic-Execution-Control-Loop.png)
+![F7-LAS technical execution control loop showing all seven responsibility layers, permit-only PDP-to-PEP routing, Layer 4 tool access inside the Layer 6 boundary, lifecycle-wide Layer 7 monitoring and evaluation, and governed feedback](images/F7-LAS-Agentic-Execution-Control-Loop.png)
+
+[Open the full-resolution technical control-loop diagram](images/F7-LAS-Agentic-Execution-Control-Loop.png)
 
 This view maps the same control loop to F7-LAS Layers 1–7. Layer numbers name
 responsibility domains; they do not require every runtime event to occur in
-numeric order. In particular, Layer 4 first defines a proposed tool action as
-data before Layer 5 authorization. Actual Layer 4 tool access may occur only
-after permit and successful PEP enforcement, within the applicable Layer 6
-execution boundary. Human approval never bypasses the PDP or PEP.
+numeric order. The six displayed runtime stages are workflow compression; they
+do not redefine or merge the seven architectural layers. In particular, Layer
+4 first defines a proposed tool action as data before Layer 5 authorization.
+Actual Layer 4 tool access may occur only after permit and successful PEP
+enforcement, within the applicable Layer 6 execution boundary. Human approval
+never bypasses the PDP or PEP.
+
+**L7 Monitoring & Evaluation** performs result validation, audit, telemetry,
+evidence, and assurance. Layer 7 observes the complete lifecycle: request,
+grounding, planning, proposed actions, policy decisions, approvals, denials,
+enforcement, execution, outputs, and feedback. **Feedback & Continuous
+Assurance** is governed feedback produced from Layer 7 observations. It is not
+an eighth layer and does not replace continuous monitoring.
 
 ## Canonical implementation alignment
 
@@ -39,8 +62,8 @@ execution boundary. Human approval never bypasses the PDP or PEP.
 | Conditional human approval | The canonical fixture creates deterministic synthetic approval evidence before the `policy_decision` record. It demonstrates binding and expiry enforcement, not an interactive approval service or verified human identity. |
 | PEP enforcement | Only a PDP permit reaches the PEP. The PEP verifies the decision and its action, approval, scope, policy, obligation, and expiry bindings before authorizing access. |
 | Scoped execution and tool access | Only after PEP authorization does the permit path enter the Layer 6 boundary and invoke one registered, synthetic, read-only in-process executor. It makes no network or external API call and independently rechecks the complete binding. |
-| Validation, monitoring, and evaluation | `execution_result` and `audit_event` records preserve the outcome; evidence verification and deterministic replay check their correlations and digests. This is not production telemetry or continuous monitoring. |
-| Feedback and continuous assurance | Test, review, policy, prompt, and process changes use the normal governed repository workflow. The implementation does not self-modify. |
+| Layer 7 monitoring and evaluation | `execution_result` and `audit_event` records preserve the outcome; evidence verification and deterministic replay check their correlations and digests. The diagram depicts lifecycle-wide monitoring, but this repository does not provide production telemetry or continuous monitoring. |
+| Feedback and continuous assurance | Test, review, policy, prompt, and process changes use the normal governed repository workflow. This governed feedback is produced from Layer 7 observations; it is not an eighth layer. The implementation does not self-modify. |
 
 The permit flow is therefore:
 
@@ -72,8 +95,8 @@ F7-LAS trademark rights or imply endorsement.
 
 | File | Dimensions | SHA-256 |
 |---|---:|---|
-| `images/F7-LAS-Executive-Control-Loop.png` | 1672 × 941 | `23449ac61fc65089d96956d5900916f69ee637960d83a46ff847093e3da59159` |
-| `images/F7-LAS-Agentic-Execution-Control-Loop.png` | 1672 × 941 | `9f4400b86796f1f047e51f595f416be5c2c398801a146778833a821277cdd8d6` |
+| `images/F7-LAS-Executive-Control-Loop.png` | 1920 × 1080 | `0e250eff8f021973608a77df78f01b276ed8c1147f25d24e493f9d96bc8b38ff` |
+| `images/F7-LAS-Agentic-Execution-Control-Loop.png` | 1920 × 1080 | `777f4a5de48dcc98ea0332358c0d9272ca4ca13d12889143a3e42464d4e6187d` |
 
 Legacy draft graphics were removed from the current documentation set because
 they contained ambiguous execution routing, private-reasoning terminology, or

scripts/validate-documentation.py

@@ -25,12 +25,26 @@
 IGNORED_DIRECTORIES = {".git", ".venv", "venv", "node_modules", "__pycache__"}
 EXPECTED_DIAGRAMS = {
     Path("docs/images/F7-LAS-Executive-Control-Loop.png"): (
-        "23449ac61fc65089d96956d5900916f69ee637960d83a46ff847093e3da59159",
-        (1672, 941),
+        "0e250eff8f021973608a77df78f01b276ed8c1147f25d24e493f9d96bc8b38ff",
+        (1920, 1080),
     ),
     Path("docs/images/F7-LAS-Agentic-Execution-Control-Loop.png"): (
-        "9f4400b86796f1f047e51f595f416be5c2c398801a146778833a821277cdd8d6",
-        (1672, 941),
+        "777f4a5de48dcc98ea0332358c0d9272ca4ca13d12889143a3e42464d4e6187d",
+        (1920, 1080),
+    ),
+}
+REQUIRED_DIAGRAM_ALT_TEXT = {
+    Path("docs/images/F7-LAS-Executive-Control-Loop.png"): (
+        "F7-LAS executive control loop showing six numbered runtime stages "
+        "governed across all seven layers, conditional human approval, PDP and "
+        "PEP gates, scoped execution, lifecycle-wide Layer 7 monitoring and "
+        "governed feedback"
+    ),
+    Path("docs/images/F7-LAS-Agentic-Execution-Control-Loop.png"): (
+        "F7-LAS technical execution control loop showing all seven "
+        "responsibility layers, permit-only PDP-to-PEP routing, Layer 4 tool "
+        "access inside the Layer 6 boundary, lifecycle-wide Layer 7 monitoring "
+        "and evaluation, and governed feedback"
     ),
 }
 RETIRED_DIAGRAMS = {
@@ -51,6 +65,13 @@
     "PEP authorization occurs before tool access or execution",
     "distinct terminal outcomes",
     "Agent Planning",
+    "workflow compression",
+    "six-stage runtime flow governed across all seven F7-LAS layers",
+    "L7 Monitoring & Evaluation",
+    "result validation, audit, telemetry, evidence, and assurance",
+    "Layer 7 observes the complete lifecycle",
+    "governed feedback produced from Layer 7 observations",
+    "not an eighth layer",
 }
 EXPECTED_RELEASE_VERSION = "4.0.0"
 CURRENT_WHITEPAPER_PATH = Path("docs/whitepaper/F7-LAS-Whitepaper-v4.0.pdf")
@@ -207,6 +228,13 @@ def validate_diagrams(root: Path) -> None:
             raise DocumentationError(f"retired legacy diagram returned: {relative}")
 
     guide = (root / "docs" / "architecture-diagrams.md").read_text(encoding="utf-8")
+    for relative, alt_text in REQUIRED_DIAGRAM_ALT_TEXT.items():
+        guide_target = relative.relative_to("docs").as_posix()
+        expected_reference = f"![{alt_text}]({guide_target})"
+        if expected_reference not in guide:
+            raise DocumentationError(
+                f"architecture diagram guide is missing accessible alt text: {relative}"
+            )
     normalized_guide = " ".join(guide.split())
     for notice in REQUIRED_DIAGRAM_NOTICES:
         if notice not in normalized_guide:

tests/test_documentation.py

@@ -66,7 +66,7 @@ def test_substituted_canonical_diagram_is_rejected(tmp_path: Path) -> None:
             MODULE.EXPECTED_DIAGRAMS[
                 Path("docs/images/F7-LAS-Executive-Control-Loop.png")
             ][0],
-            (1672, 941),
+            (1920, 1080),
         )
 
 
@@ -155,10 +155,25 @@ def test_control_loop_semantics_are_required() -> None:
         "PEP authorization occurs before tool access or execution",
         "distinct terminal outcomes",
         "Agent Planning",
+        "workflow compression",
+        "six-stage runtime flow governed across all seven F7-LAS layers",
+        "L7 Monitoring & Evaluation",
+        "result validation, audit, telemetry, evidence, and assurance",
+        "Layer 7 observes the complete lifecycle",
+        "governed feedback produced from Layer 7 observations",
+        "not an eighth layer",
     }
     assert expected <= MODULE.REQUIRED_DIAGRAM_NOTICES
 
 
+def test_control_loop_accessible_alt_text_is_required() -> None:
+    assert set(MODULE.REQUIRED_DIAGRAM_ALT_TEXT) == set(MODULE.EXPECTED_DIAGRAMS)
+    assert all(
+        "Layer 7" in alt_text
+        for alt_text in MODULE.REQUIRED_DIAGRAM_ALT_TEXT.values()
+    )
+
+
 def test_clean_user_gate_rejects_substituted_opa(tmp_path: Path) -> None:
     fake_opa = tmp_path / "opa"
     fake_opa.write_text("#!/bin/sh\necho 'Version: 1.20.2'\n", encoding="utf-8")