Add the skill lifecycle hooks to the Trace mappings

README.md

@@ -244,7 +244,7 @@ the one sending hook requests like the ones above. The **Guardian Agent** sits o
 other end of the wire and decides what happens next.
 
 A **hook** is a point in the Observed Agent's execution where it stops and asks before
-acting. `toolCallRequest` is one of ACS's sixteen native lifecycle hooks. Others fire at
+acting. `toolCallRequest` is one of ACS's nineteen native lifecycle hooks. Others fire at
 session start and end, before and after a turn, on knowledge retrieval, and around
 memory reads and writes.
 

docs/concepts/skill.md

@@ -30,4 +30,5 @@ Load is the runtime gate. It governs each activation in live context and carries
 
 - **Instrument**: the [`skillRegister`, `skillLoad`, and `skillUnload` hooks](../spec/instrument/hooks.md#skillregister).
 - **Inspect**: the `skill` [AgBOM component type](../spec/inspect/README.md).
+- **Trace**: the [span names and OCSF classes](../spec/trace/events.md) the three hooks emit.
 - See also [Capability](./capability.md), [Provenance](./provenance.md), and [Trust basis](./trust.md).

docs/spec/trace/events.md

@@ -34,6 +34,9 @@ The full mapping lives in [`trace/otel-mapping.json`](https://genai-security-pro
 | `steps/preCompact` | `acs.compact` | `acs.compact.entry_count`, `acs.compact.triggered_by` |
 | `steps/postCompact` | `acs.compact.complete` | `acs.compact.entry_count`; `acs.compact.lineage_depth_after` (optional) |
 | `steps/subagentStart`, `steps/subagentStop` | `acs.subagent`, `acs.subagent.end` | `acs.subagent.session_id`, `acs.subagent.parent_session_id`, `acs.subagent.intent_derivation` / `acs.subagent.outcome`, `acs.subagent.final_chain_hash` |
+| `steps/skillRegister` | `acs.skill.register` | `acs.skill.id`, `acs.skill.digest.algorithm`, `acs.skill.digest.value`, `acs.skill.declared_capabilities` |
+| `steps/skillLoad` | `acs.skill.load` | `acs.skill.id`, `acs.skill.digest.algorithm`, `acs.skill.digest.value`, `acs.skill.load_trigger`, `acs.skill.load_path` (skill ids, root first); `acs.skill.digest_verified`, `acs.skill.registration_ref` (optional) |
+| `steps/skillUnload` | `acs.skill.unload` | `acs.skill.id`, `acs.skill.reason`; `acs.skill.replaced_by` (optional) |
 | Decision (allow/deny/modify/ask/defer) | `acs.decision` (span event) | `acs.decision`, `acs.evaluator`, `acs.reasoning` (when present), `acs.confidence` (when present) |
 | `agbom/snapshot` | `acs.agbom` | `acs.agbom.format` (`canonical`/`cyclonedx`/`spdx`/`swid`), `acs.agbom.component_count` |
 | `agbom/changed` | `acs.agbom` | `acs.agbom.format` (`canonical`/`cyclonedx`/`spdx`/`swid`), `acs.agbom.change_reason` |
@@ -51,12 +54,14 @@ The full mapping lives in [`trace/ocsf-mapping.json`](https://genai-security-pro
 | `steps/sessionStart` | Authentication | 3002 |
 | `steps/agentTrigger`, `steps/userMessage`, `steps/agentResponse` | Application Activity | 6002 |
 | `steps/toolCallRequest`, `steps/toolCallResult` | Process Activity | 1007 |
+| `steps/skillLoad`, `steps/skillUnload` | Module Activity | 1005 (`activity_id` 1 load, 2 unload) |
 | `steps/knowledgeRetrieval`, `steps/memoryStore`, `steps/memoryContextRetrieval` | Datastore Activity | 6005 |
 | `steps/preCompact`, `steps/postCompact` | Datastore Activity | 6005 (compaction subtype) |
 | `steps/subagentStart`, `steps/subagentStop` | Authentication | 3002 (logon/logoff for the subagent's session) |
 | `steps/turnStart`, `steps/turnEnd` | Application Activity | 6002 |
 | Decision (deny/modify/ask/defer) | Detection Finding | 2004 |
 | `agbom/snapshot`, `agbom/changed` | Inventory Info | 5001 |
+| `steps/skillRegister` | Device Inventory Info | 5001 (skill enters the component set) |
 | `steps/sessionEnd` | Authentication | 3002 (logoff) |
 
 OCSF `severity_id` for decision events is set from the disposition:

docs/spec/trace/extend_ocsf.md

@@ -9,11 +9,13 @@ ACS events map to OCSF 1.5+ event classes. The normative class assignments and t
 | ACS step | OCSF class | Class UID |
 |---|---|---|
 | `steps/sessionStart`, `steps/sessionEnd`, `steps/subagentStart`, `steps/subagentStop` | Authentication | 3002 |
-| `steps/userMessage`, `steps/agentResponse`, `steps/turnStart`, `steps/turnEnd` | Application Activity | 6002 |
+| `steps/agentTrigger`, `steps/userMessage`, `steps/agentResponse`, `steps/turnStart`, `steps/turnEnd` | Application Activity | 6002 |
 | `steps/toolCallRequest`, `steps/toolCallResult` | Process Activity | 1007 |
+| `steps/skillLoad`, `steps/skillUnload` | Module Activity | 1005 (`activity_id` 1 load, 2 unload) |
 | `steps/knowledgeRetrieval`, `steps/memoryStore`, `steps/memoryContextRetrieval`, `steps/preCompact`, `steps/postCompact` | Datastore Activity | 6005 |
 | Decision (deny/modify/ask/defer) | Detection Finding | 2004 |
 | `agbom/snapshot`, `agbom/changed` | Inventory Info | 5001 |
+| `steps/skillRegister` | Device Inventory Info | 5001 |
 
 ## Severity mapping
 

specification/v0.1.0/trace/ocsf-mapping.json

@@ -34,6 +34,9 @@
         "steps/postCompact": { "class_uid": 6005, "class_name": "Datastore Activity", "activity_id": 99 },
         "steps/subagentStart": { "class_uid": 3002, "class_name": "Authentication", "activity_id": 1, "_note": "Subagent spawn opens a new session — modeled as Authentication/Logon for OCSF symmetry with sessionStart." },
         "steps/subagentStop": { "class_uid": 3002, "class_name": "Authentication", "activity_id": 2 },
+        "steps/skillRegister": { "class_uid": 5001, "class_name": "Device Inventory Info", "_note": "Registration admits a skill to the component set and persists its definition ref and digest to the AgBOM — modeled as Inventory Info, the class agbom/* already uses." },
+        "steps/skillLoad": { "class_uid": 1005, "class_name": "Module Activity", "activity_id": 1, "_note": "OCSF defines Module Activity as a process loading or unloading a module, and its required module object is the skill itself — not Process Activity, which needs a launched or terminated process that a skill load does not have; keeping loads off 1007 lets a reader tell a skill loading from the tool calls its actions raise." },
+        "steps/skillUnload": { "class_uid": 1005, "class_name": "Module Activity", "activity_id": 2 },
         "agbom/snapshot": { "class_uid": 5001, "class_name": "Inventory Info" },
         "agbom/changed": { "class_uid": 5001, "class_name": "Inventory Info" }
       }

specification/v0.1.0/trace/otel-mapping.json

@@ -89,6 +89,20 @@
           "span_name": "acs.subagent.end",
           "required_attributes": ["acs.subagent.session_id", "acs.subagent.outcome", "acs.subagent.final_chain_hash"]
         },
+        "steps/skillRegister": {
+          "span_name": "acs.skill.register",
+          "required_attributes": ["acs.skill.id", "acs.skill.digest.algorithm", "acs.skill.digest.value", "acs.skill.declared_capabilities"]
+        },
+        "steps/skillLoad": {
+          "span_name": "acs.skill.load",
+          "required_attributes": ["acs.skill.id", "acs.skill.digest.algorithm", "acs.skill.digest.value", "acs.skill.load_trigger", "acs.skill.load_path"],
+          "optional_attributes": ["acs.skill.digest_verified", "acs.skill.registration_ref"]
+        },
+        "steps/skillUnload": {
+          "span_name": "acs.skill.unload",
+          "required_attributes": ["acs.skill.id", "acs.skill.reason"],
+          "optional_attributes": ["acs.skill.replaced_by"]
+        },
         "agbom/snapshot": {
           "span_name": "acs.agbom",
           "required_attributes": ["acs.agbom.format", "acs.agbom.component_count"]