Define overlap handling for skill command policies

[shiny-code-bot]

Finish Line

Every Code handles overlapping skill-owned command policies deterministically and usefully when multiple loaded skills match the same raw command.

Current Status

State: Proposed follow-up after initial command-policy runtime support (#236/#237).
Next action: Design and implement overlap semantics before adding many cross-cutting skill policies.
Blocked by: None.
Waiting for: More real policy migrations may provide examples, but implementation can be designed independently.
Last verified: 2026-05-30 after the GitHub skill migration in cbusillo/codex-skills#191 exposed possible overlap with github-plan.

Context

The current runtime compiles command policies from all loaded skills and picks a single best match by matcher specificity. That works for simple cases but can be noisy or surprising when a broad skill and a specialized skill both own the same command family.

Example:

• github owns broad raw gh issue edit -> scripts/gh-issue edit guidance.
• github-plan may want planning-specific guidance for gh issue edit when editing durable plan issue bodies.

If both policies match, the model should receive deterministic guidance that preserves the specialized context without duplicating or hiding the broad helper preference.

Acceptance Criteria

• Define deterministic policy precedence when multiple skills match the same command.
• Preserve useful overlap information in guidance instead of silently dropping important specialized context.
• Avoid duplicate/noisy guidance when two policies point to the same preferred helper.
• Account for manual-only skills and skill precedence/order from the loader.
• Add unit tests for exact/prefix/regex overlaps, equal-specificity ties, duplicate preferred actions, and manual-only policies.
• Add an exec-path regression test proving overlapping policies block before execution and return stable guidance.
• Document how skill authors should avoid or intentionally use overlaps.

Open Questions

• Should a more specialized skill policy be able to override a broad policy by declaring an explicit priority or relationship?
• Should the runtime return one primary policy plus secondary notes, or aggregate all matching policies into one guidance response?
• Should duplicate preferred actions be coalesced by path/example/kind?
• Should overlap handling be schema-only, runtime-only, or both?