Repository navigation
[Bug] Skill lifecycle hooks missing from the trace mappings, acs.md, and the Trace pillar docs #58
Description
The three skill lifecycle hooks (skillRegister, skillLoad, skillUnload) are present in hooks.md, in the specification.md taxonomy table, and as schemas under specification/v0.1.0/hooks/. They are absent from six other surfaces that restate the hook set, two of which are normative.
Found while reviewing #20, whose FAQ correctly states 19. The suite is green on all of this (198 passed).
Normative gaps
specification/v0.1.0/trace/otel-mapping.json and specification/v0.1.0/trace/ocsf-mapping.json each enumerate 16 steps/* keys and contain none of the three skill hooks.
$ python3 -c "import re;print(len(set(re.findall(r'\"(steps/[A-Za-z]+)\"', open('specification/v0.1.0/trace/otel-mapping.json').read()))))"
16
Both files apply to ACS-Trace, and otel-mapping.json states that "v0.1.0 conformance requires that a deployment emitting OTel for the Trace pillar uses these span names and required attributes verbatim." conformance.md:19 says the skill hooks SHOULD be implemented. So a deployment that implements skillRegister and claims ACS-Trace has no normative span name or class_uid to emit. Two conformant implementations can emit incompatible telemetry for the same hook and nothing adjudicates.
The skillRegister case is the one worth caring about, because a denied skillRegister is a malicious skill definition blocked at the vetting gate, which is exactly the event a SIEM should receive.
Documentation gaps
docs/acs.md:11says "16 native lifecycle hooks" and enumerates 16 names.grep -c "skillRegister\|skillLoad\|skillUnload" docs/acs.mdreturns 0. This is the ACS overview page, so it is where a reader learns what ACS-Core is, and it currently tells them skill hooks are not part of v0.1.0.docs/spec/trace/events.mdhas zero occurrences of "skill". Its OTel span table and OCSF class table both stop atsubagentStart/subagentStop.docs/spec/trace/extend_ocsf.mdhas zero occurrences of "skill".
hooks.md:3 says 19. So the published site currently states both 16 and 19 in prominent places.
Why CI does not catch it
tests/test_hook_taxonomy.py derives the hook set from specification/v0.1.0/hooks/*.json and compares it against two files:
SPECIFICATION = ROOT / "docs" / "spec" / "instrument" / "specification.md"
HOOKS_PAGE = ROOT / "docs" / "spec" / "instrument" / "hooks.md"Those are the two files that are already correct. The guard's premise is that the hook set is stated in three places. It is stated in at least nine, and four of the unguarded ones are wrong today.
Suggested fix
- Add the three hooks to
otel-mapping.jsonandocsf-mapping.jsonwith span names and class_uids consistent with the existing 16. - Update
docs/acs.md:11,docs/spec/trace/events.md, anddocs/spec/trace/extend_ocsf.md. - Widen the guard so it derives the restating surfaces rather than hardcoding two paths. Matching every
steps/<name>occurrence acrossdocs/andspecification/v0.1.0/trace/would have caught all six.
Item 3 matters more than the other two. Without it the next hook addition reopens the same gap, which is what happened here.
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsDone
Activity
sabasiddique1 commentedon Sep 9, 2026
Picking this up. I reproduced all six gaps on a fresh clone: both trace mappings hold 16
steps/*keys,acs.md:11/events.md/extend_ocsf.mdhave no skill rows, andtest_hook_taxonomy.pyonly guards the two surfaces that are already right.I've got a fix working locally, test first. The widened guard now discovers every surface that restates the hook set under
docs/andspecification/v0.1.0/trace/:steps/prefix only, soagbom/*stays out)On the unfixed tree it goes red on all six. With the fix, the three skill hooks are in
otel-mapping.jsonandocsf-mapping.json(span names and required attributes taken from each hook's ownrequiredfields), andacs.md,trace/events.md,trace/extend_ocsf.mdare updated. Suite is green. Strict MkDocs build passes.One extra thing the guard caught that isn't in the list above:
extend_ocsf.mdalso omitssteps/agentTrigger. Included it; I'll call it out separately in the PR.The OCSF class choice for the skill hooks is a judgment call, so I'm flagging it as a reviewer decision in the PR rather than deciding alone.
Opening the PR shortly, would appreciate a look when it's up.
[-]Skill lifecycle hooks missing from the trace mappings, acs.md, and the Trace pillar docs[/-][+][Bug] Skill lifecycle hooks missing from the trace mappings, acs.md, and the Trace pillar docs[/+]Add the skill lifecycle hooks to the Trace mappings (GenAI-Security-P…