[sabasiddique1]

What changed

skillRegister, skillLoad, and skillUnload had no entry in otel-mapping.json or ocsf-mapping.json, so a deployment claiming ACS-Trace had no normative span name or class_uid for a skill event. This adds both mappings, renders them on the Trace Events and Extending OCSF pages, links them from the Skill concept page, and widens tests/test_hook_taxonomy.py to guard every surface that restates the hook set. docs/acs.md keeps integration's version, which #21 already updated.

Which issue does this implement

Closes #57, closes #58.

• This is an editorial correction (typo, grammar, link, formatting) with no change in meaning, so it needs no issue

Base branch

• integration, because this touches the specification, schemas, a reference implementation, an adapter, tests, or CI
• main, because every changed path is on the documentation lane allowlist in CONTRIBUTING.md

Type of change

• Specification change (schema, hooks, events, AgBOM)
• Reference implementation or adapter
• Documentation
• Tooling or CI
• Governance (licensing, security policy, contributor docs)

Specification changes

• I opened a Discussion before this PR
• Schema changes validate against the JSON Schema spec
• I described the impact on downstream implementers below

Breaking for implementers? No. Nothing on the wire changes. Three new keys appear in each mapping's default; existing keys, span names, and class assignments are untouched.

OTel: acs.skill.register, acs.skill.load, acs.skill.unload. Required attributes come only from fields each hook schema requires. The digest maps to two attributes, acs.skill.digest.algorithm and acs.skill.digest.value, so every exporter emits the same values. acs.skill.load_path stays required because cascade containment is the reason the hook carries it.

OCSF, as the Spec leads decided: skillLoad and skillUnload map to Module Activity (1005) with activity_id 1 (Load) and 2 (Unload). Its required module object is the skill itself, and keeping loads off Process Activity (1007) lets a reader tell a skill loading from the tool calls its actions raise. skillRegister maps to 5001, labeled Device Inventory Info, its name in every OCSF release. The agbom/* rows still say Inventory Info until #121 renames them. A denied skillRegister still surfaces as Detection Finding 2004 through decision_class.

Guard

The first commit widens the test and fails on exactly the surfaces #58 lists, plus one it did not: the class table in extend_ocsf.md never listed steps/agentTrigger. That row is fixed here too.

Two maintainer commits harden the guard. Every failure message now says how to fix it. A page that lists a deliberate subset or names a proposed hook goes in SUBSET_SURFACES or PROPOSED_HOOKS with a reason. The reference pattern skips globs, paths, and anchors. The count check skips subset counts, reads spelled-out numbers, and scans README.md, which still said sixteen native hooks and now says nineteen.

Not changed

The AgBOM trigger list in docs/spec/inspect/README.md omits skill; filed as #120. The "Sixteen" in specification/proposals/skill-lifecycle/README.md describes the pre-skill state and is correct in context.

I tested this

• I synced my branch with the base branch before opening this
• uv run pytest -v passes on my machine
• uv run mkdocs build --strict passes on my machine

Checklist

• Commits are signed off with git commit -s (required by the DCO)
• Prose follows STYLE.md
• No secrets, tokens, or internal URLs in the diff

Security

• This change has no security impact

[sabasiddique1]

Retargeted to integration per #64 and synced; 283 guards pass (1 skipped on macOS), mkdocs build --strict clean.

Two decisions needed from the Spec leads (@bar-capsule @afogel):

1. OCSF class for skill hooks — 5001 Inventory Info + 1007 Process Activity as implemented, or 1005 Module Activity (Load=1 / Unload=2)? I will update within the hour either way.
2. status:accepted on [Docs] Skill lifecycle hooks have no ACS-Trace mapping (no OTel span, no OCSF class) #57 / [Bug] Skill lifecycle hooks missing from the trace mappings, acs.md, and the Trace pillar docs #58 — both already carry scope:in-focus and priority:P2.

RESTATING_THRESHOLD = 8 can become an explicit list if preferred. The agentTrigger row in extend_ocsf.md is a plain omission fix. OCSF 1.5 naming (5001 → "Device Inventory Info") and the missing skill entry in the AgBOM trigger list are out of scope here and filed as #120 and #121.

[github-actions]

Thanks for this. It is queued rather than ignored.

This pull request does not reference an issue carrying status:accepted, so a maintainer has not looked at it yet and will not until the underlying issue is triaged. Nothing here is rejected. See Current Priority Scope for what the project is working on, and help wanted for work that is already accepted.

If this is an editorial correction, tick that box in the description and this comment stops applying.

[bar-capsule]

@sabasiddique1 sorry for the long wait. Decisions, plus two things for the same update:

1. skillLoad and skillUnload: 1005 Module Activity, activity_id 1 (Load) and 2 (Unload). OCSF defines it as a process loading or unloading a module, and its required module object is the skill itself. Process Activity requires a process that was launched or terminated, which a skill load doesn't have, and keeping loads off 1007 lets a reader tell a skill loading from the tool calls its actions raise. Please update the skillLoad _note to match, and the rows in events.md and extend_ocsf.md.
2. skillRegister: 5001, labeled "Device Inventory Info". We're pinning the mapping to OCSF 1.9.0 under [Docs] OCSF 1.5 renames class 5001 to "Device Inventory Info"; Trace docs still say "Inventory Info" #121, and that is 5001's official name in every OCSF release.
3. docs/acs.md conflicts with integration. Set the ACS-Core floor: MODIFY and system/ping to SHOULD, Wrapped MCP and subagentStart as conditional MUSTs #21 rewrote the ACS-Core line and it already lists skillRegister/Load/Unload, so please keep integration's version of that line.
4. digest in skill-register and skill-load is an object with algorithm and value. Please map it as two attributes, acs.skill.digest.algorithm and acs.skill.digest.value, so every exporter emits the same values.

The new taxonomy tests are a good guard: I checked that they catch the missing skill rows. Happy to approve once these are in.

[sabasiddique1]

@bar-capsule thanks, that's clear. Pushing all four tomorrow.

[sabasiddique1]

@bar-capsule pushed: 1005 for load/unload with activity_id 1 and 2, "Device Inventory Info" on 5001, integration's acs.md line kept, and the digest split into acs.skill.digest.algorithm and acs.skill.digest.value. pytest and mkdocs --strict pass.

[github-actions]

This pull request's description says it closes #57 #58, which is on the project roadmap. When it merges, GitHub closes that issue and the roadmap counts it as delivered. Please confirm the change delivers the whole issue before merging.

[rocklambros]

@sabasiddique1 I reviewed this tonight, and it's ready from my side. Thank you for turning Bar's four asks around in a day.

What I checked

• Required attributes. I checked every required_attributes entry against the three skill schemas on integration. Each one comes from a field the schema requires: skill_id, declared_capabilities and definition.digest.{algorithm,value} for register, skill_id, digest.{algorithm,value}, load_trigger and load_path for load, and skill_id and reason for unload. That's the mistake we're fixing in [Bug]: otel-mapping.json requires acs.capability on gen_ai.tool.call, but capability is optional in tool-call-request.json #227, and this PR doesn't repeat it.
• Bar's four asks. All four are in: 1005 Module Activity with activity_id 1 and 2, 5001 labeled "Device Inventory Info", docs/acs.md left at integration's version, and the digest split into acs.skill.digest.algorithm and acs.skill.digest.value. The skillLoad note was updated too.
• The OCSF names. I checked them against the OCSF schema repository at the 1.0.0, 1.1.0, 1.5.0 and 1.9.0 tags. Class 1005 is "Module Activity", with 1 = Load and 2 = Unload. Class 5001 is "Device Inventory Info" at every tag I checked.
• Branch and checks. Your branch was current with integration, and all checks were green.

What I pushed to your branch, and why

I pushed two small commits, so please pull before you push again.

1. README.md hook count. The README said "sixteen native lifecycle hooks". The schemas define nineteen, so I changed it to nineteen. Your guard didn't catch this, because it only scanned docs/ and only matched digits.

2. Failure messages in tests/test_hook_taxonomy.py. Your four tests catch the right things. My question was what the next person sees when one fails, and I tried a few edits that the upcoming [Bug]: otel-mapping.json requires acs.capability on gen_ai.tool.call, but capability is optional in tool-call-request.json #227, [Bug]: acs.decision trace event cannot carry reason_codes, policy_references, cited_provenance_ids, or chain_hash, so replay from the trace alone is not possible #228 and Export Guardian traces as OTLP to a file and over HTTP #244 changes will plausibly make. Two of them failed when they shouldn't have:

   • A path or a glob, like #steps/toolcallrequest or steps/toolCall*, was read as an unknown hook.
   • A sentence like "these 2 native hooks" failed the count check.

   None of the messages said how to fix the problem.

   So the guard now does five things:

   • Every message says what to do.
   • A page that lists a subset on purpose, or names a hook proposed for later, goes in SUBSET_SURFACES or PROPOSED_HOOKS with a reason. Both start empty, and a new test rejects an entry with no reason or one that's no longer needed.
   • The reference pattern skips globs, paths and anchors.
   • The count check skips small subset counts, reads spelled-out numbers like "sixteen", and also scans README.md.
   • A renamed heading now fails with the heading's name instead of a bare StopIteration.

I tested the guard by putting "sixteen" back in the README. It failed with this message: README.md: sixteen. Update the count. The full suite passes (907 passed, 1 skipped), and mkdocs build --strict is clean.

I also updated the PR description, because it becomes the squash commit message. It still said skillLoad maps to 1007 and that docs/acs.md changes, which Bar's decision replaced. Please check that it still says what you mean.

One thing I'm leaving as it is

The skillRegister note still says "modeled as Inventory Info", and the agbom/* rows still use the old name. So 5001 shows up under two names for a short time. My #121 PR renames the agbom/* rows, and I'll fix that note in the same PR. You don't need to change anything.

Next step

I pushed the last commit, so the branch rules say someone else has to approve. @bar-capsule, you said you'd approve once your four asks were in. They are, and the only new changes are the two commits above. When Bar approves, I'll squash it with Closes #57 and Closes #58 and add the sign-offs.

[rocklambros]

For the record, since this merged with the admin bypass on October 12 and I owe a note on why.

I pushed the last two commits here (the hook-taxonomy guard fixes), so my approval couldn't count, and I merged before Bar's approval came in because the trace work queued behind it (PR #261, PR #244 and issue #228) needed these mappings. Here's what was in place at merge: Saba had addressed all four of Bar's asks on October 9, my two commits only touched the guard, and CI was green on the merged head, 0775c83 (test, build and closing-choice).

@bar-capsule, if you get a chance to look at it after the fact, anything you find goes into a follow-up PR.