Epic: native-overlap tooling fix and route-to-compose sweep

[kyle-sexton]

Brief

TLDR

• Repair the native-overlap tooling so it reports honestly on Claude Code 2.1.263: the inventory extractor's bundled-skill lane, per-lane integrity, the reverse-parity blind spot, and the seeded-pairs drift.
• Move the marketplace posture from route-only to compose-where-sensible: a skill runs the native surface as a named step when it resolves and layers its own value around it.
• Add a per-row integration field (route, wrap, suggest) to the native-surfaces store, separate from verdict, and a suggest grammar to the native-references convention.
• Degrade gracefully: when a native surface does not resolve, skip the step, report it with the gating axes, offer the enable path, never re-implement the native job.
• Deliver as one parent issue with per-unit sub-issues: the tooling fix first, then claude-ops, then every other plugin holding a store row, one unit in flight at a time.

Goal

A run of /claude-ops:audit-native-overlap on the current Claude Code build tells the truth lane by lane instead of collapsing to broken, and the skills this marketplace ships stop competing with the native surfaces they overlap: where a bundled skill does a strict subset of a skill's job, the skill composes it as a step and adds its own value (deeper inventory, reconciliation, its own agents); where a built-in command does related work a skill cannot invoke, the skill tells the user it exists at the moment that matters; and in every session where the native surface is gated, disabled, or absent, the skill still completes its own part and says what it skipped and why.

Constraints

• A skill never asserts that a native surface is present, absent, enabled, or unavailable. The native-references convention's presence-gate rule holds for every new phrase and body section.
• A skill never invokes a target it cannot identify. Bundled skills: name in the listing plus an advisory description check, skip with a warning on mismatch. Plugin skills (any marketplace, including melodic-software): the namespaced plugin:skill form, plus marketplace-qualified provenance from claude plugin list when the CLI resolves. Built-in commands: never invoked.
• Whether a session is unattended is declared by the caller, never sniffed. An unattended run records a built-in suggestion in its output instead of asking.
• Verdicts stay human-gated. No component is edited before its store row carries a verdict and an integration value.
• The sweep contract stands: one plugin is one unit, closed only when its PR merges green, never two units in flight.
• Every touched description must fit the 1,536-character per-entry cap after baking; trimming existing text to make room is allowed and gated by /skill-quality:check.
• Baked text is self-contained: no phrase or Boundary section cites a file outside its own plugin.
• Plain-bullet acceptance criteria (acceptance_criteria_format resolved to free-text from the default; the repo declares no convention home).

Acceptance criteria

• inventory.py --binary-only on Claude Code 2.1.263 reports integrity ok or degraded with a non-empty bundled-skill lane, its eval suite passes, and validated_against moves to 2.1.263.
• overlap.py detect on an inventory with exactly one broken lane exits 3, writes the candidates file, states per-lane floors, and marks only that lane's rows as not re-derivable.
• overlap.py self-check flags a frontmatter description that names a bundled surface behind a presence condition without a gate token.
• Every store row carries integration with one of route, wrap, suggest; the self-check rejects any other value, rejects wrap on a built-in command row, and rejects wrap or suggest on a session-provided row.
• The generated view renders the integration column and --check stays in sync.
• The two human-added audit-skill-visibility rows appear in reference/canonical-pairs.json, and a consumer-repo detect proposes them.
• The native-references convention documents three grammars (route phrase, wrap Boundary section, suggest body sentence) with the class table stating which grammar each provenance class may use.
• A wrapped skill, run where the native surface resolves, invokes it as a named step and reports the native result alongside its own.
• A wrapped skill, run where the native surface does not resolve, completes its own part and reports the skipped step naming the four gating axes and the enable path.
• While a bundled skill is present under skillOverrides: name-only, the wrapping skill treats it as not resolving.
• A skill with a suggest row surfaces the suggestion at the start of the run when the built-in command covers everything the skill does, and at the end when coverage is partial, phrased conditionally.
• Every touched skill passes /skill-quality:check, and each sweep unit's plugin takes its version bump and CHANGELOG entry.
• The parent issue quotes the affected store rows, and each sub-issue names its unit and its predecessor.

Captured assumptions

• The two coverage cases above (native absent, name-only override) are the author's proposal; the user approved the Brief as a whole without ruling on them separately. Revisit if a sweep unit finds a third trigger or state the wrapped skill must handle.
• Wrap candidates on the current store are the bundled-skill rows: doctor (three rows), simplify (two), run, design (two), and the plugin-backed security-review. code-review against the CI lane is expected to stay route because a CI lane cannot type into a session. Each row's final integration value is still a human verdict recorded in the store. Revisit if a row's verdict moves to superseded.
• Built-in command rows (export, skill-doctor) and the design access command take suggest. Revisit if Claude Code exposes a built-in command through the Skill tool.
• The skill-doctor row keeps its gated marker on the docs basis (v2.1.252+, absent when feature-flag fetching is skipped); the extractor's gated: false reading is a heuristic blind to feature-flag gates. Revisit when the extractor learns to read that gate.
• design is two surfaces sharing one name: the canvas bundled skill (the store row) and a gated built-in access command. The row's evidence must name both. Revisit if either is renamed.
• Replace (our skill retired in favor of the native one) is expressed by the existing superseded verdict, so integration needs no replace value. Revisit if a row reaches superseded and still needs a runtime relationship.
• The extractor fix targets the 2.1.263 bundle layout, where the readable export map no longer carries registerBundledSkill:()=>…; the new registration shape is an implementation finding for the plan. Revisit on the next CLI release that moves validated_against again.
• Session-provided rows (morning) stay defer with integration: route withheld until an in-session capture protocol exists.

Scope note, 2026-09-10, added at planning after the fresh-context review: three statements about defer rows disagreed (the assumption above says route is withheld for morning, the acceptance criterion says every row carries integration, and the plan's verdict pass proposes route). The acceptance criterion is the stronger, approved statement, so every row carries integration, morning included, with route as the only value a defer row may take. The assumption's "withheld" is superseded by this note.

Scope note, 2026-09-10, added at planning after the devil's-advocate pass: the wrap-candidate assumption above rests on model-invocability that the 2.1.263 binary contradicts. Each bundled-skill registration carries an invocation-control field, and doctor, design, design-sync, batch, debug, and run-skill-generator are registered with model invocation disabled, which the official skills reference defines as "Claude cannot invoke" and this repository's invocation-mode convention restates as "cannot be invoked by any other skill". simplify and run are registered model-invocable. So the three doctor rows and the two design rows cannot take wrap on any host; their available integrations are route and suggest. This changes which rows the sweep can compose and is the user's decision at the policy unit's verdict pass, not resolved here.

Out-of-scope

• Re-implementing any native job inside a marketplace skill as a fallback.
• Retiring any skill under superseded in this effort.
• Wrapping or suggesting session-provided skills.
• The improvement items beyond the four broken ones: a recheck subcommand for trigger evaluation, a marker-basis field, name-collision keying in detect, an apply-time per-entry cap precheck, durable report output from a bare run, and a reverify helper. These are filed as follow-up scope below, not built here.

Deferred questions

• none; every registered question closed answered.

Affected store rows

Every row of the native-surfaces store at the time of filing. Integration reads pending until the policy unit's human verdict pass writes it.

Native surface	Class	Component	Verdict	Integration
code-review (markers: none)	bundled-skill	review:code-review (skill)	complementary	pending
simplify (markers: none)	bundled-skill	code-tidying:tidy (skill)	complementary	pending
simplify (markers: none)	bundled-skill	code-tidying:batch-simplify (skill)	complementary	pending
security-review (markers: none)	plugin-backed-builtin	review:security-review (skill)	complementary	pending
run (markers: none)	bundled-skill	testing:run-e2e (skill)	complementary	pending
doctor (markers: gated)	bundled-skill	claude-ops:audit-install-state (skill)	complementary	pending
doctor (markers: gated)	bundled-skill	claude-ops:audit-performance (skill)	complementary	pending
doctor (markers: gated)	bundled-skill	claude-ops:audit-skill-visibility (skill)	complementary	pending
skill-doctor (markers: gated)	builtin-command	claude-ops:audit-skill-visibility (skill)	complementary	pending
morning (markers: none)	session-skill	claude-ops:morning-brief (skill)	defer	pending
export (markers: none)	builtin-command	session-flow:clean-stop (skill)	complementary	pending
playground (markers: none)	marketplace-plugin	visualization:visualize (skill)	complementary	pending
playground (markers: none)	marketplace-plugin	prototype:explore-directions (skill)	complementary	pending
design (markers: gated)	bundled-skill	visualization:visualize (skill)	complementary	pending
design (markers: gated)	bundled-skill	prototype:explore-directions (skill)	complementary	pending
design-sync (markers: hidden, gated)	bundled-skill	visualization:visualize (skill)	defer	pending

Two rows are added by the policy unit: export against session-flow:handoff and export against session-flow:retro, both suggest, because each body already carries a suggestion and every baked line must trace to a row.

Follow-up scope

Filed here for later items, not built under this container:

• A recheck subcommand for the overlap engine that evaluates recheck triggers against a changelog and the upstream plugins repository, so trigger evaluation stops being a manual session act.
• A marker-basis field on store rows recording which substrate set each marker.
• Name-collision keying in detect (one native name resolving in two lanes).
• Durable report output from a bare /claude-ops:audit-native-overlap run.
• A reverify helper that stamps a row's date plus evidence without hand-editing JSON.
• The registrar-export advisory in the inventory extractor is blind to the ESM export form; the tooling fix teaches it that form, and any further registration shape found later is its own item.
• Phantom constant names from a global constant map (a same-named identifier bound to an unrelated string in another chunk); the tooling fix scopes resolution per chunk, and any residual case is its own item.

Search before create

Searched open and closed issues for native-overlap, audit-native-overlap, native-surfaces, and inventory.py 2.1.263 on 2026-09-10. No open issue carries this scope; the nearest matches were a closed item pinning the skill-doctor row's upstream source and the code-metrics follow-ups container, neither of which overlaps.

Execution shape: per-item PRs

[kyle-sexton]

Round-4 policy decisions for #4049 were resolved on 2026-09-11 and validated by two independent research agents against the official Claude Code references and the 2.1.263 binary. Consequences for this container:

Corrections to the Brief's captured assumptions (recorded in docs/topics/audit-native-overlap/PLAN.md, third scope note): the name design carries two bundled registrations on 2.1.263, and the canvas skill both design rows describe is model-invocable, so those rows do not carry model-invocation-disabled and wrap is admissible for them (the accepted value is route on job merits, revisitable in units 7 and 8). The assumption that no built-in command is exposed through the Skill tool has fired: the official skills reference exposes /init and /security-review; the export and skill-doctor rows still take suggest because those commands are non-prompt command types.

Unit 1 (#4048) gained a requirement: a same-name bundled collision rule so disable_model_invocation is keyed per registration. Unit 2 (#4049) stays work-class: structural and needs-human; the verdict table in its body is the C4 plan approval.

Follow-up scope, added to this container:

• /verify has no store row although it is the closest bundled analogue to testing:run-e2e and verification:confirm. Candidate pairs: verify x testing:run-e2e, verify x verification:confirm. It is model-disabled by a flag-driven field, so suggest at most.
• A Native step identity check (name plus description) cannot see behaviour drift under a correct identity, such as simplify running single-pass without the Agent tool. Candidate grammar addition: a post-step assertion on what the surface reported doing.
• Seeded-vs-observed name-collision keying in detect stays here; the bundled-vs-bundled case moved into claude-ops/inventory: recover the bundled-skill lane on 2.1.263 and report integrity per lane #4048.

---

Generated by Claude Code