docs(spec): clarify resource event types — add RESOURCE_CREATED, RESOURCE_DELETED, RESOURCE_MOVED

docs/specification.md

@@ -46039,7 +46039,10 @@ CleverAgents emits domain events for every significant state change. Events flow
 
     <span style="color: #888;"># Resource events</span>
     RESOURCE_ACCESSED = <span style="color: #66cc66;">"resource.accessed"</span>
+    RESOURCE_CREATED = <span style="color: #66cc66;">"resource.created"</span>
     RESOURCE_MODIFIED = <span style="color: #66cc66;">"resource.modified"</span>
+    RESOURCE_DELETED = <span style="color: #66cc66;">"resource.deleted"</span>
+    RESOURCE_MOVED = <span style="color: #66cc66;">"resource.moved"</span>
     RESOURCE_INDEXED = <span style="color: #66cc66;">"resource.indexed"</span>
 
     <span style="color: #888;"># Correction events</span>
@@ -46136,6 +46139,37 @@ CleverAgents emits domain events for every significant state change. Events flow
         <span style="color: magenta; font-weight: 600;">return</span> <span style="color: cyan;">self</span>._subject
 </code></pre></div>
 
+#### Resource Event Types and ResourceFileWatcher Behavior
+
+> **Clarification added in response to issue [#8018](https://git.cleverthis.com/cleveragents/cleveragents-core/issues/8018).**
+> Tracked for implementation in [#8025](https://git.cleverthis.com/cleveragents/cleveragents-core/issues/8025).
+
+The full set of resource `EventType` values is:
+
+| `EventType` member | String value | Description |
+|---|---|---|
+| `RESOURCE_ACCESSED` | `"resource.accessed"` | A resource was read or queried. |
+| `RESOURCE_CREATED` | `"resource.created"` | A new resource file was created on disk. |
+| `RESOURCE_MODIFIED` | `"resource.modified"` | An existing resource file was modified in place. |
+| `RESOURCE_DELETED` | `"resource.deleted"` | A resource file was removed from disk. |
+| `RESOURCE_MOVED` | `"resource.moved"` | A resource file was renamed or relocated. |
+| `RESOURCE_INDEXED` | `"resource.indexed"` | A resource was (re-)indexed into the context store. |
+
+**`ResourceFileWatcher` mapping (required behavior):**
+
+`ResourceFileWatcher` monitors the filesystem using a `FileChangeType` enumeration produced by the underlying watcher library. It **MUST** map each `FileChangeType` to a distinct `EventType` as follows:
+
+| `FileChangeType` | Required `EventType` emitted |
+|---|---|
+| `CREATED` | `RESOURCE_CREATED` |
+| `MODIFIED` | `RESOURCE_MODIFIED` |
+| `DELETED` | `RESOURCE_DELETED` |
+| `MOVED` | `RESOURCE_MOVED` |
+
+**Design rationale:** The `EventType` value alone MUST be sufficient for any subscriber to determine the nature of a filesystem change. Subscribers MUST NOT need to inspect `details["change_type"]` or any other payload field to distinguish between created, modified, deleted, or moved events. Encoding the change semantics in the event type (rather than a payload field) keeps subscriber logic simple and enables type-safe subscription via `EventBus.subscribe(EventType.RESOURCE_DELETED, handler)`.
+
+> **Historical note:** Prior to this clarification, `ResourceFileWatcher` emitted `RESOURCE_MODIFIED` for all filesystem change types (created, modified, deleted, moved) and included a `change_type` key in `details` so subscribers could distinguish them. This was a workaround for the missing enum variants and is **no longer the intended design**. New and updated implementations MUST use the distinct event types listed above.
+
 #### LLM Call Tracing
 
 Every LLM invocation is traced with full context for debugging and cost tracking: