Consolidate evaluation context merge order in the spec

specification.json

@@ -301,7 +301,7 @@
         {
             "id": "Requirement 3.2.2",
             "machine_id": "requirement_3_2_2",
-            "content": "Evaluation context MUST be merged in the order: API (global) - client - invocation, with duplicate values being overwritten.",
+            "content": "Evaluation context MUST be merged in the order: API (global; lowest precedence) - client - invocation - before hooks (highest precedence), with duplicate values being overwritten.",
             "RFC 2119 keyword": "MUST",
             "children": []
         },
@@ -393,7 +393,7 @@
         {
             "id": "Requirement 4.3.4",
             "machine_id": "requirement_4_3_4",
-            "content": "When `before` hooks have finished executing, any resulting `evaluation context` MUST be merged with the existing `evaluation context` in the following order: before-hook (highest precedence), invocation, client, api (lowest precedence).",
+            "content": "When `before` hooks have finished executing, any resulting `evaluation context` MUST be merged with the existing `evaluation context`.",
             "RFC 2119 keyword": "MUST",
             "children": []
         },

specification/README.md

@@ -1,7 +1,7 @@
 ---
 id: intro
-title: Intro
-description: An intro to the OpenFeature specification.
+title: Introduction
+description: An introduction to the OpenFeature specification.
 sidebar_position: 0
 ---
 

specification/sections/03-evaluation-context.md

@@ -40,7 +40,7 @@ see: [structure](../types.md#structure), [datetime](../types.md#datetime)
 
 > The evaluation context fields **MUST** have an unique key.
 
-The key uniquely identifies a field in the `evaluation context` and it should be unique accross all types to avoid any collision when marshelling the `evaluation context` by the provider.
+The key uniquely identifies a field in the `evaluation context` and it should be unique across all types to avoid any collision when marshalling the `evaluation context` by the provider.
 
 ### Merging Context
 
@@ -52,6 +52,17 @@ API (global) `evaluation context` can be used to supply static data to flag eval
 
 #### Requirement 3.2.2
 
-> Evaluation context **MUST** be merged in the order: API (global) -> client -> invocation, with duplicate values being overwritten.
+> Evaluation context **MUST** be merged in the order: API (global; lowest precedence) -> client -> invocation -> before hooks (highest precedence), with duplicate values being overwritten.
 
-Any fields defined in the client `evaluation context` will overwrite duplicate fields defined globally, and fields defined in the invocation `evaluation context` will overwrite duplicate fields defined in the globally or on the client.
+Any fields defined in the client `evaluation context` will overwrite duplicate fields defined globally, and fields defined in the invocation `evaluation context` will overwrite duplicate fields defined globally or on the client. Any resulting `evaluation context` from a [before hook](./04-hooks.md#requirement-434) will overwrite duplicate fields defined globally, on the client, or in the invocation.
+
+```mermaid
+flowchart LR
+  global("API (global)")
+  client("Client")
+  invocation("Invocation")
+  hook("Before Hooks")
+  global --> client
+  client --> invocation
+  invocation --> hook
+```

specification/sections/04-hooks.md

@@ -87,7 +87,9 @@ EvaluationContext | void before(HookContext, HookHints);
 
 #### Requirement 4.3.4
 
-> When `before` hooks have finished executing, any resulting `evaluation context` **MUST** be merged with the existing `evaluation context` in the following order: before-hook (highest precedence), invocation, client, api (lowest precedence).
+> When `before` hooks have finished executing, any resulting `evaluation context` **MUST** be merged with the existing `evaluation context`.
+
+Evaluation context merge order is defined in [Requirement 3.2.2](./03-evaluation-context.md#requirement-322).
 
 #### Requirement 4.3.5