source-agnostic artifact IDs; built-in tier recognized by exclusion, never by name.

Co-authored-by: nicolehaugen <10600161+nicolehaugen@users.noreply.github.com>

Author: Copilot

docs/reference/artifacts.md

@@ -66,6 +66,7 @@ specify artifact info <name> --json
   "stack": [
     {
       "layer": "preset",
+      "sourceId": "compliance",
       "presetId": "compliance",
       "presetName": "Compliance Preset",
       "strategy": "replace",
@@ -75,14 +76,15 @@ specify artifact info <name> --json
       "lookupId": "preset:compliance:command:speckit.specify"
     },
     {
-      "layer": "core",
+      "layer": null,
+      "sourceId": null,
       "presetId": null,
       "presetName": null,
       "strategy": "replace",
       "active": false,
       "hidden": true,
       "manifestPath": null,
-      "lookupId": "core:_:command:speckit.specify"
+      "lookupId": null
     }
   ]
 }
@@ -96,16 +98,17 @@ The top-level `id`, `name`, `kind`, and `description` fields match the correspon
 
 | Field          | Description                                                                     |
 | -------------- | -------------------------------------------------------------------------------- |
-| `layer`        | `project`, `preset`, `extension`, or `core`                                       |
-| `presetId`     | Preset pack directory id; `null` on `core`, `project`, and `extension` rows       |
+| `layer`        | `project`, `preset`, or `extension`; `null` for built-in layers                    |
+| `sourceId`     | Source component of `lookupId`, or `null` when the layer has no provenance         |
+| `presetId`     | Preset pack directory id; `null` on built-in, `project`, and `extension` rows       |
 | `presetName`   | Preset display name when its manifest declares one, else the pack id; `null` when `presetId` is `null` |
 | `strategy`     | `replace`, `wrap`, `prepend`, or `append`                                         |
 | `active`       | `true` only for index `0` — the layer whose content is served                     |
 | `hidden`       | `true` when a lower-index `replace` layer cuts this layer out of the composition |
 | `manifestPath` | Project-relative path to the declaring manifest, or `null` when none applies      |
-| `lookupId`     | Deterministic `{layer}:{sourceId}:{kind}:{name}` identifier for the layer         |
+| `lookupId`     | Deterministic `{layer}:{sourceId}:{kind}:{name}` identifier, or `null` for built-in layers |
 
-`active` and `hidden` are independent labels, not opposites. Composing strategies (`wrap`, `prepend`, `append`) keep lower layers in the composed output, so an inactive layer is not necessarily hidden: only layers below the first `replace` layer are marked `hidden`. Core rows appear as the base of the stack with `presetId`/`presetName`/`manifestPath` set to `null` and a `core:_:{kind}:{name}` lookup ID.
+`active` and `hidden` are independent labels, not opposites. Composing strategies (`wrap`, `prepend`, `append`) keep lower layers in the composed output, so an inactive layer is not necessarily hidden: only layers below the first `replace` layer are marked `hidden`. Built-in rows have no provenance: `layer`, `sourceId`, and `lookupId` are `null`.
 
 Lookup IDs use the same grammar as [preset contribution identifiers](presets.md#contribution-identifiers), so a `lookupId` from this command joins directly to `PresetManifest.iter_contributions()` / `ExtensionManifest.iter_contributions()` for manifest-declared layers. Project-local overrides carry a synthetic `project:_:{kind}:{name}` ID that intentionally matches no manifest contribution.
 

extensions/EXTENSION-API-REFERENCE.md

@@ -863,7 +863,7 @@ satisfied = version_satisfies("1.2.3", ">=1.0.0,<2.0.0")  # bool
 
 ## Contribution Identifiers
 
-Every command, template, script, and hook contributed by an extension (or a preset, or the core layer) is addressable at read time by a deterministic opaque identifier. Resolved artifact-stack layers carry a matching `lookupId` field that shares this grammar and identifies the layer's stack position. Manifest-declared preset and extension layers use the manifest's validated `id:` for `lookupId`'s `sourceId` component, so their `lookupId` joins directly to the matching `iter_contributions()` entry even after the installed directory is renamed; convention-only contributions have no manifest `id:` to consult and fall back to the on-disk directory / registry key instead (see [Determinism guarantees](#determinism-guarantees) below). Identifiers are **computed on demand from author-declared manifest content** and are **never persisted** to `.specify/` or to any cache file.
+Every command, template, script, and hook contributed by an extension or preset is addressable at read time by a deterministic opaque identifier. Resolved artifact-stack layers carry a matching `lookupId` field when they have provenance. Manifest-declared preset and extension layers use the manifest's validated `id:` for `lookupId`'s `sourceId` component, so their `lookupId` joins directly to the matching `iter_contributions()` entry even after the installed directory is renamed; convention-only contributions have no manifest `id:` to consult and fall back to the on-disk directory / registry key instead (see [Determinism guarantees](#determinism-guarantees) below). Identifiers are **computed on demand from author-declared manifest content** and are **never persisted** to `.specify/` or to any cache file.
 
 ### Grammar
 
@@ -873,9 +873,9 @@ Named contributions (commands, templates, scripts) follow:
 {layer}:{sourceId}:{kind}:{name}
 ```
 
-- `layer` is one of `core`, `preset`, or `extension`.
-- `sourceId` is `_` for `core`, the preset pack id for `preset`, or the extension id for `extension`.
-- `kind` is one of `command`, `template`, `script`, or `hook`.
+- `layer` is one of `preset` or `extension`.
+- `sourceId` is the preset pack id for `preset`, or the extension id for `extension`.
+- `kind` is one of `command`, `template`, or `script`.
 - `name` is the contribution's declared `name` field.
 
 Hook contributions use a compound name-component built from the event and command:

src/specify_cli/_identifier.py

@@ -9,19 +9,22 @@
 across machines, project locations, and reinstalls, and what lets consumers use
 them as stable join keys.
 
-Grammar for named contributions (commands, templates, scripts)::
+Grammar for manifest-backed named contributions (commands, templates, scripts)::
 
     id = "{layer}:{sourceId}:{kind}:{name}"
 
-    layer    ∈ {"core", "preset", "extension"}
-    sourceId = "_" when layer == "core"; the preset id or extension id otherwise
-    kind     ∈ {"command", "template", "script", "hook"}
+    layer    ∈ {"project", "preset", "extension"}
+    sourceId = "_" when layer == "project"; the preset or extension id otherwise
+    kind     ∈ {"command", "template", "script"}
     name     = the contribution's declared ``name``
 
 Hook identifiers use ``{eventName}:{command}`` as the name component::
 
     id = "{layer}:{sourceId}:hook:{eventName}:{command}"
 
+Built-in artifacts have no layer or lookup identifier. Their public identifier
+is source-agnostic: ``"{kind}:{name}"``.
+
 The functions in this module are pure — inputs are strings or in-memory
 mappings parsed from a manifest, outputs are strings. None of them read from
 disk, look at ``os.environ``, call ``datetime``, or hash file contents. That
@@ -88,24 +91,34 @@ def derive_named_id(layer: str, source_id: str, kind: str, name: str) -> str:
     strings should either pre-validate or handle
     :class:`IdentifierComponentError`.
     """
+    if layer not in _LAYER_KINDS:
+        raise IdentifierComponentError(f"Invalid layer '{layer}'")
+    if kind not in _NAMED_CONTRIBUTION_KINDS:
+        raise IdentifierComponentError(f"Invalid named contribution kind '{kind}'")
     validate_component(layer, "layer")
     validate_component(source_id, "sourceId")
     validate_component(kind, "kind")
     validate_component(name, "name")
     return f"{layer}:{source_id}:{kind}:{name}"
 
 
-_LAYER_KINDS = frozenset({"core", PROJECT_OVERRIDE_LAYER, "preset", "extension"})
+_LAYER_KINDS = frozenset({PROJECT_OVERRIDE_LAYER, "preset", "extension"})
 _CONTRIBUTION_KINDS = frozenset({"command", "template", "script", "hook"})
+_NAMED_CONTRIBUTION_KINDS = _CONTRIBUTION_KINDS - {"hook"}
+
+
+def derive_public_id(kind: str, name: str) -> str:
+    """Build the source-agnostic public identifier for an artifact."""
+    return f"{kind}:{name}"
 
 
 def layer_kind_from_lookup_id(lookup_id: str) -> str | None:
     """Return the layer segment of a resolved-stack ``lookupId``, or ``None``.
 
     ``lookupId`` values on resolved stack layers follow the same
     ``"{layer}:..."`` grammar as manifest-contribution ``id`` values (see
-    module docstring), with ``layer`` additionally taking on
-    :data:`PROJECT_OVERRIDE_LAYER` for resolver-only project-override layers.
+    module docstring), including :data:`PROJECT_OVERRIDE_LAYER` for
+    project-local override layers.
     This is the single place that knows the set of valid layer prefixes, so
     consumers can classify a lookupId without re-deriving the grammar via
     string-prefix checks of their own.
@@ -114,9 +127,9 @@ def layer_kind_from_lookup_id(lookup_id: str) -> str | None:
     named contributions require exactly the four ``{layer}:{sourceId}:{kind}:
     {name}`` components, and hook contributions require exactly the five
     ``{layer}:{sourceId}:hook:{eventName}:{command}`` components, with every
-    component non-empty. A value such as ``"core:not-an-id"`` or ``"preset:x"``
-    has a recognized layer prefix but the wrong number of components, so it is
-    malformed and returns ``None`` rather than being treated as authoritative.
+    component non-empty. A value such as ``"preset:x"`` has a recognized layer
+    prefix but the wrong number of components, so it is malformed and returns
+    ``None`` rather than being treated as authoritative.
     """
     parts = lookup_id.split(":")
     if len(parts) < 4 or any(not part for part in parts):
@@ -159,6 +172,8 @@ def derive_hook_id(
     Each component is revalidated with :func:`validate_component` — same
     contract as :func:`derive_named_id`.
     """
+    if layer not in _LAYER_KINDS:
+        raise IdentifierComponentError(f"Invalid layer '{layer}'")
     validate_component(layer, "layer")
     validate_component(source_id, "sourceId")
     validate_component(event_name, "eventName")

src/specify_cli/artifacts/__init__.py

@@ -22,6 +22,7 @@
 from .._identifier import (
     PROJECT_OVERRIDE_LAYER,
     IdentifierComponentError,
+    derive_public_id,
     is_dotted_command_name,
     layer_kind_from_lookup_id,
     validate_component,
@@ -33,7 +34,7 @@
 # ---------------------------------------------------------------------------
 
 ArtifactKind = Literal["command", "template", "script"]
-LayerName = Literal["project", "preset", "extension", "core"]
+LayerName = Literal["project", "preset", "extension"]
 Strategy = Literal["replace", "wrap", "prepend", "append"]
 
 
@@ -59,18 +60,20 @@ def to_json_dict(self) -> dict[str, Any]:
 class StackLayer:
     """One row inside the ``stack`` array returned by ``get_artifact_info()``."""
 
-    layer: LayerName
+    layer: LayerName | None
+    sourceId: str | None
     presetId: str | None
     presetName: str | None
     strategy: Strategy
     active: bool
     hidden: bool
     manifestPath: str | None
-    lookupId: str
+    lookupId: str | None
 
     def to_json_dict(self) -> dict[str, Any]:
         return {
             "layer": self.layer,
+            "sourceId": self.sourceId,
             "presetId": self.presetId,
             "presetName": self.presetName,
             "strategy": self.strategy,
@@ -335,8 +338,7 @@ def _build_stack(
 
     rows: list[StackLayer] = []
     for idx, layer in enumerate(raw):
-        lookup_id = layer.get("lookupId", "")
-        source = str(layer.get("source", ""))
+        lookup_id = layer.get("lookupId")
         strategy = layer["strategy"]
         active = idx == 0
 
@@ -345,15 +347,14 @@ def _build_stack(
         else:
             hidden = idx > first_replace_idx
 
-        # Layer classification: the lookupId prefix is the resolver's own
-        # grammar (see layer_kind_from_lookup_id) and is authoritative; the
-        # source-string check only guards against a malformed lookupId.
-        layer_kind = layer_kind_from_lookup_id(lookup_id)
+        layer_kind = layer_kind_from_lookup_id(lookup_id) if isinstance(lookup_id, str) else None
+        source_id = lookup_id.split(":", 2)[1] if layer_kind else None
 
-        if layer_kind == "core" or (layer_kind is None and source.startswith("core")):
+        if layer_kind == PROJECT_OVERRIDE_LAYER:
             rows.append(
                 StackLayer(
-                    layer="core",
+                    layer="project",
+                    sourceId=source_id,
                     presetId=None,
                     presetName=None,
                     strategy=strategy,
@@ -365,37 +366,35 @@ def _build_stack(
             )
             continue
 
-        if layer_kind == PROJECT_OVERRIDE_LAYER or (
-            layer_kind is None and source == "project override"
-        ):
+        if layer_kind == "extension":
+            manifest_path = _derive_manifest_path(layer, project_root)
             rows.append(
                 StackLayer(
-                    layer="project",
+                    layer="extension",
+                    sourceId=source_id,
                     presetId=None,
                     presetName=None,
                     strategy=strategy,
                     active=active,
                     hidden=hidden,
-                    manifestPath=None,
+                    manifestPath=manifest_path,
                     lookupId=lookup_id,
                 )
             )
             continue
 
-        if layer_kind == "extension" or (
-            layer_kind is None and source.startswith("extension:")
-        ):
-            manifest_path = _derive_manifest_path(layer, project_root)
+        if layer_kind != "preset":
             rows.append(
                 StackLayer(
-                    layer="extension",
+                    layer=None,
+                    sourceId=None,
                     presetId=None,
                     presetName=None,
                     strategy=strategy,
                     active=active,
                     hidden=hidden,
-                    manifestPath=manifest_path,
-                    lookupId=lookup_id,
+                    manifestPath=None,
+                    lookupId=None,
                 )
             )
             continue
@@ -417,6 +416,7 @@ def _build_stack(
         rows.append(
             StackLayer(
                 layer="preset",
+                sourceId=source_id,
                 presetId=pack_id or None,
                 presetName=display or None,
                 strategy=strategy,
@@ -546,19 +546,26 @@ def list_artifacts(self) -> list[Artifact]:
 
         resolver = PresetResolver(self.project_root)
         layers_cache: dict[tuple[ArtifactKind, str], list[dict[str, Any]]] = {}
+        resolved_cache: dict[tuple[ArtifactKind, str], bool] = {}
 
         def _layers_for(kind: ArtifactKind, name: str) -> list[dict[str, Any]]:
             key = (kind, name)
             if key not in layers_cache:
                 layers_cache[key] = resolver.collect_all_layers(name, kind)
             return layers_cache[key]
 
+        def _is_resolved(kind: ArtifactKind, name: str) -> bool:
+            key = (kind, name)
+            if key not in resolved_cache:
+                resolved_cache[key] = resolver.resolve_content(name, kind) is not None
+            return resolved_cache[key]
+
         names: set[tuple[ArtifactKind, str]] = set()
         for kind, name in self._iter_candidate_artifacts(resolver):
             key = (kind, name)
             if not _is_valid_artifact_name_component(name, kind):
                 continue
-            if _layers_for(kind, name):
+            if _layers_for(kind, name) and _is_resolved(kind, name):
                 names.add(key)
 
         artifacts: list[Artifact] = []
@@ -574,7 +581,7 @@ def _layers_for(kind: ArtifactKind, name: str) -> list[dict[str, Any]]:
                     description = candidate
                     break
             artifacts.append(
-                Artifact(id=f"{kind}:{name}", name=name, kind=kind, description=description)
+                Artifact(id=derive_public_id(kind, name), name=name, kind=kind, description=description)
             )
 
         kind_order = {"command": 0, "template": 1, "script": 2}
@@ -602,48 +609,39 @@ def get_artifact_info(
         _validate_preset_registry(self.project_root)
         bare, resolved_kind = _resolve_kind_hint(name, kind)
 
+        inventory = self.list_artifacts()
         if resolved_kind is None:
-            matches = self._find_matches(bare)
+            matches = [(artifact.kind, artifact.name) for artifact in inventory if artifact.name == bare]
             if not matches:
                 raise ArtifactNotFoundError(name)
             if len(matches) > 1:
                 raise AmbiguousArtifactError(bare, [k for k, _ in matches])
             resolved_kind = matches[0][0]
 
         validated_name = _validate_artifact_name(bare, resolved_kind)
-        if not any(kind_name == resolved_kind for kind_name, _ in self._find_matches(validated_name)):
+        artifact = next(
+            (
+                item
+                for item in inventory
+                if item.kind == resolved_kind and item.name == validated_name
+            ),
+            None,
+        )
+        if artifact is None:
             raise ArtifactNotFoundError(name)
         stack = _build_stack(self.project_root, resolved_kind, validated_name)
         if not stack:
             raise ArtifactNotFoundError(name)
 
-        description = self._describe(resolved_kind, validated_name)
         return {
-            "id": f"{resolved_kind}:{validated_name}",
+            "id": derive_public_id(resolved_kind, validated_name),
             "name": validated_name,
             "kind": resolved_kind,
-            "description": description,
+            "description": artifact.description,
             "stack": [layer.to_json_dict() for layer in stack],
         }
 
     # -------------------------------------------------------------- internals
-    def _find_matches(self, name: str) -> list[tuple[ArtifactKind, str]]:
-        """Return every (kind, name) pair whose name matches exactly."""
-        artifacts = self.list_artifacts()
-        return [(a.kind, a.name) for a in artifacts if a.name == name]
-
-    def _describe(self, kind: ArtifactKind, name: str) -> str:
-        """Return the description that would appear on the flat-list row.
-
-        Sources the value from :meth:`list_artifacts` so the two commands
-        agree on the same string for the same artifact — the ``info`` output
-        promises "matching the same field on 'artifact list --json'".
-        """
-        for artifact in self.list_artifacts():
-            if artifact.kind == kind and artifact.name == name:
-                return artifact.description
-        return ""
-
     def _iter_candidate_artifacts(
         self,
         resolver: Any,