From 7748322ae9d4eb50ec0e387c5f8fac1fbec0b08b Mon Sep 17 00:00:00 2001 From: root Date: Mon, 20 Jul 2026 11:34:53 +0800 Subject: [PATCH 1/2] docs: clarify hook priority validation semantics --- docs/reference/extensions.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/reference/extensions.md b/docs/reference/extensions.md index 783b17888d..97c47064c7 100644 --- a/docs/reference/extensions.md +++ b/docs/reference/extensions.md @@ -221,12 +221,14 @@ Each hook entry supports the following fields: | `command` | Extension command associated with the hook. | | `enabled` | Whether the hook is active. Hooks with `enabled: false` are skipped. | | `optional` | Whether the hook is optional. If `true`, the hook is presented with its `prompt` and can be skipped; if `false`, the hook is emitted as an automatic hook (includes `EXECUTE_COMMAND` markers). | -| `priority` | Priority metadata for the hook. Values must be integers >= 1; invalid values fall back to the default priority `10`. Current command templates surface hooks in their configured YAML order and do not sort them by `priority`. | +| `priority` | Priority metadata for the hook. Registered hook entries use integer values >= 1; entries installed from manifests default to `10` when no priority is declared. Current command templates surface hooks in their configured YAML order and do not sort them by `priority`. | | `prompt` | Message shown when asking whether to run an optional hook. | | `description` | Human-readable explanation of what the hook does. | | `condition` | Optional expression evaluated by `HookExecutor` (using `config.` or `env.` with `is set`, `==`, or `!=`). Current command templates do not evaluate conditions and skip hooks with a non-empty condition. | Hook event names identify when a hook is invoked. They generally use `before_` or `after_`, such as `before_implement`, `after_implement`, `before_tasks`, and `after_tasks`. +Extension manifests reject invalid hook priorities during installation. If an existing `.specify/extensions.yml` file contains a missing or corrupted `priority` value, `HookExecutor.get_hooks_for_event()` treats that entry as priority `10` when sorting. + `HookExecutor.get_hooks_for_event()` returns hooks ordered by `priority`, with lower values first. However, current command templates read hook lists directly and surface them in their configured YAML order rather than using priority ordering. ## FAQ From 3795850d8a21b90297b967cb1d2209bf2ab5e639 Mon Sep 17 00:00:00 2001 From: root Date: Wed, 22 Jul 2026 09:50:25 +0800 Subject: [PATCH 2/2] docs: clarify stored hook priority normalization --- docs/reference/extensions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/extensions.md b/docs/reference/extensions.md index 97c47064c7..919617a087 100644 --- a/docs/reference/extensions.md +++ b/docs/reference/extensions.md @@ -227,7 +227,7 @@ Each hook entry supports the following fields: | `condition` | Optional expression evaluated by `HookExecutor` (using `config.` or `env.` with `is set`, `==`, or `!=`). Current command templates do not evaluate conditions and skip hooks with a non-empty condition. | Hook event names identify when a hook is invoked. They generally use `before_` or `after_`, such as `before_implement`, `after_implement`, `before_tasks`, and `after_tasks`. -Extension manifests reject invalid hook priorities during installation. If an existing `.specify/extensions.yml` file contains a missing or corrupted `priority` value, `HookExecutor.get_hooks_for_event()` treats that entry as priority `10` when sorting. +Extension manifests reject invalid hook priorities during installation. For existing `.specify/extensions.yml` entries, `HookExecutor.get_hooks_for_event()` sorts with `normalize_priority()`: missing values, booleans, non-numeric values rejected by `int()`, and values less than `1` fall back to `10`; numeric strings and finite floats are coerced with `int()`, while non-finite floats are unsupported and may fail instead of falling back. `HookExecutor.get_hooks_for_event()` returns hooks ordered by `priority`, with lower values first. However, current command templates read hook lists directly and surface them in their configured YAML order rather than using priority ordering.