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

Closes #4048

The inventory extractor's bundled-skill lane returned empty on Claude Code 2.1.263 (a bytecode-fragmented bundle with an ESM export list), so every native-overlap run reported broken. inventory.py now reads every printable run above a 256-byte floor from the first bundle marker, discovers the registrar by three routes, resolves computed names by locality, keeps same-name registrations as a collision list, reads the invocation-control fields, and reports integrity per lane. overlap.py reads the lanes, marks candidates re_derivable, flags ungated presence mentions, and accepts one --upstream-sha per upstream repository. Two seeded pairs (doctor and skill-doctor against audit-skill-visibility), the graduated plan and design resolution under docs/specs/, a trimmed audit-native-overlap description, and claude-ops 0.54.0.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JEFsqe8fDbDjSFx79hVB9e

Author: kyle-sexton

docs/specs/native-overlap-integration-design.md

@@ -0,0 +1,63 @@
+---
+outcome: early-exit
+tier: B
+reason: one new store field with a closed enum, one new convention grammar, and a per-lane integrity shape inside existing scripts; every contract decision was locked in the Brief, so a full design pass would re-derive settled threads
+---
+
+# Design resolution, audit-native-overlap
+
+## Type sketch
+
+### Store row (`docs/native-surfaces/records.json`, schema 1, additive)
+
+```text
+row.integration : "route" | "wrap" | "suggest"     required on every row
+  invariants (enforced by overlap.py validate_row):
+    native.class == "builtin-command"      -> integration in {route, suggest}
+    native.class == "bundled-skill"        -> integration in {route, wrap}
+    native.class == "bundled-skill" and "model-invocation-disabled" in native.markers
+                                           -> integration == "suggest"   (the model never lists it, so a route phrase is dead text)
+    native.class == "plugin-backed-builtin"-> integration in {route, wrap}
+    native.class == "marketplace-plugin"   -> integration in {route, wrap}   (wrap grammar owned by seam-phrasing)
+    native.class == "session-skill"        -> integration == "route"
+    verdict == "defer"                     -> integration == "route"   (nothing is baked from a defer row)
+    integration in {wrap, suggest}         -> an evidence line names the observed invocation mode
+                                              (Skill-tool reach is per surface: /init and /security-review are
+                                              reachable built-ins; /export and /skill-doctor are non-prompt
+                                              command types; the class rules are a floor, not the determinant)
+  marker source: the registration the row's evidence names, never the bare name
+    (on 2.1.263 "design" is two bundled registrations: the canvas, model-invocable; the hub, model-disabled)
+row.baked : {description_phrase, boundary_section, native_step, suggest_sentence}   two flags added
+  native_step:      true only when integration == "wrap"    and the body carries "## Native step: <name> (<class>)"
+  suggest_sentence: true only when integration == "suggest" and the body carries the suggest token
+```
+
+### Inventory integrity (`inventory.py`, schema 1, additive)
+
+```text
+integrity.status        : "ok" | "degraded" | "broken"        unchanged, now the worst lane
+integrity.lanes         : { builtin_commands: LaneStatus, bundled_skills: LaneStatus, plugin_backed: LaneStatus }
+LaneStatus              : { status: "ok" | "degraded" | "broken", problems: [str], advisories: [str] }
+```
+
+`overlap.py detect` reads `integrity.lanes` when present and falls back to the top-level status when absent, so an older inventory file still parses.
+
+### Convention grammars (`docs/conventions/native-references`)
+
+```text
+route   : description phrase carrying the gate token "resolves in your session"   (existing)
+wrap    : body section "## Native step: <name> (<class>)" carrying the gate token, the identity
+          check by class, the mutation clause, the skip-and-report contract for five states
+          (does not resolve, invocation refused with the reason named, identity mismatch,
+          mutation detected after a scoped invocation, resolved but degraded with the surface's
+          own disclosure relayed), and the enable path   (new)
+suggest : body sentence "If /<command> is available in your session (<basis>), run it for <job>."
+          carrying the token "available in your session", the basis pointing at a same-file
+          four-part verification record                                              (new)
+```
+
+Class table: bundled-skill, plugin-backed-builtin, and marketplace-plugin may take route or wrap (the marketplace-plugin wrap grammar is seam-phrasing's, per the playgrounds precedent); a bundled-skill row marked model-invocation-disabled takes suggest; builtin-command may take route or suggest; session-skill may take route only. Amended 2026-09-11 after the round-4 validation pass.
+
+## Threads resolved in the Brief
+
+Wrap semantics, degradation contract, identity verification, suggestion placement, per-row field placement, description trimming, and filing shape are all locked in `../PLAN.md` `## Brief`. No thread is open.

docs/specs/native-overlap-route-to-compose.md

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "claude-ops",
-  "version": "0.53.0",
+  "version": "0.54.0",
   "description": "Claude Code operations toolkit. Twelve skills: audit-skill-visibility (audit whether each installed skill is actually VISIBLE to the model, and diagnose why most of a fleet never gets used: a skill is invisible when its description is dropped by Claude Code's skill-listing context budget, which sheds descriptions lowest-score-first so an unused skill loses the keywords that would let it be matched, from skills genuinely not wanted, from skills the run cannot observe at all; computes whether the listing overflows from documented settings, and withholds every cold verdict the data cannot support rather than reporting absence of data as absence of use), inventory (read-only enumeration of the complete invocable surface: every built-in CLI command with aliases and hidden/gated status, every bundled skill, and every component of every installed plugin across all marketplaces; reads the shipped binary because upstream publishes no built-in command list, and carries an integrity verdict so a drifted build reports counts as floors rather than silently short totals), audit-install-state (read-only audit of the machine-scope ~/.claude installation directory and ~/.claude.json: full inventory split into an authored surface and rolled-up bulk trees, product-managed retention vs genuinely unmanaged state, filename-scheme resolution before any process-liveness check, and deliberate/mid-experiment detection; reports, never deletes), audit-performance (read-only slowness-diagnostic capture run at the moment the machine or a session feels slow: CLI version, retention-sweep health including the silent unparsable-settings pause, a timed census walk of the install tree as a sweep-cost proxy, active-session and plugin-fleet counts, a process census, and the fan-out layer, which covers a load-labelled no-op spawn baseline, every hook that will fire bucketed per-tool-call versus per-turn with its invocation shape, the configured statusline, subagent concurrency and spawn-depth ceilings against documented defaults, whether running sessions predate the settings file they are judged by, and orphan attribution by parent liveness rather than age, plus on Windows a kernel-object census (Token objects against uptime, paged pool) that names a host-level leak beneath all four suspects; read against a bundled known-performance-issues reference that also records the causes tested and cleared; separates the four documented suspects of accumulated state, version regression, component bloat, and per-spawn fan-out cost, and routes remediation out; reports, never mutates, and never executes a discovered hook or statusline command), audit-native-overlap (map native Claude Code surfaces, namely built-in CLI commands, bundled skills, plugin-backed built-ins, and session-provided skills, against the current repo's plugin skills and agents, so a custom component never silently duplicates what Claude Code itself ships; bare invocation is a read-only overlap report carrying the extraction's integrity floors and a shared-listing-budget exposure section, verdicts are human-gated in a committed store rendered into a generated registry whose every row carries an observable recheck trigger, and only an explicit apply step bakes presence-gated native references into descriptions and Boundary sections), observability (read locally captured telemetry from the OTEL store, the collector, the per-session hook event log and hook-event JSONL, and ccusage, with trend reports, a per-session report of what fired, what was blocked and the event timeline, and store pruning), known-issues (search known Claude product GitHub bugs, check service health, maintain a persistent tracked-issue registry), changelog (ingest Claude Code changelog entries and integrate them into the current repo), plugins (bring a machine's plugin fleet current on demand: marketplace refresh, effective-scope updates including in-repo project/local installs, new-plugin install per policy, scope-divergence detection and explicit convergence), morning-brief (read-only gh-based operator morning view: queue-label counts, merge-ready PRs, parked decisions with their RECOMMENDED lines, and loop-lane telemetry freshness), lanes (start/restart/stop/status loop lanes as named background Claude Code sessions seeded from canonical prompt files, with per-lane model/effort, a repo-pull + marketplace-refresh launch step, and a consume-restarts action, an OS-schedulable reader that relaunches stopped lanes whose telemetry carries a restart_request), and a re-runnable setup action that settles where the known-issues registry, the skill-usage log and the hook log root live, places the root's self-ignoring guard, and detects retired conventions. Plus an opt-in, default-off per-session hook event log (one JSON line per hook event on every event the generated registry marks observable, written to <root>/sessions/<session_id>.jsonl, with SessionEnd retention by session count or age and an optional detached pre-prune command), a family of eight advisory *-audit hooks (API errors, config changes, instruction loads, permission denials, pre-compaction, skill usage, tool failures, and unsurfaced hook failures. The last also warns the user via systemMessage, since a hook that fails to launch enforces nothing and Claude Code surfaces the failure to nobody) that emit the shared hook-telemetry envelope, and a reference sink that routes envelopes under the same root: per session when the envelope carries a session id, else into the shared hook-events.jsonl the observability skill reads.",
   "author": {
     "name": "Melodic Software",

plugins/claude-ops/.claude-plugin/plugin.json

@@ -3,6 +3,63 @@
 All notable changes to the `claude-ops` plugin are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.
 
+## [0.54.0]
+
+### Added
+
+- **`inventory.py` reads a bytecode-fragmented bundle.** 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 sitting 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 discovery routes.** The CJS getter, then the ESM export list
+  (`<ident> as registerBundledSkill`), then the canary registration; `bundled_skill_notes` records
+  `registrar_route`. The registrar-shaped-export advisory sees both export shapes, and the known
+  set gains `registerDesignCanvasSkill` and `registerWorkflowAuthoringSkill`.
+- **Computed names resolve by locality.** A hoisted constant resolves to its nearest preceding
+  binding, never a farther one, so an unrelated module's binding of the same identifier cannot
+  shadow the real one; a single-character identifier is trusted only within a locality window; a
+  loop or template-literal registration is a `dynamic_roster` note, not an unresolved name; a call
+  whose object carries no `name:` is another module's function and is counted apart.
+- **Per-registration invocation fields.** `user_invocable`, `disable_model_invocation`,
+  `terminal_oriented`, and `survives_kill_switch` when present; a function-valued field reads as
+  true with the key listed under `flag_driven`.
+- **Same-name registrations are both kept.** Two distinct bundled registrations sharing a name are
+  a list under that name with `collision: true` and are named in `bundled_skill_notes.collisions`;
+  `registrations_of(entry)` reads either shape.
+- **Integrity per lane.** `integrity.lanes` carries `builtin_commands`, `bundled_skills`, and
+  `plugin_backed`, each with its own status, problems, and advisories; the top-level status is the
+  worst lane, and top-level `broken` means every lane is broken or the binary is unreadable, so one
+  broken lane is a named `degraded` rather than a run with no counts. `plugin_backed` gains a canary
+  (`security-review`). Exit mappings are unchanged in both `inventory.py --self-check` (which now
+  prints each lane) and `overlap.py detect`.
+- **`overlap.py detect` reads the lanes.** The candidate report carries 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 every
+  candidate carries `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,
+  which have no lane. A name collision lists every registration with its invocation mode. An
+  inventory without `lanes` keeps the previous reading.
+- **`overlap.py self-check` flags a presence-gated native mention without the gate token.** A
+  description that names a native surface by class and kind inside a `when`, `where`, or `if`
+  clause with an availability word, and carries no gate token in that clause, is an advisory (exit
+  3) naming the row to add or the token to use. Judged per clause, so a gated marketplace clause
+  never excuses an ungated native clause beside it.
+- **`--upstream-sha` repeats.** One value per upstream repository the store cites; a recorded
+  commit matches when any provided value matches it.
+- **Seeded pairs** gain `doctor` and `skill-doctor` against `claude-ops:audit-skill-visibility`.
+
+### Changed
+
+- `VALIDATED_AGAINST` is `2.1.263`, validated on the Linux ELF build in a container; the PE
+  container path is covered by a byte-layout fixture, not a Windows run.
+- The audit-native-overlap description is under the 1,024-character Skills API cap: the same
+  claims and every trigger phrase, in fewer words.
+- The inventory skill's integrity table, the audit-native-overlap detection posture, and
+  `reference/extraction.md` describe the lanes, the region rule, the locality rule, and the
+  collision list; the inventory eval for degraded counts names dynamic rosters and lane statuses.
+
 ## [0.53.0]
 
 ### Added

plugins/claude-ops/CHANGELOG.md

@@ -1,5 +1,5 @@
 ---
-description: "Map native Claude Code surfaces (built-in CLI commands, bundled skills, plugin-backed built-ins, session-provided skills) against the current repo's plugin skills and agents, so a custom component never silently duplicates what Claude Code itself now ships. Bare invocation is a READ-ONLY report: overlap candidates with evidence, detection integrity floors, and a listing-budget exposure section. Verdicts are human-gated and recorded in a committed store rendered into a generated registry; only an explicit `apply` argument edits a component, baking presence-gated native references into descriptions and Boundary sections. Use when: 'does this skill duplicate a built-in', 'what does Claude Code already ship for this', 'audit native overlap', 'is our install-state audit the same as /doctor', 'refresh the native-surfaces registry', 'bake the native reference into this skill', 'which of our skills overlap bundled skills'. Not for: enumerating what this machine can invoke (use /claude-ops:inventory), MCP tool overlap (use /mcp-tools:audit), plugin fleet currency (use /claude-ops:plugins), or ingesting a CLI release (use /claude-ops:changelog)."
+description: "Map native Claude Code surfaces (built-in commands, bundled skills, plugin-backed built-ins, session skills) against this repo's skills and agents, so no component silently duplicates what Claude Code ships. Bare invocation is READ-ONLY: overlap candidates with evidence, per-lane integrity floors, and listing-budget exposure. Verdicts are human-gated in a committed store rendered to a generated registry; only an explicit `apply` argument edits a component, baking presence-gated native references into it. Use when: 'does this skill duplicate a built-in', 'what does Claude Code already ship for this', 'audit native overlap', 'is our install-state audit the same as /doctor', 'refresh the native-surfaces registry', 'bake the native reference into this skill', 'which of our skills overlap bundled skills'. Not for: enumerating what this machine can invoke (/claude-ops:inventory), MCP tool overlap (/mcp-tools:audit), plugin fleet currency (/claude-ops:plugins), or ingesting a CLI release (/claude-ops:changelog)."
 argument-hint: "[report|apply <plugin>] [--store <path>] [--inventory <path>]. Bare runs the read-only report"
 user-invocable: true
 disable-model-invocation: false
@@ -96,9 +96,13 @@ for the repo's test discovery.
 
 Under-recall stated honestly beats confident completeness. Three rules:
 
-- **Carry the integrity floor through.** If the inventory reports `degraded`, every native-side
-  count in the report is a floor and the report says so in the same sentence as the number. If it
-  reports `broken`, the report carries no native-side counts at all.
+- **Carry the integrity floor through, per lane.** The inventory reports integrity per lane
+  (`builtin_commands`, `bundled_skills`, `plugin_backed`). A `degraded` lane makes every count from
+  that lane a floor, and the report says so in the same sentence as the number. A `broken` lane's
+  counts are omitted, the report names the lane and its cause, and every candidate whose lane is
+  broken is marked `re_derivable: false` (its presence or absence in that lane proves nothing
+  this run); the other lanes' counts stand. Only when every lane is broken does the report omit
+  every native-side count.
 - **Never auto-verdict.** Detection emits candidates with evidence. The verdict column is empty
   until a human fills it.
 - **Accept human-added candidates.** A pair nobody's heuristic found is a first-class row; add it
@@ -110,8 +114,8 @@ Under-recall stated honestly beats confident completeness. Three rules:
 # Native overlap — <repo>, <date>
 
 ## Detection integrity
-Inventory status (ok | degraded | broken), cli_version vs validated_against, and what that
-means for every count below.
+Inventory status per lane (ok | degraded | broken), cli_version vs validated_against, and what
+that means for every count below; a broken lane is named with its cause.
 
 ## Overlap candidates
 One row per (native surface, our component): native name + provenance class + hidden/gated

plugins/claude-ops/skills/audit-native-overlap/SKILL.md

@@ -37,6 +37,16 @@
       "component": { "plugin": "claude-ops", "skill": "audit-performance", "kind": "skill" },
       "why": "Both diagnose a slow or unhealthy install; doctor also offers to fix."
     },
+    {
+      "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."
+    },
     {
       "native": { "name": "morning", "class": "session-skill" },
       "component": { "plugin": "claude-ops", "skill": "morning-brief", "kind": "skill" },