An extension alias can shadow a core command; `_validate_install_conflicts` only checks installed extensions

[Yash-Chindam]

Problem Statement

_validate_install_conflicts is documented as rejecting installs that "would shadow core or installed extension commands", but it only checks installed extensions. Core command names are never in the map it consults, so an extension can claim a core command name as an alias and install successfully.

Split out of #4421 at a maintainer's request, so that stage 1 (#4488) stays additive and no core-validation change is smuggled into it.

Reproduction

main at d848fb4. A manifest whose command carries speckit.taskstoissues — a live core command — as an alias:

schema_version: "1.0"
extension:
  id: probe
  name: "Probe"
  version: "1.0.0"
  description: "probe"
requires:
  speckit_version: ">=0.2.0"
provides:
  commands:
    - name: speckit.probe.taskstoissues
      file: commands/cmd.md
      aliases: ["speckit.taskstoissues"]     # core command name

Result:

1) manifest validation:
   ACCEPTED — aliases: [['speckit.taskstoissues']]
2) install into a project (core taskstoissues exists):
   ACCEPTED — installed: probe

Both stages accept it, with the core command present in the same project.

Cause

Two gaps that line up:

1. Aliases are not pattern-checked. EXTENSION_COMMAND_NAME_PATTERN and the core-namespace guard in src/specify_cli/extensions/__init__.py apply to primary command names only. A primary speckit.taskstoissues is correctly rejected (it fails the two-segment pattern, and an extension id equal to a core command name is rejected separately) — but an alias goes through neither check.

2. The conflict check does not know about core. _get_installed_command_name_map walks self.registry — installed extensions — so core command names never appear in the map that _validate_install_conflicts compares against. Confirmed by inspection: the function references self.registry and nothing that loads core command names (_load_core_command_names / _FALLBACK_CORE_COMMAND_NAMES).

So the docstring describes a guarantee ("shadow core or installed extension commands") that is only half implemented.

Impact

A community extension can claim a core command's name as an alias and shadow it. This is most likely to bite during the #4421 migration, where the whole point of stage 1 is that speckit.taskstoissues and speckit.github.taskstoissues coexist without either shadowing the other — but it applies to any core command, not just this one.

The bundled github extension in #4488 deliberately registers no alias, and has a test pinning that. Worth being explicit that this is currently author discipline, not an enforced invariant — which is the reason to file this separately rather than rely on the convention holding.

Suggested Fix

Either:

• extend the core-namespace guard to aliases as well as primary names, and include core command names in the map _validate_install_conflicts consults; or
• if shadowing core via an alias is intended to be allowed (an override mechanism), narrow the docstring to describe what is actually checked.

Whichever way it goes, a test should pin the decision — an install that claims speckit.taskstoissues as an alias currently passes silently either way.

Component

Specify CLI (initialization, commands)

---

Disclosure: I used an AI assistant (Claude Code, model Claude Opus 5) to investigate this and draft this report. The results above came from running the probe manifest through ExtensionManifest and ExtensionManager.install_from_directory against main; I reviewed the findings before filing.

[github-actions]

Bug assessment — extension-alias-shadow: Valid · severity medium

---

Bug Assessment: An extension alias can shadow a core command

• Slug: extension-alias-shadow
• Created: 2026-09-12T13:11:02Z
• Source: issue An extension alias can shadow a core command; _validate_install_conflicts only checks installed extensions #4555
• Verdict: valid
• Severity: medium

Report (summarized)

The issue reports that _validate_install_conflicts is documented as preventing an extension from shadowing core or installed-extension commands, but its installed-name map contains only commands and aliases from installed extensions. A community extension can therefore declare a live core command such as speckit.taskstoissues as an alias and pass both manifest validation and installation. The report reproduces this against main at d848fb4, and notes that the gap applies to any core command, not only taskstoissues.

No additional reproduction details beyond the issue report were required for this assessment.

Symptom

An extension manifest with a valid namespaced primary command and an alias matching a core command is accepted, and the extension installs into a project where the core command already exists. The expected behavior, based on the conflict-check docstring and the reported invariant, is to reject the install rather than allow the alias to shadow the core command.

Reproduction

1. Create an extension manifest with a primary command such as speckit.probe.taskstoissues.
2. Add speckit.taskstoissues to that command's aliases list.
3. Validate the manifest; it is accepted because aliases are type/path checked but not checked against the core namespace.
4. Install the extension into a project containing the core taskstoissues command; installation is accepted because the conflict map is populated from installed extensions only.

Suspected Code Paths

• src/specify_cli/extensions/__init__.py:48-62 — defines the fallback core command stems and the canonical extension command-name pattern.
• src/specify_cli/extensions/__init__.py:78-119 — loads core command names into CORE_COMMAND_NAMES; these values are core stems such as taskstoissues, not the full alias form speckit.taskstoissues.
• src/specify_cli/extensions/__init__.py:474-510 — validates aliases for type and safe path syntax, while explicitly applying no command-name pattern enforcement to aliases.
• src/specify_cli/extensions/__init__.py:1078-1155 — _collect_manifest_command_names enforces core namespace checks for primary command names only; aliases are collected without a core-name check.
• src/specify_cli/extensions/__init__.py:1157-1185 — _get_installed_command_name_map returns names from self.registry (installed extensions) and does not add core command names.
• src/specify_cli/extensions/__init__.py:1187-1208 — _validate_install_conflicts compares declared names only with that installed-extension map.
• src/specify_cli/extensions/__init__.py:2098-2099 — install_from_directory invokes the conflict validation before installation.
• tests/test_extensions.py:3033-3061 — existing coverage intentionally preserves free-form aliases, but does not cover an alias colliding with a core command.
• tests/test_extensions.py:3063-3110 — existing namespace and installed-extension collision tests cover primary namespace rules and extension-to-extension conflicts, not core alias conflicts.

Root Cause Hypothesis

Confidence: high. Core command names are represented separately from extension command names, and the validation logic applies the core namespace guard only inside the kind == "command" branch. Alias names are deliberately allowed to remain free-form for compatibility, but no separate reserved-name check is applied. The later install conflict check only consults manifests in self.registry, so core commands cannot collide there either. These two omissions allow the reported alias through both validation stages.

Proposed Remediation

Preferred: Keep aliases free-form for backward compatibility, but reserve the canonical full names of core commands (for example, derive speckit.<core-stem> from CORE_COMMAND_NAMES) when validating every declared alias. In addition, make the install conflict map include core command names, or perform the same normalized core-name collision check in _validate_install_conflicts, so both manifest-level and install-time validation enforce the invariant. The error should identify the alias and the core command it conflicts with.

Add focused tests for manifest/install rejection of a core alias, including a core command discovered from the source templates and the fallback set. Retain the existing test proving that a non-core short alias such as speckit.shortcut remains accepted.

Alternatives:

• If core overrides through aliases are an intentional extension point, narrow the _validate_install_conflicts documentation and add explicit precedence/dispatch tests. This preserves compatibility but allows an extension to change the command users invoke, so it is less safe as the default.
• Normalize all command names into one registry containing core and extension providers, then use a single collision check. This is more comprehensive but has greater migration and compatibility risk than adding a reserved-core check.

Files likely to change:

• src/specify_cli/extensions/__init__.py
• tests/test_extensions.py

Tests to add or update:

• Reject an alias equal to a core command's canonical name during install or manifest conflict validation.
• Verify the full speckit.<core-stem> normalization for a core name such as taskstoissues.
• Verify that aliases which do not collide with core or installed extension names remain accepted.
• Preserve rejection of duplicate aliases and existing extension-to-extension collisions.

Risks & Considerations

• Changing alias validation may reject existing community extensions that currently rely on core aliases; this is a compatibility change and should produce a clear migration error.
• The core-name source can differ between a source checkout, packaged core bundle, and fallback set, so the normalization must use the same discovery path as existing core validation.
• Core-vs-extension precedence should remain deterministic even when command registration is disabled during preflight or when an extension is reinstalled.
• No data migration is required, but already-installed conflicting extensions may remain in user projects; the remediation should clarify whether detection is install-time only or also part of listing/repair commands.

Open Questions

• Should an existing installed extension that already claims a core alias be reported or remediated by an audit/list command, or is blocking future installs sufficient?
• Are any documented community extensions intentionally using a core alias as an override, or should all such aliases be treated as invalid?

Generated by 🐛 Assess Bug from Labeled Issue for #4555 · copilot · gpt52codex · 2.03 AIC · ⌖ 5.49 AIC · ⊞ 25.5K · ◷