[Feature]: Add deterministic contribution IDs and stack lookup IDs for resolved artifacts

[nicolehaugen]

Problem Statement

Spec Kit identifies contributed commands, templates, scripts, and hooks primarily by name. Names can collide across artifact kinds and source layers, and a name alone cannot reliably link a resolved artifact-stack layer to the exact manifest contribution that supplied it. Consumers such as preset info --json, extension info --json, and specify artifact need stable contribution identifiers and a join key that works across reinstalls and machines.

Proposed Solution

Introduce computed, opaque id fields for every command, template, script, and hook returned by public preset/extension manifest and info APIs, plus a lookupId field on every provenance-backed non-built-in resolved artifact-stack layer.

For named preset, extension, and project-override contributions, derive IDs using:

{layer}:{sourceId}:{kind}:{name}

Use project, preset, or extension for layer; _ only for the project-override source ID; and the preset or extension manifest ID for manifest-declared sources. Use command, template, or script for kind. Examples include preset:speckit.core:command:speckit.plan, extension:speckit.git:template:pr-body, and project:_:template:spec-template.

For hooks, use {eventName}:{command} as the name component. Hooks are valid only for preset and extension layers. If duplicate event/command hook entries are valid, add an appropriate stable discriminator or reject duplicates; do not use array position.

Built-in artifacts do not have an originating manifest contribution and therefore do not receive a contribution lookupId. Every artifact, including built-ins, instead has a source-agnostic public ID of the form {kind}:{name}. Built-in stack rows are recognized by absent provenance fields (layer, sourceId, and lookupId are null), and round-trip through the public artifact ID.

Compute IDs at read, serialization, or resolution time rather than persisting them in authored or installed manifests. For manifest-declared preset and extension layers, lookupId must exactly match the originating contribution's id. Preserve existing name-based behavior and document IDs as opaque strings.

Alternatives Considered

Install-time UUIDs are unsuitable because they differ across machines and reinstalls. Existing names are insufficient because they collide across sources and kinds. Content hashes are unsuitable because IDs would change whenever artifact content is edited. Array indexes are unsuitable for hooks because reordering entries would change their IDs.

A synthetic core:_:... contribution ID was considered for built-in assets. It was rejected because built-ins have no originating preset or extension manifest contribution to join to; the source-agnostic {kind}:{name} artifact ID provides their stable round-trip key without overloading lookupId.

Do not use the existing integration manifest as the ID source; it tracks installed file hashes and paths rather than manifest contribution identity.

Component

Specify CLI (initialization, commands)

AI Agent (if applicable)

No response

Use Cases

1. A wizard can read an artifact stack and follow each provenance-backed layer's lookupId to the full contribution detail without re-parsing manifests.
2. Developers on different machines can use identical IDs when reporting or diagnosing a contribution.
3. Tooling can hash or cache resolved compositions using public artifact IDs plus the available layer lookupId values.
4. Future JSON output for preset info, extension info, and specify artifact can expose consistent cross-references.

Acceptance Criteria

• Document the layer:sourceId:kind:name contribution grammar, the source-agnostic kind:name artifact ID, and the lookupId relationship in extensions/EXTENSION-API-REFERENCE.md and the preset API/manifest reference.
• Public preset/extension manifest and info representations expose computed id values for commands, templates, scripts, and hooks.
• Hook IDs are deterministic and collision-free without install paths or list indexes.
• Manifest-declared preset and extension artifact-stack layers expose lookupId equal to the corresponding contribution's id.
• Project-local override layers use the synthetic project:_:{kind}:{name} lookup form and intentionally have no manifest contribution match.
• Built-in artifact-stack layers expose no contribution provenance (layer, sourceId, and lookupId are null) and round-trip through the public {kind}:{name} artifact ID.
• Identical manifest coordinates produce identical IDs across processes, machines, project locations, and reinstalls.
• Manifest-backed IDs do not depend on artifact contents, timestamps, manifest hashes, archive paths, or installation directories.
• Existing name fields and name-based resolution remain unchanged.
• Tests cover each provenance-backed layer and artifact kind, hook uniqueness, resolver repeatability, manifest lookup round-trips, built-in public-ID round-trips, and backward compatibility.

Additional Context

This request defines the ID contract only. Adding the JSON output surfaces themselves for preset info --json, extension info --json, or specify artifact is out of scope and will be handled separately. Changing precedence, resolution, installation, or uninstall behavior is also out of scope. Relevant implementation areas include the extension manifest schema and validation and PresetResolver composition handling. IDs must not expose install paths, secrets, or connection strings.

[github-actions]

Feature assessment — contribution-ids-lookup · Stage 1/5: Intake

Idea Intake: Deterministic Contribution IDs and Stack Lookup IDs

• Slug: contribution-ids-lookup
• Created: 2026-08-19
• Source: GitHub issue [Feature]: Add deterministic contribution IDs and stack lookup IDs for resolved artifacts #4210 (labeled issue / pasted text)
• Type: new-capability

Idea (as captured)

Introduce computed, opaque id fields for every command, template, script, and hook returned by public manifest/info APIs, plus a lookupId field on every resolved artifact-stack layer.

For named artifacts, derive IDs using: {layer}:{sourceId}:{kind}:{name}

Use core, preset, or extension for layer; _ for the core source ID; and the preset or extension manifest ID for other sources. Use command, template, script, or hook for kind. Examples include preset:speckit.core:command:speckit.plan, extension:speckit.git:template:pr-body, and core:_:command:speckit.constitution.

For hooks, use {eventName}:{command} as the name component. Compute IDs at read/serialization/resolution time — never persist in authored or installed manifests. lookupId must exactly match the originating contribution's id. Preserve existing name-based behavior; document IDs as opaque strings.

Restated

The Spec Kit CLI needs stable, computed identifiers for every artifact contribution (commands, templates, scripts, hooks) and for every layer of a resolved artifact stack, so that consumers such as preset info --json, extension info --json, and future specify artifact tooling can reliably cross-reference contributions without relying on names that collide across sources and kinds.

Origin & Context

• Raised by: @nicolehaugen
• Trigger: Observed that artifact names collide across source layers and kinds; cross-referencing a resolved stack layer back to the exact manifest contribution is currently unreliable. The issue defines the ID contract only — JSON output surfaces are explicitly out of scope and handled separately.

First-Glance Unknowns

• [NEEDS CLARIFICATION: Which surfaces (preset info --json, extension info --json, specify artifact) are already implemented vs. still planned?]
• [NEEDS CLARIFICATION: Are hook duplicate entries (same event+command) currently valid or always rejected?]
• [NEEDS CLARIFICATION: Are there existing callers relying on the current source string format in resolved layers that would need migration?]
• [NEEDS CLARIFICATION: Is the "public API" scope Python library consumers, CLI JSON output only, or both?]

---

Posted on behalf of @nicolehaugen by GitHub Copilot (model: claude-sonnet-4.6, autonomous)

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4210 · 561.6 AIC · ⌖ 19.3 AIC · ⊞ 36.5K · ◷

[github-actions]

Feature assessment — contribution-ids-lookup · Stage 2/5: Research

Idea Research: Deterministic Contribution IDs and Stack Lookup IDs

• Slug: contribution-ids-lookup
• Created: 2026-08-19
• Evidence confidence (overall): medium

Users & Demand

• Spec Kit CLI maintainers and extension/preset authors currently have no stable cross-reference between a resolved artifact-stack layer and the manifest entry that contributed it — consumers must re-parse manifests or rely on path heuristics — (confidence: high, cited: codebase — PresetResolver.resolve() returns a Path only, no source attribution; WorkflowResolver.resolve_with_layers() returns Layer objects where source is a freeform string, not a structured ID)
• Tooling consumers (wizards, diagnostic tools, JSON clients) need a stable join key across machines and reinstalls; install-path–based keys change across environments — (confidence: high, cited: issue acceptance criterion feat: implement in Japanese #5)
• CI/CD and multi-machine teams would benefit from deterministic IDs for caching and composition hashing — (confidence: medium, ASSUMPTION — issue use case Update README.md #3, no external user signal found)

Prior Art

• Layer.source field (src/specify_cli/workflows/overlays/layer_sources.py): existing layers carry a source string and tier but no structured contribution ID; this is the closest current analog — (cited: codebase)
• Extension/preset id fields: ExtensionManifest.id and PresetManifest.id already provide stable slug-like identifiers ([a-z0-9-]+) that the proposed grammar reuses as sourceId — (cited: src/specify_cli/extensions/__init__.py, src/specify_cli/presets/__init__.py)
• No prior attempt found inside the Spec Kit repo to introduce a contribution-ID scheme; the current approach relies entirely on file paths and name strings — (cited: codebase search for lookupId, contribution_id, lookup_id — no matches)
• Ecosystem analogs: VS Code extensionId, NPM package identity, Cargo workspace crate IDs all use stable structured identifiers for provenance — (confidence: low, ASSUMPTION)

Market & Context

• Alternative today: consumers reconstruct origin by inspecting Layer.source (freeform string), install paths, or by re-parsing manifest YAML — fragile across project locations
• Cost of doing nothing: tooling that must join stack layers to contributions will require brittle, bespoke path-parsing heuristics per caller — (cited: issue body)

Data & Constraints

• IDs must be deterministic across processes/machines; must not depend on content, timestamps, install paths, or secrets — (cited: issue acceptance criteria feat: implement in Japanese #5, shell scripts in the scripts directory fail to execute #6)
• Existing name fields and name-based resolution must remain unchanged — (cited: issue acceptance criterion adding executable permission to the scripts so they execute when the … #7)
• Hook IDs: array-position discriminators are explicitly rejected; stable discriminator or duplicate rejection required — (cited: issue body)
• Scope boundary: JSON output surfaces for preset info --json, extension info --json, specify artifact are explicitly deferred — (cited: issue "Additional Context")
• Implementation areas named: ExtensionManifest, PresetManifest schema/validation, PresetResolver composition — (cited: issue body)

Evidence Against the Idea

• Adds API surface without an immediate consumer: JSON output surfaces that would consume id/lookupId are explicitly deferred; risk of over- or under-specifying the schema before consumers exist — (confidence: medium, cited: issue "Additional Context")
• Computed-at-read-time overhead: every manifest read and resolution call must compute and attach IDs; marginal but nonzero in large preset stacks — (confidence: low, ASSUMPTION)
• Hook uniqueness underspecified: "add a stable discriminator or reject duplicates" leaves ambiguity that could block implementation or force a later breaking schema change — (confidence: medium, cited: issue body)

Gaps & Open Questions

• [NEEDS CLARIFICATION: Are preset info --json, extension info --json, and specify artifact already partially implemented or only planned?]
• [NEEDS CLARIFICATION: Should duplicate hook entries (same event+command) be rejected at validation time, or is a stable discriminator approach preferred?]
• [NEEDS CLARIFICATION: Are there external Python consumers of PresetManifest, ExtensionManifest, or Layer that would need migration guidance?]

Sources

• Local codebase: src/specify_cli/presets/__init__.py, src/specify_cli/extensions/__init__.py, src/specify_cli/workflows/overlays/layer_sources.py (policy: allowlisted — local repo)
• GitHub issue [Feature]: Add deterministic contribution IDs and stack lookup IDs for resolved artifacts #4210 body (host: github.com, policy: allowlisted)

---

Posted on behalf of @nicolehaugen by GitHub Copilot (model: claude-sonnet-4.6, autonomous)

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4210 · 561.6 AIC · ⌖ 19.3 AIC · ⊞ 36.5K · ◷

[github-actions]

Feature assessment — contribution-ids-lookup · Stage 3/5: Problem

Problem Definition: Deterministic Contribution IDs and Stack Lookup IDs

• Slug: contribution-ids-lookup
• Created: 2026-08-19
• Inputs used: intake.md | research.md

Problem Statement

When Spec Kit resolves an artifact stack (commands, templates, scripts, hooks contributed by core, presets, and extensions), it returns layers identified only by freeform source strings and file paths — which differ across machines, project locations, and reinstalls — making it impossible for consumers to reliably cross-reference a resolved layer back to the exact manifest contribution that supplied it.

Affected Users & Stakeholders

• Users: Extension and preset authors, Spec Kit CLI maintainers, and tooling builders (wizards, diagnostic commands, JSON API consumers) — currently cannot build stable cross-references without fragile path-parsing heuristics
• Stakeholders: Spec Kit project maintainers — own the public manifest/info API shape and must provide a stable contract for downstream tooling

Goals

• Every command, template, script, and hook contribution has a computed, deterministic id (grammar: {layer}:{sourceId}:{kind}:{name})
• Every resolved artifact-stack layer exposes a lookupId matching the contributing manifest entry's id
• IDs are computed at read/serialization/resolution time; never stored in authored manifests
• Contract is documented in EXTENSION-API-REFERENCE.md and preset API/manifest reference
• Hook IDs are collision-free and stable (not position-based)

Non-Goals

• Exposing id/lookupId through preset info --json, extension info --json, or specify artifact JSON surfaces (deferred — handled separately)
• Changing precedence, resolution, installation, or uninstall behavior
• Changing existing name fields or name-based resolution
• Persisting IDs in authored or installed manifest files

Success Metrics

• All public manifest/info representations expose computed id for commands, templates, scripts, and hooks (baseline: 0 computed id fields today)
• Resolved artifact-stack layers expose lookupId equal to the corresponding contribution's id (baseline: lookupId field does not exist)
• Same manifest coordinates produce identical IDs across processes, machines, project locations, and reinstalls (baseline: current source strings vary by install path)
• Test coverage: every source layer and artifact kind, hook uniqueness, resolver repeatability, lookup round-trips, backward compatibility (baseline: no such tests exist)

Cost of Inaction

Without this, any tooling that needs to join a resolved stack layer back to its manifest contribution must resort to path-string heuristics that break across machines and reinstalls. As preset info --json and related surfaces are built out, each consumer must independently re-implement fragile origin reconstruction instead of using a stable, tested contract.

Open Questions

• [NEEDS CLARIFICATION: Are preset info --json, extension info --json, and specify artifact already partially implemented or only planned?]
• [NEEDS CLARIFICATION: Should duplicate hook entries (same event+command) be rejected at validation time, or should a stable discriminator be added?]
• [NEEDS CLARIFICATION: Are there external Python consumers of PresetManifest, ExtensionManifest, or Layer that need migration guidance?]

---

Posted on behalf of @nicolehaugen by GitHub Copilot (model: claude-sonnet-4.6, autonomous)

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4210 · 561.6 AIC · ⌖ 19.3 AIC · ⊞ 36.5K · ◷

[github-actions]

Feature assessment — contribution-ids-lookup · Stage 4/5: Concept

Concept: Deterministic Contribution IDs and Stack Lookup IDs

• Slug: contribution-ids-lookup
• Created: 2026-08-19
• Recommended option: Option A — Computed ID properties on existing manifest and layer objects

Options

Option A — Computed ID properties on existing manifest and layer objects

• Sketch: Add a computed id property to PresetManifest, ExtensionManifest, and the core contribution model. For each command, template, script, and hook entry read from a manifest, the ID is computed on-the-fly using {layer}:{sourceId}:{kind}:{name} (e.g., extension:speckit.git:template:pr-body). Add a lookupId field to resolved Layer/stack-layer objects set during resolution to the matching contribution's id. Document the grammar as opaque in EXTENSION-API-REFERENCE.md. Hook IDs use {eventName}:{command} as the name component; duplicate event+command hook entries are rejected at validation.
• Appetite: medium (weeks)
• Trade-offs: Clean and non-breaking; fits naturally onto existing objects; no schema changes to authored files; consistent with existing manifest id fields. Requires touching PresetManifest, ExtensionManifest, PresetResolver, the workflow overlay layer model, and comprehensive test suites.
• Rabbit holes: Hook deduplication policy is unspecified — must be decided (reject vs. discriminator suffix) before implementation. The Layer dataclass is shared across overlay and preset contexts; verifying no callsite depends on source's string shape needs investigation.

Option B — Central contribution-ID registry computed at install time

• Sketch: Cache a contribution ID map in .specify/ at install time; resolution looks up the cache.
• Appetite: large (months)
• Trade-offs: Faster lookups, richer metadata — but adds a new persisted artifact that can go stale and explicitly contradicts the issue's requirement to compute IDs at read/resolution time, not persist them.
• Rabbit holes: Stale-cache invalidation, cross-version compatibility. Ruled out by the issue.

Option C — Standalone ID-computation utility, no class changes

• Sketch: A contribution_id(layer, source_id, kind, name) utility function; callers opt in.
• Appetite: small (days)
• Trade-offs: Lowest risk, fastest. Does not satisfy the acceptance criteria requiring public manifest/info representations to expose computed id values — leaves consistency to callers.
• Rabbit holes: Future JSON-output surfaces must add ad hoc wiring.

Recommendation

Option A. It is the only option satisfying all acceptance criteria without contradicting the issue's constraints. Option B is explicitly ruled out; Option C does not meet the public-API requirement.

The hook deduplication question must be resolved before implementation — recommend rejection at validation as the simpler, safer default.

Out of Scope (for the recommended option)

• Exposing id/lookupId through preset info --json, extension info --json, or specify artifact CLI outputs (deferred per issue)
• Changing resolution precedence, installation, or uninstall behavior
• Persisting computed IDs to disk
• Project-override or user-overridable IDs

Assumptions to Validate

• The Layer dataclass can receive a lookupId field without breaking existing callsites
• No existing test or caller depends on the exact string content of Layer.source in a way that lookupId would need to replace
• Duplicate hook entries (same event+command) are rare enough that rejection at validation is not breaking
• The {layer}:{sourceId}:{kind}:{name} grammar is collision-free given [a-z0-9-]+ constraints on sourceId and [a-z0-9.-]+ on name

---

Posted on behalf of @nicolehaugen by GitHub Copilot (model: claude-sonnet-4.6, autonomous)

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4210 · 561.6 AIC · ⌖ 19.3 AIC · ⊞ 36.5K · ◷

[github-actions]

Feature assessment — contribution-ids-lookup · Stage 5/5: Decision — verdict needs-clarification

Decision: Deterministic Contribution IDs and Stack Lookup IDs

• Slug: contribution-ids-lookup
• Decided: 2026-08-19
• Verdict: needs-clarification
• Artifacts reviewed: intake.md | research.md | problem.md | concept.md

Scorecard

Criterion	Rating	Justification
Problem validity	strong	Real, codebase-evidenced gap: PresetResolver.resolve() returns a path with no structured source attribution; Layer.source is a freeform string that varies by install path. Cross-referencing stack layers to manifest contributions is genuinely impossible today without heuristics.
Evidence strength	weak	Demand signal comes almost entirely from the issue's stated use cases and codebase inspection. No external user signal (support tickets, interviews, usage data). The JSON output surfaces that would consume these IDs are explicitly deferred — no immediate consumer demonstrated.
Value vs. inaction	adequate	Without the ID contract, all future JSON-output consumers must independently implement fragile path-parsing. Establishing the contract now reduces that debt. Value is prospective (enables future work) rather than solving an active pain today.
Feasibility / appetite	strong	Option A (computed ID properties on existing manifest and layer objects) is clearly scoped at medium appetite. Grammar is well-defined. Existing id fields on ExtensionManifest/PresetManifest provide the sourceId building block. Implementation areas are named in the issue.
Strategic fit	adequate	Additive, non-breaking; fits naturally with the Spec Kit CLI trajectory toward richer JSON output and tooling APIs. Documents the contract in the extension API reference.
Risk posture	adequate	Key risks identified: hook deduplication policy is underspecified (reject vs. discriminator must be decided before implementation); Layer dataclass callsite impact needs verification. Tractable, but must be resolved before a go.

Verdict & Rationale

needs-clarification. The problem is valid and the concept is well-shaped (Option A is clearly the right approach). However, evidence strength is rated weak: there is no external demand signal, and the primary consumers of id/lookupId (preset info --json, extension info --json, specify artifact) are explicitly deferred and may not yet exist. The decide command's rules require evidence strength adequate+ for a go — thin evidence produces needs-clarification, not go.

Two implementation-blocking questions are also unresolved: the status of the consumer surfaces, and the hook deduplication policy. Once those are answered and an active consumer is confirmed, this idea has all the properties of a go.

If needs-clarification

• Blocking questions:
  • [NEEDS CLARIFICATION: Are preset info --json, extension info --json, and specify artifact already partially implemented or only planned? An active consumer in development substantially strengthens the urgency for this contract.]
  • [NEEDS CLARIFICATION: Should duplicate hook entries (same event+command) be rejected at validation time, or should a stable discriminator be appended? Must be decided before implementation to avoid a later breaking schema change.]
  • [NEEDS CLARIFICATION: Are there external Python consumers of PresetManifest, ExtensionManifest, or Layer that would need migration guidance when id/lookupId fields are added?]
• Revisit stage: research (gather evidence of active consumer demand) → shape/decide

---

Posted on behalf of @nicolehaugen by GitHub Copilot (model: claude-sonnet-4.6, autonomous)

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4210 · 561.6 AIC · ⌖ 19.3 AIC · ⊞ 36.5K · ◷

[nicolehaugen]

[NEEDS CLARIFICATION: Are preset info --json, extension info --json, and specify artifact already partially implemented or only planned? An active consumer in development substantially strengthens the urgency for this contract.] => The consumer is this Canvas app - currently, it is using it's own logic to obtain composition information on presets/extensions, but the goal is to remove this custom logic and get it directly from SpecKit:
https://github.com/github/spec-kit-copilot/tree/main/plugins/spec-kit-copilot-wizard => also see this issue: #4211

[NEEDS CLARIFICATION: Should duplicate hook entries (same event+command) be rejected at validation time, or should a stable discriminator be appended? Must be decided before implementation to avoid a later breaking schema change.] => Use descriminator.

[NEEDS CLARIFICATION: Are there external Python consumers of PresetManifest, ExtensionManifest, or Layer that would need migration guidance when id/lookupId fields are added?] =>My assumption is no.

[github-actions]

Feature assessment — contribution-ids-lookup · Stage 1/5: Intake

Idea Intake: Deterministic Contribution IDs and Stack Lookup IDs

• Slug: contribution-ids-lookup
• Created: 2026-08-19
• Source: GitHub issue [Feature]: Add deterministic contribution IDs and stack lookup IDs for resolved artifacts #4210 (github/spec-kit)
• Type: new-capability

Idea (as captured)

Title: [Feature]: Add deterministic contribution IDs and stack lookup IDs for resolved artifacts

Author: @nicolehaugen

Spec Kit identifies contributed commands, templates, scripts, and hooks primarily by name. Names can collide across artifact kinds and source layers, and a name alone cannot reliably link a resolved artifact-stack layer to the exact manifest contribution that supplied it. Consumers such as preset info --json, extension info --json, and specify artifact need stable contribution identifiers and a join key that works across reinstalls and machines.

Proposed Solution: Introduce computed, opaque id fields for every command, template, script, and hook returned by public manifest/info APIs, plus a lookupId field on every resolved artifact-stack layer, derived from {layer}:{sourceId}:{kind}:{name}. IDs computed at read/resolution time, not persisted in manifests. lookupId on stack layers must exactly match the originating contribution's id. Preserve existing name-based behavior.

Alternatives Considered: Install-time UUIDs (differ across machines/reinstalls), existing names (collide across sources/kinds), content hashes (change when content is edited), array indexes for hooks (fragile on reorder).

Restated

The request proposes adding computed, stable id fields (format: {layer}:{sourceId}:{kind}:{name}) to every command, template, script, and hook in Specify CLI's public manifest/info APIs, along with a matching lookupId on resolved artifact-stack layers, so that consumers can reliably join stack layers back to their contributing manifest entries across machines and reinstalls.

Origin & Context

• Raised by: @nicolehaugen
• Trigger: GitHub issue labeled feature-assess on 2026-08-19; the author observed that name-only identification causes collisions across artifact kinds and source layers, making reliable cross-referencing impossible for consumers of preset info --json, extension info --json, and specify artifact.

First-Glance Unknowns

• [NEEDS CLARIFICATION: Are there existing consumers of preset info --json / extension info --json that would need to be updated simultaneously, or is this additive?]
• [NEEDS CLARIFICATION: What is the exact public API surface today? The issue says adding the JSON output surface itself is out of scope — so where does the id field actually surface today?]
• [NEEDS CLARIFICATION: Are hook event names and command values guaranteed to be globally unique, or can the same event+command pair appear in multiple extensions/presets?]
• [NEEDS CLARIFICATION: Is there a preset API/manifest reference document referenced in the acceptance criteria?]

---

Posted on behalf of @nicolehaugen by GitHub Copilot (model: claude-sonnet-4.6, autonomous)

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4210 · 527.9 AIC · ⌖ 18.1 AIC · ⊞ 36.4K · ◷

[github-actions]

Feature assessment — contribution-ids-lookup · Stage 2/5: Research

Idea Research: Deterministic Contribution IDs and Stack Lookup IDs

• Slug: contribution-ids-lookup
• Created: 2026-08-19
• Evidence confidence (overall): medium

Users & Demand

• Specify CLI tooling consumers (wizards, CI pipelines) need stable cross-references when reading the artifact stack; today they must re-parse all manifests manually — [source: issue [Feature]: Add deterministic contribution IDs and stack lookup IDs for resolved artifacts #4210] (confidence: high, cited)
• PresetResolver.collect_all_layers() returns layers as raw dicts with path, source, and strategy keys; no id or lookupId field exists — [source: src/specify_cli/presets/__init__.py lines 5460–5490] (confidence: high, cited from code)
• The source field already encodes partial origin info (e.g. "extension:speckit.git v1.2.3", "preset:speckit.core", "core") but as an unstructured string, not a stable opaque key — [source: src/specify_cli/presets/__init__.py lines 1773, 5448–5458] (confidence: high, cited from code)

Prior Art

• Internal: Extension manifests expose manifest.id, manifest.commands, etc. — all accessed by name, no computed id on individual contributions — [source: src/specify_cli/extensions/__init__.py lines 668–724; EXTENSION-API-REFERENCE.md] (confidence: high, cited)
• Internal: Preset manifests use pack["id"] at preset level but provide no per-command/template/hook contribution ID — [source: src/specify_cli/presets/__init__.py line 490] (confidence: high, cited)
• No prior spec or design doc found in .specify/ for a contribution ID system — [source: file system search] (confidence: high)
• Industry pattern: Package managers use content-hash-free stable IDs like {registry}:{package}#{artifact} for lockfile references; this proposal follows a similar four-part grammar — [ASSUMPTION, no external citation; consistent with well-known pattern]

Market & Context

• Cost of doing nothing: Consumers of resolved stacks must write brittle string-parsing against the informal source field. This is already observable in _reconcile_composed_commands() which parses source.startswith("extension:") — [source: src/specify_cli/presets/__init__.py lines 1776, 1898] (confidence: high, cited)
• Additive change: IDs computed at read/resolution time without persisting to authored manifests — backward-compatible by design — [source: issue [Feature]: Add deterministic contribution IDs and stack lookup IDs for resolved artifacts #4210] (confidence: high, cited)

Data & Constraints

• Scope out (explicit): Adding JSON output surfaces for preset info --json, extension info --json, or specify artifact is out of scope — [source: issue [Feature]: Add deterministic contribution IDs and stack lookup IDs for resolved artifacts #4210, Additional Context]
• Scope out (explicit): Changing precedence, resolution, installation, or uninstall behavior is out of scope — [source: issue [Feature]: Add deterministic contribution IDs and stack lookup IDs for resolved artifacts #4210]
• Hook ID collision risk: If multiple extensions register the same {eventName}:{command} pair, the proposed grammar produces colliding IDs — [source: issue [Feature]: Add deterministic contribution IDs and stack lookup IDs for resolved artifacts #4210; EXTENSION-API-REFERENCE.md] (confidence: high)
• Grammar is simple: {layer}:{sourceId}:{kind}:{name} — four segments, no hashing, fully deterministic from manifest coordinates — [source: issue [Feature]: Add deterministic contribution IDs and stack lookup IDs for resolved artifacts #4210] (confidence: high)
• preset info and extension info do not currently emit --json — no --json flag on those commands today — [source: src/specify_cli/presets/_commands.py line 462; extensions/_commands.py line 1338] (confidence: medium)

Evidence Against the Idea

• The source field already partially captures what id would capture. Consumers tolerating an informal string could continue; no existing consumer is documented as broken today. The ID system adds formality but may be premature if JSON output surfaces are also deferred. (confidence: medium, ASSUMPTION)
• Hook collision ambiguity is unresolved. The proposal does not commit to one approach (reject duplicates vs. stable discriminator). This must be answered before implementation to avoid an unstable hook ID grammar. (confidence: high, cited from issue)
• No JSON output surface is introduced by this request. Without preset info --json or extension info --json, the only initial consumers are internal callers of collect_all_layers(). Benefit is real but incremental. (confidence: medium, cited from issue)

Gaps & Open Questions

• [NEEDS CLARIFICATION: How should duplicate {eventName}:{command} hook entries be handled — reject duplicates or add a stable discriminator?]
• [NEEDS CLARIFICATION: Does collect_all_layers() need a lookupId key in each returned layer dict, or only at a higher API boundary?]
• [NEEDS CLARIFICATION: Is there a preset API/manifest reference document currently defining the preset manifest structure?]

Sources

• GitHub issue [Feature]: Add deterministic contribution IDs and stack lookup IDs for resolved artifacts #4210 (host: github.com, policy: allowlisted)
• src/specify_cli/presets/__init__.py (local codebase)
• src/specify_cli/extensions/__init__.py (local codebase)
• extensions/EXTENSION-API-REFERENCE.md (local codebase)

---

Posted on behalf of @nicolehaugen by GitHub Copilot (model: claude-sonnet-4.6, autonomous)

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4210 · 527.9 AIC · ⌖ 18.1 AIC · ⊞ 36.4K · ◷