feat(extensions): per-event hook lists with priority ordering (#2798)

* feat(extensions): per-event hook lists with priority ordering

The manifest validator restricted each hook event to a single mapping,
even though HookExecutor stores entries as a list per event. This blocked
an extension from running multiple commands on one event (e.g. a
verification step plus a doc-generation step after speckit.plan), and
get_hooks_for_event returned entries in raw insertion order with no way
to influence execution order across or within extensions.

This change:

1. Validator: accept hooks.<event> as either a single mapping or a list
   of mappings. Each entry is validated individually and may carry an
   optional integer `priority` (>= 1, default 10; bool rejected).
2. Command-ref normalization: apply rename / alias->canonical rewriting
   to every entry in the list, not just the head.
3. register_hooks: expand list entries, persist `priority`, and
   purge-and-replace all entries owned by the extension on each event so a
   reinstall whose shape changed (single<->list, or a shorter list) leaves
   no orphaned entries behind.
4. get_hooks_for_event: sort enabled entries by `priority` ascending with
   a stable sort (ties keep insertion order). The existing
   normalize_priority helper is reused as the sort key so corrupted
   on-disk values fall back to the default instead of raising.

Backward compatible: existing single-mapping manifests parse and register
unchanged with priority defaulting to 10. The extension-level `priority`
used by preset/template resolution is independent of the new hook-entry
`priority`.

Implements #2378

* fix(extensions): harden register_hooks per PR review

- Skip non-dict hook entries before .get() so a manifest that bypasses
  validation can't crash register_hooks with AttributeError.
- Normalize `priority` on save via normalize_priority so the on-disk
  config stays clean, mirroring the read-side defense in
  get_hooks_for_event.
- Tests: cover the non-dict-entry skip and add encoding="utf-8" to the
  new tests' manifest writes.

* fix(extensions): purge dropped-event hook orphans on reinstall

register_hooks only purged events the new manifest still declared, so an
extension that dropped an event on reinstall left stale entries for it in
the project config. Purge this extension's entries from undeclared events
(and prune emptied events) before registering; scoped to this extension,
and a no-op for the install/update flow where unregister_hooks runs first.

* fix(extensions): reject boolean priority and complete orphan purge

- normalize_priority falls back to default for bool values
- dedup deletes duplicate commands before re-insert for last-wins ties
- register_hooks purges orphans even when all hooks are dropped

* docs(extensions): document per-event hook lists and priority

- EXTENSION-API-REFERENCE: hook event accepts a mapping or list; add
  priority field reference and last-wins dedup note
- EXTENSION-DEVELOPMENT-GUIDE: add list-form example with priority

* docs(extensions): show both single and list hook forms in schema snippet

* docs(extensions): reference DEFAULT_HOOK_PRIORITY in normalize_priority

normalize_priority hard-coded the default as the literal 10 in both its
signature and docstring, duplicating DEFAULT_HOOK_PRIORITY. Reference the
constant in the signature and drop the literal from the docstring so the
default has a single source of truth.

Author: seiya-koji

extensions/EXTENSION-API-REFERENCE.md

@@ -52,13 +52,19 @@ provides:
       description: string
       required: boolean  # Default: false
 
-hooks:                   # Optional, event hooks
+hooks:                   # Optional, event hooks. Each event accepts either form below.
   event_name:            # e.g., "after_specify", "after_plan", "after_tasks", "after_implement"
     command: string      # Command to execute
+    priority: integer    # Optional, >= 1, default 10 (lower runs first)
     optional: boolean    # Default: true
     prompt: string       # Prompt text for optional hooks
     description: string  # Hook description
     condition: string    # Optional, condition expression
+  another_event:         # Any event may instead use a list of mappings (multiple commands)
+    - command: string    # Same fields as the single mapping, per entry
+      priority: integer
+    - command: string
+      priority: integer
 
 tags:                    # Optional, array of tags (2-10 recommended)
   - string
@@ -109,8 +115,10 @@ defaults:                # Optional, default configuration values
 
 - **Type**: object
 - **Keys**: Event names (e.g., `after_specify`, `after_plan`, `after_tasks`, `after_implement`, `before_analyze`)
+- **Value**: A single hook mapping, or a list of hook mappings to register multiple commands on one event
 - **Description**: Hooks that execute at lifecycle events
 - **Events**: Defined by core spec-kit commands
+- **Ordering**: Within an event, hooks run by ascending `priority` (integer ≥ 1, default 10; lower runs first; equal priorities keep authoring order via a stable sort)
 
 ---
 
@@ -535,7 +543,9 @@ Examples:
 
 ### Hook Definition
 
-**In extension.yml**:
+Each event accepts either a single hook mapping or a list of mappings. A list registers multiple commands on the same event.
+
+**Single mapping (in extension.yml)**:
 
 ```yaml
 hooks:
@@ -547,6 +557,24 @@ hooks:
     condition: null
 ```
 
+**List of mappings with priority**:
+
+```yaml
+hooks:
+  after_plan:
+    - command: "speckit.my-ext.verify"
+      priority: 5
+      optional: false
+      description: "Verify the plan"
+    - command: "speckit.my-ext.report"
+      priority: 10
+      optional: true
+      prompt: "Generate the report?"
+      description: "Generate a report from the plan"
+```
+
+Within a single manifest list, a repeated `command` is deduped as "last wins" and moved to the end, so it also breaks equal-priority ties in authoring order.
+
 ### Hook Events
 
 Standard events (defined by core):

extensions/EXTENSION-DEVELOPMENT-GUIDE.md

@@ -206,9 +206,12 @@ Available hook points:
 - `before_constitution` / `after_constitution`: Before/after constitution update
 - `before_taskstoissues` / `after_taskstoissues`: Before/after tasks-to-issues conversion
 
+Each event accepts a single hook object or a list of hook objects (multiple commands on one event).
+
 Hook object:
 
 - `command`: Command to execute (typically from `provides.commands`, but can reference any registered command)
+- `priority`: Run order within the event (integer ≥ 1, default 10; lower runs first; equal priorities keep authoring order)
 - `optional`: If true, prompt user before executing
 - `prompt`: Prompt text for optional hooks
 - `description`: Hook description
@@ -655,6 +658,23 @@ hooks:
     description: "Analyze tasks after generation"
 ```
 
+Multiple commands on one event, ordered by `priority` (lower runs first):
+
+```yaml
+# extension.yml
+hooks:
+  after_plan:
+    - command: "speckit.my-ext.verify"
+      priority: 5
+      optional: false
+      description: "Verify the plan"
+    - command: "speckit.my-ext.report"
+      priority: 10
+      optional: true
+      prompt: "Generate the report?"
+      description: "Generate a report from the plan"
+```
+
 ---
 
 ## Troubleshooting

extensions/template/extension.yml

@@ -79,6 +79,14 @@ hooks:
   #   optional: false  # Auto-execute without prompting
   #   description: "Runs automatically after implementation"
 
+  # MULTIPLE COMMANDS ON ONE EVENT: use a list of entries.
+  # Add optional `priority` (integer >= 1, default 10) to order them, lowest first.
+  # after_plan:
+  #   - command: "speckit.my-extension.verify"
+  #     priority: 5
+  #   - command: "speckit.my-extension.report"
+  #     priority: 10
+
 # CUSTOMIZE: Add relevant tags (2-5 recommended)
 # Used for discovery in catalog
 tags:

src/specify_cli/extensions.py

@@ -41,6 +41,8 @@
 })
 EXTENSION_COMMAND_NAME_PATTERN = re.compile(r"^speckit\.([a-z0-9-]+)\.([a-z0-9-]+)$")
 
+DEFAULT_HOOK_PRIORITY = 10
+
 REINSTALL_COMMAND = "uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git"
 
 
@@ -89,26 +91,37 @@ class CompatibilityError(ExtensionError):
     pass
 
 
-def normalize_priority(value: Any, default: int = 10) -> int:
+def normalize_priority(value: Any, default: int = DEFAULT_HOOK_PRIORITY) -> int:
     """Normalize a stored priority value for sorting and display.
 
-    Corrupted registry data may contain missing, non-numeric, or non-positive
-    values. In those cases, fall back to the default priority.
+    Corrupted registry data may contain missing, non-numeric, non-positive, or
+    boolean values. In those cases, fall back to the default priority.
 
     Args:
         value: Priority value to normalize (may be int, str, None, etc.)
-        default: Default priority to use for invalid values (default: 10)
+        default: Default priority to use for invalid values
 
     Returns:
         Normalized priority as positive integer (>= 1)
     """
+    if isinstance(value, bool):
+        return default
     try:
         priority = int(value)
     except (TypeError, ValueError):
         return default
     return priority if priority >= 1 else default
 
 
+def coerce_hook_entries(hook_config: Any) -> List[Any]:
+    """Return a hook event's config as a list of entries.
+
+    A hook event may be declared as a single mapping or a list of mappings.
+    Both shapes are normalized to a list so callers can iterate uniformly.
+    """
+    return hook_config if isinstance(hook_config, list) else [hook_config]
+
+
 @dataclass
 class CatalogEntry(BaseCatalogEntry):
     """Represents a single catalog entry in the catalog stack."""
@@ -215,17 +228,36 @@ def _validate(self):
                 "Extension must provide at least one command or hook"
             )
 
-        # Validate hook values (if present)
+        # Validate hook values (if present).
+        # Each event is a single mapping or a list of mappings.
         if hooks:
             for hook_name, hook_config in hooks.items():
-                if not isinstance(hook_config, dict):
+                if isinstance(hook_config, list) and not hook_config:
                     raise ValidationError(
-                        f"Invalid hook '{hook_name}': expected a mapping"
-                    )
-                if not hook_config.get("command"):
-                    raise ValidationError(
-                        f"Hook '{hook_name}' missing required 'command' field"
+                        f"Invalid hook '{hook_name}': list must contain at least one entry"
                     )
+                for entry in coerce_hook_entries(hook_config):
+                    if not isinstance(entry, dict):
+                        raise ValidationError(
+                            f"Invalid hook '{hook_name}': "
+                            "expected a mapping or list of mappings"
+                        )
+                    if not entry.get("command"):
+                        raise ValidationError(
+                            f"Hook '{hook_name}' missing required 'command' field"
+                        )
+                    if "priority" in entry:
+                        priority = entry["priority"]
+                        if not isinstance(priority, int) or isinstance(priority, bool):
+                            raise ValidationError(
+                                f"Hook '{hook_name}' has invalid 'priority': "
+                                "must be an integer"
+                            )
+                        if priority < 1:
+                            raise ValidationError(
+                                f"Hook '{hook_name}' has invalid 'priority': "
+                                "must be >= 1"
+                            )
 
         # Validate commands; track renames so hook references can be rewritten.
         rename_map: Dict[str, str] = {}
@@ -275,28 +307,30 @@ def _validate(self):
         # an alias-form ref (ext.cmd → speckit.ext.cmd).  Always emit a warning when
         # the reference is changed so extension authors know to update the manifest.
         for hook_name, hook_data in self.data.get("hooks", {}).items():
-            if not isinstance(hook_data, dict):
-                raise ValidationError(
-                    f"Hook '{hook_name}' must be a mapping, got {type(hook_data).__name__}"
-                )
-            command_ref = hook_data.get("command")
-            if not isinstance(command_ref, str):
-                continue
-            # Step 1: apply any rename from the auto-correction pass.
-            after_rename = rename_map.get(command_ref, command_ref)
-            # Step 2: lift alias-form '{ext_id}.cmd' to canonical 'speckit.{ext_id}.cmd'.
-            parts = after_rename.split(".")
-            if len(parts) == 2 and parts[0] == ext["id"]:
-                final_ref = f"speckit.{ext['id']}.{parts[1]}"
-            else:
-                final_ref = after_rename
-            if final_ref != command_ref:
-                hook_data["command"] = final_ref
-                self.warnings.append(
-                    f"Hook '{hook_name}' referenced command '{command_ref}'; "
-                    f"updated to canonical form '{final_ref}'. "
-                    f"The extension author should update the manifest."
-                )
+            for entry in coerce_hook_entries(hook_data):
+                if not isinstance(entry, dict):
+                    raise ValidationError(
+                        f"Hook '{hook_name}' must be a mapping or list of mappings, "
+                        f"got {type(entry).__name__}"
+                    )
+                command_ref = entry.get("command")
+                if not isinstance(command_ref, str):
+                    continue
+                # Step 1: apply any rename from the auto-correction pass.
+                after_rename = rename_map.get(command_ref, command_ref)
+                # Step 2: lift alias-form '{ext_id}.cmd' to canonical 'speckit.{ext_id}.cmd'.
+                parts = after_rename.split(".")
+                if len(parts) == 2 and parts[0] == ext["id"]:
+                    final_ref = f"speckit.{ext['id']}.{parts[1]}"
+                else:
+                    final_ref = after_rename
+                if final_ref != command_ref:
+                    entry["command"] = final_ref
+                    self.warnings.append(
+                        f"Hook '{hook_name}' referenced command '{command_ref}'; "
+                        f"updated to canonical form '{final_ref}'. "
+                        f"The extension author should update the manifest."
+                    )
 
     @staticmethod
     def _try_correct_command_name(name: str, ext_id: str) -> Optional[str]:
@@ -2734,9 +2768,6 @@ def register_hooks(self, manifest: ExtensionManifest):
         # Always ensure the extension is in the installed list
         self.register_extension(manifest.id)
 
-        if not hasattr(manifest, "hooks") or not manifest.hooks:
-            return
-
         config = self.get_project_config()
 
         # Ensure config is a dict (defensive)
@@ -2762,39 +2793,68 @@ def register_hooks(self, manifest: ExtensionManifest):
                         config["hooks"][h_name] = sanitized_h_list
                         changed = True
 
+        # Purge this extension's entries from events the new manifest no longer
+        # declares, so dropping an event on reinstall leaves no orphans.
+        declared_events = set(manifest.hooks.keys())
+        for h_name in list(config["hooks"].keys()):
+            if h_name in declared_events:
+                continue
+            kept = [
+                h for h in config["hooks"][h_name]
+                if not (isinstance(h, dict) and h.get("extension") == manifest.id)
+            ]
+            if kept != config["hooks"][h_name]:
+                config["hooks"][h_name] = kept
+                changed = True
+
         # Register each hook
         for hook_name, hook_config in manifest.hooks.items():
             if hook_name not in config["hooks"] or not isinstance(config["hooks"][hook_name], list):
                 config["hooks"][hook_name] = []
                 changed = True
 
-            # Add hook entry
-            hook_entry = {
-                "extension": manifest.id,
-                "command": hook_config.get("command"),
-                "enabled": True,
-                "optional": hook_config.get("optional", True),
-                "prompt": hook_config.get(
-                    "prompt", f"Execute {hook_config.get('command')}?"
-                ),
-                "description": hook_config.get("description", ""),
-                "condition": hook_config.get("condition"),
-            }
+            # Key by command to dedup within the manifest. Deleting before
+            # re-insert moves a duplicate to the end so "last wins" also breaks ties.
+            new_entries: Dict[str, Dict[str, Any]] = {}
+            for entry in coerce_hook_entries(hook_config):
+                if not isinstance(entry, dict):
+                    continue
+                command = entry.get("command")
+                if not command:
+                    continue
+                if command in new_entries:
+                    del new_entries[command]
+                new_entries[command] = {
+                    "extension": manifest.id,
+                    "command": command,
+                    "enabled": True,
+                    "optional": entry.get("optional", True),
+                    "priority": normalize_priority(
+                        entry.get("priority"), DEFAULT_HOOK_PRIORITY
+                    ),
+                    "prompt": entry.get("prompt", f"Execute {command}?"),
+                    "description": entry.get("description", ""),
+                    "condition": entry.get("condition"),
+                }
 
-            # Deduplicate: remove all existing entries for this extension on this
-            # hook event, then append the single canonical entry. This prevents
-            # multiple hooks firing when hand-edited or older versions leave
-            # duplicate entries behind. (Feedback from review)
+            # Purge then re-add all of this extension's entries for the event.
+            # A reinstall with a changed shape (single<->list or a shorter list)
+            # then leaves no orphaned entries behind.
             original_list = config["hooks"][hook_name]
             deduped = [
                 h for h in original_list
                 if not (isinstance(h, dict) and h.get("extension") == manifest.id)
             ]
-            deduped.append(hook_entry)
+            deduped.extend(new_entries.values())
             if deduped != original_list:
                 config["hooks"][hook_name] = deduped
                 changed = True
 
+        non_empty = {name: hooks for name, hooks in config["hooks"].items() if hooks}
+        if non_empty != config["hooks"]:
+            config["hooks"] = non_empty
+            changed = True
+
         if changed:
             self.save_project_config(config)
 
@@ -2838,19 +2898,26 @@ def unregister_hooks(self, extension_id: str):
         self.save_project_config(config)
 
     def get_hooks_for_event(self, event_name: str) -> List[Dict[str, Any]]:
-        """Get all registered hooks for a specific event.
+        """Get all enabled hooks for a specific event, sorted by priority ascending.
+
+        Lower ``priority`` runs first. Ties keep insertion order via a stable
+        sort. Missing or corrupted on-disk priorities fall back to the default.
 
         Args:
             event_name: Name of the event (e.g., 'after_tasks')
 
         Returns:
-            List of hook configurations
+            List of enabled hook configurations sorted by priority.
         """
         config = self.get_project_config()
         hooks = config.get("hooks", {}).get(event_name, [])
 
         # Filter to enabled hooks only
-        return [h for h in hooks if h.get("enabled", True)]
+        enabled = [h for h in hooks if h.get("enabled", True)]
+        return sorted(
+            enabled,
+            key=lambda h: normalize_priority(h.get("priority"), DEFAULT_HOOK_PRIORITY),
+        )
 
     def should_execute_hook(self, hook: Dict[str, Any]) -> bool:
         """Determine if a hook should be executed based on its condition.