fix(claude-ops): recover the bundled-skill lane on 2.1.263 and report integrity per lane

[kyle-sexton]

Closes #4048

Summary

The inventory extractor's bundled-skill lane returned empty on Claude Code 2.1.263 (a bytecode-fragmented bundle whose readable source is scattered across thousands of small printable runs, with an ESM export list in place of the CJS getter), so every native-overlap run reported broken. This PR recovers the lane, reports integrity per lane in both engines, closes the reverse-parity blind spot, seeds the two missing pairs, and releases claude-ops 0.54.0 (main released 0.49.0 through 0.53.0 while this was in flight; all merged in). It also graduates the effort's approved plan into docs/specs/ and trims the audit-native-overlap description under the Skills API cap. Unit 1 of the native-overlap effort tracked in #4047; units 2 to 9 are deferred as filed, each re-anchored by a comment.

Fix

inventory.py

• Region rule: from the first bundle marker to end of file, every printable run of at least 256 bytes, joined with newlines, in one regex pass; sources.binary records runs, joined_bytes, region_rule, runs_below_floor (registration tokens under the floor, counted rather than lost, and degrading the bundled-skill lane when positive), and elapsed_seconds. A build with no marker keeps the largest-run fallback.
• Three registrar routes in order: CJS getter, ESM export list (<ident> as registerBundledSkill), canary registration; bundled_skill_notes.registrar_route records which resolved. The registrar-shaped-export advisory sees both export shapes; the known set gains registerDesignCanvasSkill and registerWorkflowAuthoringSkill.
• Computed names resolve by locality (nearest preceding ident="kebab" binding, a farther one never wins; a single-character identifier only within a 64 KiB window). A loop or template-literal registration is a dynamic_roster note; a registrar-identifier call whose object has no name: is another module's function and is counted apart.
• Per-registration user_invocable, disable_model_invocation, terminal_oriented, survives_kill_switch; a function-valued field reads as true with the key under flag_driven, and flag_driven is part of a registration's identity.
• Two distinct registrations sharing a name are both kept as a list under that name with collision: true (design on 2.1.263: the canvas skill and the claude.ai/design hub); registrations_of(entry) reads either shape.
• integrity.lanes (builtin_commands, bundled_skills, plugin_backed), top-level status the worst lane; top-level broken only when every lane is broken or the binary is unreadable. plugin_backed gains a canary (security-review). Exit mappings unchanged; --self-check prints each lane.
• VALIDATED_AGAINST is 2.1.263.

overlap.py

• detect reads the lanes, reports per-lane floors (a lane's counts are totals only when the lane is ok and no run-wide advisory such as an unvalidated CLI version stands; a lane-attributed advisory degrades only its own lane), and marks every candidate re_derivable (false when the lane its seeded or observed class maps to is broken, both directions on a class collision; null for session-provided and marketplace classes). A name collision lists every registration with its invocation mode. An inventory without lanes keeps the previous reading.
• self-check flags a description that names a native surface by class and kind inside a when/where/if clause with an availability word and no gate token in that clause, as an advisory (exit 3).
• --upstream-sha repeats, one value per upstream repository the store cites (the store records commits in two repositories, so one value always drifted).

Also: two seeded pairs (doctor and skill-doctor against claude-ops:audit-skill-visibility), the inventory skill's integrity table and the audit-native-overlap detection posture reworded per lane, reference/extraction.md rewritten for the region, registrar, locality, collision, and lane rules, the inventory eval for degraded counts updated, the audit-native-overlap description trimmed to 1,020 characters with every claim and trigger phrase kept (and its row dropped from scripts/skill-description-cap-baseline.txt, which the changed-skills check requires once a description no longer breaches), CHANGELOG entry, version 0.53.0 to 0.54.0.

docs/specs/native-overlap-route-to-compose.md and docs/specs/native-overlap-integration-design.md: the approved plan and design resolution, graduated from the pruned topic slice per the topic-docs convention, with a ## Status section that re-anchors the deferred units on native-references 1.1.0 and the 19-row store.

Deviations from the plan, recorded in the spec: the planned marker-scoped constant map cannot work (the hoisted constants sit about 8.7 MB and 173 marker occurrences ahead of their registrations on 2.1.263), so the locality rule above replaced it; the self-check sanity criterion needs both upstream SHAs; measured wall clock is about 14 s, so the bound is stated as 30 s rather than 15 s.

Review round: the three Codex findings (flag-driven twins deduped, below-floor literals not degrading the lane, per-lane count labels ignoring run-wide drift) are fixed in f60ef12 with a test each; threads resolved.

Verification

Seeded pairs quoted per the plan:

{ "native": { "name": "doctor", "class": "bundled-skill" },
  "component": { "plugin": "claude-ops", "skill": "audit-skill-visibility", "kind": "skill" },
  "why": "doctor's checkup covers unused extensions and skill visibility as one pass of a broader health check; the audit asks the whole-fleet visibility question." }
{ "native": { "name": "skill-doctor", "class": "builtin-command" },
  "component": { "plugin": "claude-ops", "skill": "audit-skill-visibility", "kind": "skill" },
  "why": "Both ask which loaded skills go unused and what each costs; the built-in is a one-shot report that excludes bundled skills, the audit is the fleet-wide visibility question." }

Run locally on the Linux ELF 2.1.263 build in this container, on the merged head:

• python3 plugins/claude-ops/skills/inventory/scripts/test_inventory.py: 60 tests OK (six test_read_bundle cases, routes, locality, invocation fields, collisions, lanes, below-floor degradation).
• python3 plugins/claude-ops/skills/audit-native-overlap/scripts/test_overlap.py: 99 tests OK (main's Boundary-naming parity tests plus this PR's lanes, re_derivable, collision evidence, run-wide versus lane-attributed count labels, presence-mention advisory with negative fixtures, repeatable --upstream-sha).
• inventory.py --binary-only --out /tmp/inv.json: 13.6 to 14.7 s wall clock; 35 bundled-skill names, design as a two-registration list with disable_model_invocation [false, true], doctor model-disabled and terminal-oriented, simplify and run with no invocation-control field, registrar_route esm-export, plugin_backed holds security-review, no ehrpd, runs_below_floor 2.
• inventory.py --self-check: DEGRADED with lanes ok/degraded/ok; the bundled advisories are the dynamic roster (2 registrations) and the 2 below-floor literals, exit 3.
• overlap.py self-check --upstream-sha ed404106fcd80ba98ecb7c851e531dcb626d13b7 --upstream-sha d7dbd9a09f59775726ed14bbea8fc9dfdff62f7b: exit 3, no problems, exactly three advisories on the 19-row store (version drift 2.1.232/251/252 vs 2.1.263, and the two presence-mention advisories naming visualization:visualize and prototype:explore-directions).
• overlap.py generate --check: in sync, 19 rows. jq '.pairs | length' on the canonical pairs prints 16. scripts/validate-plugins.sh: passes.
• scripts/run-ruff.sh check and format --check on both script directories: clean. check-evals-quality.sh on the inventory evals: PASS. markdownlint and typos on the touched markdown and the two specs: clean. scripts/check-purged-em-dashes.sh: no em dashes. scripts/check-changed-skills.sh origin/main: 0 failed (check-skill passes on audit-native-overlap and inventory; three pre-existing advisory warnings remain on the former).
• scripts/affected-tests.sh --run: every selected shell suite passes except plugins/claude-ops/skills/plugins/scripts/cache-content-check.test.sh, whose process-budget probe measures -1 in this container (its pid-stamped PS4 does not reach the traced shell). The same suite fails identically on main's copy of that directory, which this PR does not touch, so it is an environment finding of this sandbox, not this change's. The 14 Python suites the runner lists as NOT RUN were run directly where relevant (the two above plus test_audit_skill_visibility.py, 96 OK).
• CI: the ci workflow passed in full on head ef9b96f (run 34626653025: lint, hook-utils, test-linux 0 to 3, test-windows, ci-status); the one earlier red lane (changed-skills on 3f2f538) was the stale baseline row, fixed in 5490b5f. Head a6c2ff3 merges main's 0.53.0 release and moves this entry to 0.54.0; the three Python suites, markdownlint, the em-dash gate, validate-plugins, and the changed-skills check pass on it.
• Windows: no Windows host with the 2.1.263 claude.exe was reachable from this session; the PE container path is covered by a byte-layout fixture and the CHANGELOG states the Linux-only basis.

Contract slice: pruned in daf8d692 per the topic-docs convention (pre-prune commit eab22841); its durable outcomes are the two spec files above and the sub-issue comments.

Related

• Refs Epic: native-overlap tooling fix and route-to-compose sweep #4047 (container), claude-ops/audit-native-overlap: add the integration axis to the store and the wrap and suggest grammars to native-references #4049 (unit 2, C4, deferred), claude-ops: sweep unit, bake the doctor and skill-doctor integrations into the three audit skills #4050 to session-flow: sweep unit, move the three export suggestion sites to the suggest grammar #4056 (sweep units, deferred with scope notes).

🤖 Generated with Claude Code

https://claude.ai/code/session_01JEFsqe8fDbDjSFx79hVB9e

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-11T16:44:36.470398Z	ee0af40	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ee0af40488

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[kyle-sexton]

CI note on head a6c2ff3: test-linux (3) failed in plugins/claude-ops/hooks/session-event-log.test.sh ("33 parallel fires → 33 lines: expected '33', got '32'", with a printf: write error: Broken pipe from one of the parallel writers).

This is not this PR's failure:

• The PR does not touch plugins/claude-ops/hooks/; that directory is byte-identical to main on this head (git diff --stat origin/main HEAD -- plugins/claude-ops/hooks/ is empty).
• The same shard passed on the previous head ef9b96f (run 34626653025), which carried the identical hooks directory; the only change between the two heads is the merge of main's 0.53.0 release and the version-ladder bump.
• The suite passes 5 of 5 consecutive runs locally on this head (68 assertions each).

It reads as a timing race in the test's 33-way parallel writer fan-out (one writer's stdin pipe closed before the hook read it), so no fix is ported here. I am re-running the failed job once after the workflow finishes; a second failure will be treated as real.

---

Generated by Claude Code