diff --git a/docs/architecture-diagrams.md b/docs/architecture-diagrams.md index e78cb3d..202e3ff 100644 --- a/docs/architecture-diagrams.md +++ b/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 diff --git a/docs/images/F7-LAS-Agentic-Execution-Control-Loop.png b/docs/images/F7-LAS-Agentic-Execution-Control-Loop.png index f42c9e5..b1cb275 100644 Binary files a/docs/images/F7-LAS-Agentic-Execution-Control-Loop.png and b/docs/images/F7-LAS-Agentic-Execution-Control-Loop.png differ diff --git a/docs/images/F7-LAS-Executive-Control-Loop.png b/docs/images/F7-LAS-Executive-Control-Loop.png index 1e574ef..2ad39c0 100644 Binary files a/docs/images/F7-LAS-Executive-Control-Loop.png and b/docs/images/F7-LAS-Executive-Control-Loop.png differ diff --git a/scripts/validate-documentation.py b/scripts/validate-documentation.py index 8dac16d..b5d00a2 100755 --- a/scripts/validate-documentation.py +++ b/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: diff --git a/tests/test_documentation.py b/tests/test_documentation.py index 45cdfc2..a51a1c2 100644 --- a/tests/test_documentation.py +++ b/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")