[Feature]: Expose hook contributions and runtime bindings via specify artifact

[nicolehaugen]

Problem Statement

specify artifact list --json and specify artifact info --json unify preset/extension/built-in provenance for command, template, and script contributions. Hook contributions are deliberately excluded — ArtifactKind = Literal["command","template","script"] at src/specify_cli/artifacts/__init__.py:36, and _iter_pack_candidates at :790 filters any other kind out before the stack is built.

The domain model for hooks already exists internally:

• src/specify_cli/_identifier.py:174 derive_hook_id produces the deterministic contribution ID extension:{sourceId}:hook:{eventName}:{command} — matches the lookupId grammar the artifact command uses for other kinds.
• src/specify_cli/_identifier.py:55 _HOOK_LAYERS restricts hooks to preset / extension layers.
• src/specify_cli/extensions/__init__.py:795-824 EnhancedManifest.iter_contributions() already emits kind:"hook" entries carrying layer, sourceId, name ("{eventName}:{command}"), id (via derive_hook_id), and the raw manifest fields (eventName, command, optional, priority, description, handler).
• src/specify_cli/extensions/__init__.py:79 DEFAULT_HOOK_PRIORITY, :181 normalize_priority, :203 coerce_hook_entries, :5247 priority-sort — full normalization/ordering infrastructure.

The runtime binding state — which declared hooks are actually enabled — lives in .specify/extensions.yml under a top-level hooks: map keyed by event name, managed by ExtensionConfig at src/specify_cli/extensions/__init__.py:4860 and the enable/disable paths at _commands.py:2639, :2709. There is no --json surface for this state today.

Because neither the declared hook contributions nor the runtime binding state are exposed, the speckit-wizard-canvas consumer is forced to re-parse .specify/extensions/<id>/extension.yml and .specify/extensions.yml from disk (plugins/spec-kit-copilot-wizard/extensions/speckit-wizard-canvas/composition/hooks.mjs) — the exact anti-pattern #4210, #4212, and #4305 were introduced to eliminate for other artifact kinds. The header comment in that file states the constraint explicitly:

"The specify artifact CLI doesn't emit hook metadata — hook attribution is a wizard concern. This module reads extension manifests and .specify/extensions.yml directly to feed the hook enrichment step in composition/artifact-cli.mjs."

Existing consumers reading hook state from disk must handle:

1. The manifest declaration shape (per-extension extension.yml, hooks: field, object-of-events or array-of-entries).
2. The runtime binding shape (.specify/extensions.yml, hooks: field, event-keyed arrays of {extension, command, optional, description}).
3. Deriving lookupIds themselves — duplicating derive_hook_id's grammar in JavaScript.
4. Reconciling "declared but not registered" vs "declared and registered" — a wizard-only concept today.

Proposed Solution

1. Extend ArtifactKind to include "hook":

ArtifactKind = Literal["command", "template", "script", "hook"]

Drop the corresponding filter in _iter_pack_candidates (artifacts/__init__.py:790) so hook entries from iter_contributions() flow through the stack builder.

2. Serialize hook contributions into specify artifact list --json and info --json using the same top-level shape as other kinds, plus the hook-specific fields already present on iter_contributions():

{
  "id": "hook:before_specify:speckit.compliance.pre-check",
  "name": "before_specify:speckit.compliance.pre-check",
  "kind": "hook",
  "description": "Enforces internal policy checks before specification runs.",
  "eventName": "before_specify",
  "targetCommand": "speckit.compliance.pre-check",
  "optional": false,
  "priority": 10,
  "registered": true,
  "stack": [
    {
      "id": "hook:before_specify:speckit.compliance.pre-check",
      "layer": "extension",
      "sourceId": "compliance",
      "presetId": null,
      "presetName": null,
      "strategy": "replace",
      "active": true,
      "hidden": false,
      "manifestPath": ".specify/extensions/compliance/extension.yml",
      "lookupId": "extension:compliance:hook:before_specify:speckit.compliance.pre-check"
    }
  ]
}

Field notes:

• id uses the top-level round-trip shorthand hook:{eventName}:{command} — analogous to command:{name} / template:{name} / script:{name} — so specify artifact info hook:before_specify:speckit.compliance.pre-check --json round-trips.
• stack[].lookupId uses the existing derive_hook_id grammar ({layer}:{sourceId}:hook:{eventName}:{command}); no new grammar is invented.
• strategy is fixed to "replace" on hook layers (hooks are additive per (event, command) pair; there is no wrap/prepend/append semantic for hook layers, matching the existing invariant that any strategy key on an extension provides entry is rejected).
• active marks the priority-sorted winner among duplicate (event, command) declarations from different sources (already computed by the priority-sort at extensions/__init__.py:5247).
• registered is a top-level artifact field, not a per-layer field: it reflects whether any layer of this hook is currently enabled in .specify/extensions.yml. A declared-but-not-registered hook still appears in the catalog (so the wizard can render "declared but disabled" state) — it just carries registered: false.

3. Compute registered by reading .specify/extensions.yml's hooks map through the existing ExtensionConfig API. Match declarations to bindings by (sourceId, eventName, command); when the runtime binding omits command, treat all commands from that extension for that event as registered (this matches today's implicit behavior in enable_hooks/disable_hooks at _commands.py:2639/:2709).

4. Extend the artifact-error taxonomy so artifact info on an unknown hook shorthand returns the same unknown-artifact shape as unknown commands/templates/scripts.

5. Do not introduce a separate specify hook command group. bundle, preset, and extension are installers; artifact is the introspection surface for what's composed. Hooks are contributions, not installables, so they belong under artifact (the same reasoning that keeps commands/templates/scripts there).

6. Add coverage in docs/reference/artifacts.md: extend the fields table, add a "Hook artifacts" subsection covering the hook:{event}:{command} shorthand, registered semantics, and the invariant that hooks only appear on preset and extension layers (_HOOK_LAYERS).

Alternatives Considered

• Add a separate specify hook list --json command. Rejected — hooks are contributions, not installables. Splitting them from artifact re-fragments the introspection surface the wizard just consolidated in #4305, and every consumer that wants "everything in this project" would have to fan out to two commands.
• Emit hooks only in artifact info, not in artifact list. Rejected — the wizard's Composition tab needs every artifact including hooks in one call. Withholding hooks from list reintroduces the N+1 shell-out pattern the list-with-stack change removed for other kinds.
• Expose only declared hooks; make registered a wizard concern. Rejected — the wizard would still have to read .specify/extensions.yml directly, defeating the "CLI is source of truth" boundary. ExtensionConfig already owns that file; folding the flag in at serialization time is one map lookup per hook artifact.
• Emit registered per stack layer instead of at the artifact top level. Rejected — enable/disable in .specify/extensions.yml is a per-extension binding, not a per-layer property, and hooks don't stack in the wrap/prepend/append sense that other artifacts do. A top-level registered matches the actual semantic.
• Keep parsing extension.yml on the wizard side. Rejected — same reason #4212 rejected keeping preset resolve text-parsing: the CLI is the source of truth for the composition graph. Any wizard-side manifest read is a drift risk (schema evolves, wizard silently miscounts) and duplicates ID-derivation logic (derive_hook_id grammar) in JavaScript.

Component

Specify CLI — artifact catalog, extensions, JSON contracts.

AI Agent (if applicable)

Not applicable.

Use Cases

1. speckit-wizard-canvas deletes composition/hooks.mjs (~140 lines of manifest parsing + .specify/extensions.yml walking) and reads hook metadata straight from the CLI, matching how it already reads commands / templates / scripts after #4305.
2. A debugger renders "which hooks fire on before_specify, and are any of them disabled?" from a single artifact list --json call filtered by kind=="hook" and eventName=="before_specify".
3. Reproducibility tooling can identify every hook contributed to a project — including declared-but-not-registered ones — without walking installed extension manifests on disk.
4. Future consumers (CI, external UIs) get one JSON contract for the composition graph, not one for {command, template, script} and a second for hook.

Acceptance Criteria

• ArtifactKind at src/specify_cli/artifacts/__init__.py:36 includes "hook".
• _iter_pack_candidates at src/specify_cli/artifacts/__init__.py:790 accepts "hook" and forwards hook contributions from iter_contributions() into the stack builder.
• specify artifact list --json includes one row per unique (eventName, command) hook contribution across all installed presets and extensions, with the same top-level shape as other kinds plus eventName, targetCommand, optional, priority, registered.
• specify artifact info hook:{eventName}:{command} --json returns the full stack for that hook.
• stack[].lookupId for every hook layer equals derive_hook_id(layer, sourceId, eventName, command) — no re-derivation, no new grammar.
• Hooks only appear on preset and extension layers; the built-in tier does not synthesize a core layer for hooks (they have no baseline).
• stack[].strategy is fixed to "replace" for hook layers.
• stack[].active marks the priority-sorted winner (using existing normalize_priority + DEFAULT_HOOK_PRIORITY) when multiple layers declare the same (eventName, command).
• Top-level registered reflects .specify/extensions.yml's hooks: map: true when any layer's sourceId appears under the event's binding array (with matching or omitted command), else false. A declared-but-not-registered hook still appears in list output.
• specify artifact info on an unknown hook shorthand emits the existing unknown-artifact error shape.
• Documentation at docs/reference/artifacts.md covers the hook kind, hook:{eventName}:{command} shorthand, registered semantics, and the _HOOK_LAYERS invariant.
• Tests cover: hook contribution surfacing from preset and extension layers; lookupId parity with derive_hook_id; active selection under conflicting priorities; registered true/false paths against a scaffolded .specify/extensions.yml; round-trip of hook:{event}:{command} through info; absence of hooks from the built-in tier; error shape on unknown hook.
• No change to command, template, or script shapes — the addition is additive.

Additional Context

Direct consumer: plugins/spec-kit-copilot-wizard — specifically extensions/speckit-wizard-canvas/composition/hooks.mjs and the hook-attribution passes in extensions/speckit-wizard-canvas/composition/artifact-cli.mjs:220-366. Those files exist solely because the artifact CLI does not surface hook data — the header comment on hooks.mjs states this explicitly. Closing this issue lets the wizard delete both the manifest-reading module and the client-side attribution pass, aligning hook handling with the CLI-as-source-of-truth model #4305 introduced for the other three kinds.

Depends on #4305 (contribution ID grammar + artifact command). Related to #4210 (stable per-contribution ID scheme) — hooks reuse derive_hook_id, which was defined for exactly this purpose. Related to #4212 (the artifact command itself) — this issue extends its coverage to the fourth contribution kind. Independent of #4208 (source provenance) — this issue is about what artifacts a source contributed, whereas #4208 is about where a source came from.

Scope note (out of scope). Hook execution — the runtime dispatch that fires enabled hooks around lifecycle events — is unchanged. This issue is scoped to introspection: exposing what hooks are declared, what is registered, and where each contribution came from.

[github-actions]

Feature assessment — hook-artifact-exposure · Stage 1/5: Intake

Idea Intake: Expose Hook Contributions via Artifact CLI

• Slug: hook-artifact-exposure
• Created: 2026-08-26
• Source: GitHub issue [Feature]: Expose hook contributions and runtime bindings via specify artifact #4343 (github/spec-kit), labeled feature-assess
• Type: improvement

Idea (as captured)

The specify artifact list --json and specify artifact info --json commands (being introduced in PR #4305) unify preset/extension/built-in provenance for command, template, and script contributions, but deliberately exclude hook contributions. The proposal is to extend ArtifactKind to include "hook", remove the filter that excludes hooks from the stack builder, and serialize hook contributions — including their runtime registered state from .specify/extensions.yml — into the artifact catalog JSON output.

Restated

The feature proposes that specify artifact list --json and specify artifact info --json include hook contributions alongside commands, templates, and scripts, with a registered flag reflecting runtime binding state, so that external consumers (primarily speckit-wizard-canvas) can drop their direct manifest-parsing code and rely solely on the CLI as the source of truth for the composition graph.

Origin & Context

• Raised by: @nicolehaugen
• Trigger: The speckit-wizard-canvas plugin currently re-parses .specify/extensions/*/extension.yml and .specify/extensions.yml directly (~140 lines in composition/hooks.mjs) to get hook metadata — the exact anti-pattern that PR feat: add deterministic contribution IDs and specify artifact command #4305 was introduced to eliminate for commands/templates/scripts. This issue closes the remaining gap.

First-Glance Unknowns

• [NEEDS CLARIFICATION: Is PR feat: add deterministic contribution IDs and specify artifact command #4305 merged yet? This issue is marked as depending on it, and the specify artifact command does not yet exist in the current codebase (confirmed at runtime: specify artifact returns "No such command").]
• [NEEDS CLARIFICATION: What is the expected timeline / priority relative to feat: add deterministic contribution IDs and specify artifact command #4305 landing?]
• [NEEDS CLARIFICATION: Are there consumers beyond speckit-wizard-canvas that would immediately benefit?]
• [NEEDS CLARIFICATION: Does the registered field need to track partial bindings (where .specify/extensions.yml binds an extension for an event but without specifying individual commands)?]

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4343 · 580 AIC · ⌖ 27.4 AIC · ⊞ 36.5K · ◷

[github-actions]

Feature assessment — hook-artifact-exposure · Stage 2/5: Research

Idea Research: Expose Hook Contributions via Artifact CLI

• Slug: hook-artifact-exposure
• Created: 2026-08-26
• Evidence confidence (overall): high

Users & Demand

• Direct stated consumer: speckit-wizard-canvas (composition/hooks.mjs, ~140 lines) explicitly states in its header comment that it parses manifests directly because the CLI does not surface hook data. This is concrete, acknowledged technical debt — [source: issue [Feature]: Expose hook contributions and runtime bindings via specify artifact #4343 body] (confidence: high, cited)
• Secondary consumer need: composition/artifact-cli.mjs:220–366 contains hook-attribution passes that would be removable once the CLI exposes hooks — [source: issue [Feature]: Expose hook contributions and runtime bindings via specify artifact #4343 body] (confidence: high, cited)
• Pattern evidence: Issues [Feature]: Add deterministic contribution IDs and stack lookup IDs for resolved artifacts #4210, [Feature]: Add specify artifact command exposing composition stacks as JSON #4212, and PR feat: add deterministic contribution IDs and specify artifact command #4305 were all introduced to eliminate the "consumers reading manifests directly" anti-pattern for other artifact kinds; this issue is the natural fourth extension of that arc — [source: issue [Feature]: Expose hook contributions and runtime bindings via specify artifact #4343 references, PR feat: add deterministic contribution IDs and specify artifact command #4305] (confidence: high, cited)
• Future consumers: CI tooling, external UIs, reproducibility tooling named as hypothetical beneficiaries — [source: issue [Feature]: Expose hook contributions and runtime bindings via specify artifact #4343 Use Cases] (confidence: medium, assumption — no concrete external consumer named beyond the wizard)

Prior Art

• PR feat: add deterministic contribution IDs and specify artifact command #4305 (open at assessment time): Introduces specify artifact list --json and specify artifact info --json for command, template, script kinds. Hooks deliberately excluded. This is the direct predecessor and dependency — [source: PR feat: add deterministic contribution IDs and specify artifact command #4305] (confidence: high, cited)
• Issue [Feature]: Add deterministic contribution IDs and stack lookup IDs for resolved artifacts #4210: Introduced the stable per-contribution ID scheme that derive_hook_id reuses — [source: issue [Feature]: Expose hook contributions and runtime bindings via specify artifact #4343] (confidence: high, cited)
• Issue [Feature]: Add specify artifact command exposing composition stacks as JSON #4212: Introduced the artifact command itself — [source: issue [Feature]: Expose hook contributions and runtime bindings via specify artifact #4343] (confidence: high, cited)
• _HOOK_LAYERS and derive_hook_id at src/specify_cli/_identifier.py:174, :55 (per issue): The hook ID grammar already exists internally — [source: issue [Feature]: Expose hook contributions and runtime bindings via specify artifact #4343 body; file not found in current working tree, likely part of un-merged PR feat: add deterministic contribution IDs and specify artifact command #4305] (confidence: medium, cited with caveat)
• EnhancedManifest.iter_contributions() at src/specify_cli/extensions/__init__.py:795–824 (per issue): Already emits kind:"hook" entries with all required fields — [source: issue [Feature]: Expose hook contributions and runtime bindings via specify artifact #4343 body; runtime grep confirmed hook infrastructure at lines 73–5136] (confidence: medium, cited)

Market & Context

• Cost of doing nothing: speckit-wizard-canvas maintains ~140+ lines of bespoke manifest-walking JavaScript duplicating derive_hook_id's grammar. Any manifest schema change requires coordinated updates to both CLI and wizard — a drift risk. — [source: issue [Feature]: Expose hook contributions and runtime bindings via specify artifact #4343 body] (confidence: high, cited)
• Alternative today: Direct parsing of .specify/extensions/*/extension.yml and .specify/extensions.yml. Works but is fragile against schema evolution. — [source: issue [Feature]: Expose hook contributions and runtime bindings via specify artifact #4343 body] (confidence: high, cited)

Data & Constraints

• Existing hook infrastructure confirmed in current codebase: DEFAULT_HOOK_PRIORITY (line 73), normalize_priority (line 185), coerce_hook_entries (line 207), hook validation (lines 380–537), ExtensionManifest.hooks property (line 724) all present in src/specify_cli/extensions/__init__.py — [source: runtime grep, confidence: high, cited]
• specify artifact command absent in current codebase: Command does not yet exist (specify artifact returns "No such command" at runtime). PR feat: add deterministic contribution IDs and specify artifact command #4305 is the gate — [source: runtime verification, confidence: high, cited]
• Scope: Hook execution runtime is explicitly out of scope — introspection only — [source: issue [Feature]: Expose hook contributions and runtime bindings via specify artifact #4343 scope note] (confidence: high, cited)
• registered semantics: Determined by .specify/extensions.yml hooks: map via ExtensionConfig API; partial bindings (extension-level, no command) treat all commands for that event as registered — [source: issue [Feature]: Expose hook contributions and runtime bindings via specify artifact #4343] (confidence: high, cited)

Evidence Against the Idea

• Hard dependency on un-merged PR feat: add deterministic contribution IDs and specify artifact command #4305: The specify artifact command doesn't exist yet. This issue cannot be implemented until feat: add deterministic contribution IDs and specify artifact command #4305 lands. — (confidence: high, cited)
• Limited concrete consumers today: Beyond speckit-wizard-canvas, no other concrete named consumers identified. The wizard could theoretically adapt its existing parsing rather than requiring a CLI change — though that is acknowledged as the anti-pattern. — (confidence: medium, cited)
• strategy: "replace" is a fixed constant: Slightly asymmetric with other artifact kinds where strategy varies. Not a blocking concern. — (confidence: medium, cited)

Gaps & Open Questions

• [NEEDS CLARIFICATION: PR feat: add deterministic contribution IDs and specify artifact command #4305 must land first — what is its merge timeline?]
• [NEEDS CLARIFICATION: Does _identifier.py (introduced by feat: add deterministic contribution IDs and specify artifact command #4305) already expose derive_hook_id and _HOOK_LAYERS exactly as the issue claims?]
• [NEEDS CLARIFICATION: Are there extensions in production already declaring hooks for regression testing?]

Sources

• Issue [Feature]: Expose hook contributions and runtime bindings via specify artifact #4343 body (github.com, policy: allowlisted)
• PR feat: add deterministic contribution IDs and specify artifact command #4305 (github.com, policy: allowlisted)
• Runtime grep of src/specify_cli/extensions/__init__.py
• Runtime specify artifact --help — confirmed command absence

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4343 · 580 AIC · ⌖ 27.4 AIC · ⊞ 36.5K · ◷

[github-actions]

Feature assessment — hook-artifact-exposure · Stage 3/5: Problem

Problem Definition: Expose Hook Contributions via Artifact CLI

• Slug: hook-artifact-exposure
• Created: 2026-08-26
• Inputs used: intake.md | research.md

Problem Statement

Hook contributions declared by extensions and presets are invisible to the specify artifact CLI surface, forcing external consumers to parse raw extension manifests and the runtime bindings file (.specify/extensions.yml) directly — duplicating internal ID-derivation logic and creating a fragile coupling to schema internals that the CLI is specifically designed to abstract.

Affected Users & Stakeholders

• Users: Developers building on speckit-wizard-canvas and similar tooling — they experience the problem as ~140 lines of bespoke manifest-parsing code that must be kept in sync with CLI internals, and which silently breaks when manifest schemas evolve.
• Users: Any external tool, CI system, or UI wanting a complete composition graph (commands + templates + scripts + hooks) from a single artifact list --json call — currently impossible.
• Stakeholders: Spec Kit maintainers — they carry the risk that diverging schema interpretations between wizard and CLI cause silent bugs for end users.
• Stakeholders: Consumers of the speckit-wizard-canvas "Composition" tab — they experience incorrect or incomplete hook state if the wizard's parsing drifts from the CLI's interpretation.

Goals

• Hooks exposed as first-class artifacts in specify artifact list --json and artifact info --json with the same top-level shape as other kinds plus hook-specific fields (eventName, targetCommand, optional, priority, registered).
• registered flag accurately reflects runtime binding state from .specify/extensions.yml so consumers don't need to read that file.
• stack[].lookupId for hook layers equals derive_hook_id(...) — no new grammar, no re-derivation in consumers.
• speckit-wizard-canvas can delete composition/hooks.mjs and hook-attribution passes in artifact-cli.mjs once this ships.
• specify artifact info hook:{event}:{command} --json round-trip works correctly, including unknown-artifact error shape.

Non-Goals

• Hook execution runtime changes (dispatch, ordering, triggering)
• A separate specify hook command group
• Changes to command, template, or script artifact shapes
• Wizard UI implementation (follow-up in wizard repo)

Success Metrics

• specify artifact list --json output includes all hook contributions from installed presets and extensions (baseline: 0 hook entries today)
• speckit-wizard-canvas deletes composition/hooks.mjs (~140 lines) and associated attribution passes
• No regression in the existing test suite (1132+ tests per PR feat: add deterministic contribution IDs and specify artifact command #4305)
• All 11 acceptance criteria checkboxes in issue [Feature]: Expose hook contributions and runtime bindings via specify artifact #4343 are green

Cost of Inaction

speckit-wizard-canvas continues to maintain fragile direct manifest parsing for hooks while all other artifact kinds are served by the CLI. Any manifest schema change requires coordinated edits in both CLI and wizard, with no type safety or test coverage at the boundary. The Spec Kit "CLI as source of truth" model remains half-finished until hooks are included.

Open Questions

• [NEEDS CLARIFICATION: PR feat: add deterministic contribution IDs and specify artifact command #4305 (the dependency) is currently open — what is its expected merge date?]
• [NEEDS CLARIFICATION: Does _identifier.py (introduced by feat: add deterministic contribution IDs and specify artifact command #4305) already expose derive_hook_id and _HOOK_LAYERS as the issue claims?]
• [NEEDS CLARIFICATION: Are there production extensions that already declare hooks, making regression testing immediately possible?]

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4343 · 580 AIC · ⌖ 27.4 AIC · ⊞ 36.5K · ◷

[github-actions]

Feature assessment — hook-artifact-exposure · Stage 4/5: Concept

Concept: Expose Hook Contributions via Artifact CLI

• Slug: hook-artifact-exposure
• Created: 2026-08-26
• Recommended option: Option A — Extend artifact catalog with hook kind

Options

Option A — Extend artifact catalog with hook kind

• Sketch: After PR feat: add deterministic contribution IDs and specify artifact command #4305 lands, extend ArtifactKind to include "hook", remove the filter that currently excludes hooks from _iter_pack_candidates, and wire iter_contributions()'s existing kind:"hook" entries into the stack builder with hook-specific serialization fields (eventName, targetCommand, optional, priority, registered). Top-level id uses shorthand hook:{event}:{command}; stack layer lookupId reuses derive_hook_id. The registered flag is a single map lookup against ExtensionConfig's hooks: binding. Add hook:{event}:{command} to the artifact info unknown-artifact error path. Add documentation in docs/reference/artifacts.md.
• Appetite: small (days — the domain model already exists; this is surfacing it through an established pattern)
• Trade-offs: Wins: eliminates hooks.mjs and attribution passes in wizard; makes composition graph complete; no new grammar. Sacrifices: requires feat: add deterministic contribution IDs and specify artifact command #4305 to land first; adds a fixed strategy: "replace" field that is always the same constant (slightly asymmetric with other kinds).
• Rabbit holes: Correctly matching "registered" state when a binding in .specify/extensions.yml omits command (implicit all-commands) vs. when it names a specific command — the matching logic must handle both cases exactly as enable_hooks/disable_hooks do. Diverging here would produce incorrect registered values.

Option B — Separate specify hook list --json command

• Sketch: Add a new top-level specify hook command group with list and info subcommands, independent of specify artifact. Consumers that want hooks call specify hook list --json; consumers that want everything fan out to both commands.
• Appetite: small-medium (new command scaffolding required; same underlying infrastructure)
• Trade-offs: Wins: no change to artifact command surface. Sacrifices: re-fragments the introspection surface that PR feat: add deterministic contribution IDs and specify artifact command #4305 unified; consumers wanting the full composition graph must merge two JSON streams. Explicitly rejected in the issue's Alternatives Considered section.
• Rabbit holes: Maintaining parity between artifact and hook JSON shapes over time; two separate command surfaces to document and test.

Option C — Do nothing / defer until demand grows

• Sketch: Leave hooks absent from the artifact catalog. The wizard continues using hooks.mjs. Document the gap in docs/reference/artifacts.md as a known limitation.
• Appetite: negligible
• Trade-offs: Wins: zero implementation risk. Sacrifices: leaves wizard manifest-parsing debt in place; violates the "CLI as source of truth" principle established by [Feature]: Add deterministic contribution IDs and stack lookup IDs for resolved artifacts #4210–feat: add deterministic contribution IDs and specify artifact command #4305; technical debt grows with adoption.
• Rabbit holes: None.

Recommendation

Option A. The domain model (hook infrastructure, iter_contributions(), derive_hook_id, ExtensionConfig) already exists; the main work is removing a filter and writing a serialization path that mirrors the established pattern for commands/templates/scripts. The issue is tightly specified with exact acceptance criteria, a concrete consumer waiting to delete ~140 lines of fragile code, and no new conceptual surface to design. Option B was explicitly rejected by the issue author for sound architectural reasons. Option C preserves technical debt the project has committed to eliminating.

The only timing constraint: this cannot land until PR #4305 is merged.

Out of Scope (for Option A)

• Hook execution runtime changes
• A separate specify hook command group
• Changes to command, template, or script shapes
• Wizard UI updates
• Hooks on the core (built-in) layer — _HOOK_LAYERS restricts to preset and extension

Assumptions to Validate

• PR feat: add deterministic contribution IDs and specify artifact command #4305 exposes derive_hook_id, _HOOK_LAYERS, and EnhancedManifest.iter_contributions() with kind:"hook" entries as claimed — these are the exact integration points for Option A.
• ExtensionConfig API provides a clean hooks: map lookup without additional infrastructure.
• The implicit-all-commands binding edge case can be replicated from the existing enable_hooks/disable_hooks behavior with a few lines.

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4343 · 580 AIC · ⌖ 27.4 AIC · ⊞ 36.5K · ◷

[github-actions]

Feature assessment — hook-artifact-exposure · Stage 5/5: Decision — verdict go

Decision: Expose Hook Contributions via Artifact CLI

• Slug: hook-artifact-exposure
• Decided: 2026-08-26
• Verdict: go
• Artifacts reviewed: intake.md | research.md | problem.md | concept.md

Scorecard

Criterion	Rating	Justification
Problem validity	strong	Concrete fragile consumer (hooks.mjs, ~140 lines of manifest-parsing) with an acknowledged header comment stating the gap. Problem is real, scoped, and causing active maintenance risk.
Evidence strength	adequate	Direct codebase evidence (hook infrastructure confirmed in extensions/__init__.py), concrete consumer code confirmed by issue author, PR #4305 as cited dependency. Filed by a maintainer with detailed technical evidence including specific line numbers. _identifier.py paths not directly confirmed in working tree (part of un-merged #4305), but issue author's specificity and confirmed hook infrastructure give adequate confidence.
Value vs. inaction	strong	Deletes ~140+ lines of fragile wizard-side manifest parsing, closes the last gap in the "CLI as source of truth" model, and eliminates a drift risk that grows with adoption. Concrete, measurable cleanup.
Feasibility / appetite	strong	Domain model already exists; work is surfacing it through an established pattern. Issue provides precise acceptance criteria and implementation pointers. Estimated small appetite (days). Hard dependency on #4305, which is open and in review.
Strategic fit	strong	Directly continues the trajectory of #4210 → #4212 → #4305 → this issue. Aligns exactly with the stated "CLI as source of truth" principle. No strategic conflicts.
Risk posture	strong	Key risks identified and manageable: (1) #4305 dependency — tracked, in review; (2) implicit-all-commands registered matching edge case — explicitly called out in concept, matches existing enable_hooks/disable_hooks behavior; (3) strategy: "replace" asymmetry — cosmetic, not functional. No unmitigated risk.

Verdict & Rationale

Go. Problem validity is strong, evidence is adequate (direct codebase confirmation of hook infrastructure, concrete named consumer, maintainer-authored request with line-number specificity), value is concrete (measurable code deletion), feasibility is small appetite, strategic fit is exact, and risks are understood and bounded. The only sequencing constraint — PR #4305 must land first — is a normal dependency, not a blocking unknown. The acceptance criteria are complete and testable; the recommended option (Option A) is a narrowly scoped extension of an established pattern with no new design surface.

Handoff to speckit.specify

• Problem: Hook contributions declared by extensions and presets are invisible to specify artifact list/info --json, forcing external consumers to parse raw manifests directly — duplicating internal ID logic and creating fragile schema coupling.
• Chosen approach: Option A — extend ArtifactKind to include "hook", remove the exclusion filter in _iter_pack_candidates, wire iter_contributions()'s kind:"hook" entries into the stack builder, serialize hook-specific fields (eventName, targetCommand, optional, priority, registered), and add artifact info unknown-hook error handling. Reuse derive_hook_id for stack[].lookupId; shorthand hook:{event}:{command} for top-level id.
• In scope: ArtifactKind extension; hook serialization in list and info; registered computation from ExtensionConfig; unknown-artifact error shape for hooks; docs/reference/artifacts.md coverage.
• Out of scope: Hook execution runtime; specify hook command group; changes to other artifact kind shapes; wizard UI updates.
• Success metrics: artifact list --json returns hook entries; speckit-wizard-canvas deletes hooks.mjs; no regression in existing test suite; all 11 acceptance criteria checkboxes green.
• Carried-forward open questions:
  • [NEEDS CLARIFICATION: Confirm PR feat: add deterministic contribution IDs and specify artifact command #4305 exposes derive_hook_id, _HOOK_LAYERS, and EnhancedManifest.iter_contributions() with kind:"hook" entries exactly as claimed — these are the integration points.]
  • [NEEDS CLARIFICATION: Confirm feat: add deterministic contribution IDs and specify artifact command #4305 merge timeline so this issue can be sequenced immediately after.]
  • [NEEDS CLARIFICATION: Are there existing hook-declaring extensions in production for regression testing?]

Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for issue #4343 · 580 AIC · ⌖ 27.4 AIC · ⊞ 36.5K · ◷