fix(extensions): make mandatory-hook dispatch contract self-contained

extensions/EXTENSION-API-REFERENCE.md

@@ -631,10 +631,23 @@ Or for mandatory hooks:
 
 ```markdown
 **Automatic Hook**: {extension}
-Executing: `/{command}`
+Executing: `{invocation}`
 EXECUTE_COMMAND: {command}
+EXECUTE_COMMAND_INVOCATION: {invocation}
 ```
 
+Here `{invocation}` is the environment-correct command form: usually `/{command}`, but
+skills-mode sessions render it as e.g. `/skill:speckit-*` or `$speckit-*`.
+
+> **Dispatch contract**: the `EXECUTE_COMMAND:` line is only a dispatch signal for CLI
+> orchestrators that watch agent output — emitting it does not execute anything by
+> itself. Because the agent cannot reliably tell whether such an orchestrator is
+> present, it is instructed to invoke the hook itself and wait for the result. It does
+> so using the `EXECUTE_COMMAND_INVOCATION:` line, which carries the environment-correct
+> invocation (skills mode renders it as e.g. `/skill:speckit-*` or `$speckit-*` rather
+> than `/<command>`). Extension authors should not assume an external dispatcher will
+> pick up the directive.
+
 ---
 
 ## CLI Commands

src/specify_cli/extensions.py

@@ -3057,6 +3057,21 @@ def format_hook_message(
                 lines.append(f"Executing: `{display_invocation}`")
                 lines.append(f"EXECUTE_COMMAND: {command_text}")
                 lines.append(f"EXECUTE_COMMAND_INVOCATION: {display_invocation}")
+                # The directive lines above are only a dispatch signal for
+                # CLI orchestrators that watch agent output; emitting them
+                # does not run anything. The agent cannot reliably tell
+                # whether such an orchestrator is present, so the contract is
+                # unconditional: invoke the hook yourself. ``display_invocation``
+                # is the environment-correct form (skills mode renders e.g.
+                # ``/skill:speckit-*`` rather than ``/<command>``). Without
+                # this, mandatory hooks are silently skipped (issue #2730).
+                lines.append(
+                    "\nEmitting the EXECUTE_COMMAND directive above does not "
+                    "run the hook. You MUST now invoke the hook yourself using "
+                    f"`{display_invocation}` (the invocation shown on the "
+                    "EXECUTE_COMMAND_INVOCATION line) and wait for it to "
+                    "complete before continuing."
+                )
 
         return "\n".join(lines)
 

templates/commands/analyze.md

@@ -40,11 +40,14 @@ You **MUST** consider the user input before proceeding (if not empty).
     ## Extension Hooks
 
     **Automatic Pre-Hook**: {extension}
-    Executing: `/{command}`
+    Executing: `{invocation}`
     EXECUTE_COMMAND: {command}
+    EXECUTE_COMMAND_INVOCATION: {invocation}
 
     Wait for the result of the hook command before proceeding to the Goal.
     ```
+  - Here `{invocation}` is the command form for the current environment: usually `/{command}`, but skills-mode sessions render it differently (e.g. `/skill:speckit-*` or `$speckit-*`). Use the same value for both the `Executing:` and `EXECUTE_COMMAND_INVOCATION:` lines.
+  - **Dispatch contract for mandatory hooks**: the `EXECUTE_COMMAND:` line is only a dispatch signal for CLI orchestrators that watch agent output — emitting it does not run anything. You MUST then invoke the hook yourself using `{invocation}` (the value on the `EXECUTE_COMMAND_INVOCATION:` line) and wait for its result before proceeding.
 - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
 
 ## Goal
@@ -225,9 +228,12 @@ After reporting, check if `.specify/extensions.yml` exists in the project root.
     ## Extension Hooks
 
     **Automatic Hook**: {extension}
-    Executing: `/{command}`
+    Executing: `{invocation}`
     EXECUTE_COMMAND: {command}
+    EXECUTE_COMMAND_INVOCATION: {invocation}
     ```
+  - Here `{invocation}` is the command form for the current environment: usually `/{command}`, but skills-mode sessions render it differently (e.g. `/skill:speckit-*` or `$speckit-*`). Use the same value for both the `Executing:` and `EXECUTE_COMMAND_INVOCATION:` lines.
+  - **Dispatch contract for mandatory hooks**: the `EXECUTE_COMMAND:` line is only a dispatch signal for CLI orchestrators that watch agent output — emitting it does not run anything. You MUST then invoke the hook yourself using `{invocation}` (the value on the `EXECUTE_COMMAND_INVOCATION:` line) and wait for its result before reporting completion.
 - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
 
 ## Operating Principles

templates/commands/checklist.md

@@ -61,11 +61,14 @@ You **MUST** consider the user input before proceeding (if not empty).
     ## Extension Hooks
 
     **Automatic Pre-Hook**: {extension}
-    Executing: `/{command}`
+    Executing: `{invocation}`
     EXECUTE_COMMAND: {command}
+    EXECUTE_COMMAND_INVOCATION: {invocation}
 
     Wait for the result of the hook command before proceeding to the Execution Steps.
     ```
+  - Here `{invocation}` is the command form for the current environment: usually `/{command}`, but skills-mode sessions render it differently (e.g. `/skill:speckit-*` or `$speckit-*`). Use the same value for both the `Executing:` and `EXECUTE_COMMAND_INVOCATION:` lines.
+  - **Dispatch contract for mandatory hooks**: the `EXECUTE_COMMAND:` line is only a dispatch signal for CLI orchestrators that watch agent output — emitting it does not run anything. You MUST then invoke the hook yourself using `{invocation}` (the value on the `EXECUTE_COMMAND_INVOCATION:` line) and wait for its result before proceeding.
 - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
 
 ## Execution Steps
@@ -360,7 +363,10 @@ Check if `.specify/extensions.yml` exists in the project root.
     ## Extension Hooks
 
     **Automatic Hook**: {extension}
-    Executing: `/{command}`
+    Executing: `{invocation}`
     EXECUTE_COMMAND: {command}
+    EXECUTE_COMMAND_INVOCATION: {invocation}
     ```
+  - Here `{invocation}` is the command form for the current environment: usually `/{command}`, but skills-mode sessions render it differently (e.g. `/skill:speckit-*` or `$speckit-*`). Use the same value for both the `Executing:` and `EXECUTE_COMMAND_INVOCATION:` lines.
+  - **Dispatch contract for mandatory hooks**: the `EXECUTE_COMMAND:` line is only a dispatch signal for CLI orchestrators that watch agent output — emitting it does not run anything. You MUST then invoke the hook yourself using `{invocation}` (the value on the `EXECUTE_COMMAND_INVOCATION:` line) and wait for its result before reporting completion.
 - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently

templates/commands/clarify.md

@@ -44,11 +44,14 @@ You **MUST** consider the user input before proceeding (if not empty).
     ## Extension Hooks
 
     **Automatic Pre-Hook**: {extension}
-    Executing: `/{command}`
+    Executing: `{invocation}`
     EXECUTE_COMMAND: {command}
+    EXECUTE_COMMAND_INVOCATION: {invocation}
 
     Wait for the result of the hook command before proceeding to the Outline.
     ```
+  - Here `{invocation}` is the command form for the current environment: usually `/{command}`, but skills-mode sessions render it differently (e.g. `/skill:speckit-*` or `$speckit-*`). Use the same value for both the `Executing:` and `EXECUTE_COMMAND_INVOCATION:` lines.
+  - **Dispatch contract for mandatory hooks**: the `EXECUTE_COMMAND:` line is only a dispatch signal for CLI orchestrators that watch agent output — emitting it does not run anything. You MUST then invoke the hook yourself using `{invocation}` (the value on the `EXECUTE_COMMAND_INVOCATION:` line) and wait for its result before proceeding.
 - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
 
 ## Outline
@@ -248,9 +251,12 @@ Check if `.specify/extensions.yml` exists in the project root.
     ## Extension Hooks
 
     **Automatic Hook**: {extension}
-    Executing: `/{command}`
+    Executing: `{invocation}`
     EXECUTE_COMMAND: {command}
+    EXECUTE_COMMAND_INVOCATION: {invocation}
     ```
+  - Here `{invocation}` is the command form for the current environment: usually `/{command}`, but skills-mode sessions render it differently (e.g. `/skill:speckit-*` or `$speckit-*`). Use the same value for both the `Executing:` and `EXECUTE_COMMAND_INVOCATION:` lines.
+  - **Dispatch contract for mandatory hooks**: the `EXECUTE_COMMAND:` line is only a dispatch signal for CLI orchestrators that watch agent output — emitting it does not run anything. You MUST then invoke the hook yourself using `{invocation}` (the value on the `EXECUTE_COMMAND_INVOCATION:` line) and wait for its result before reporting completion.
   - **Optional hook** (`optional: true`):
     ```
     ## Extension Hooks
@@ -278,5 +284,5 @@ Report completion (after questioning loop ends or early termination):
 
 - [ ] Spec ambiguities identified and clarifications integrated into spec file
 - [ ] Spec quality checklist re-validated against updated spec (if `FEATURE_DIR/checklists/requirements.md` exists)
-- [ ] Extension hooks dispatched or skipped according to the rules in Mandatory Post-Execution Hooks above
+- [ ] Extension hooks dispatched or skipped according to the rules in Mandatory Post-Execution Hooks above (mandatory hooks actually invoked and completed — emitting `EXECUTE_COMMAND:` alone does not count as dispatched)
 - [ ] Completion reported to user with questions answered, sections touched, checklist status, and coverage summary

templates/commands/constitution.md

@@ -41,11 +41,14 @@ You **MUST** consider the user input before proceeding (if not empty).
     ## Extension Hooks
 
     **Automatic Pre-Hook**: {extension}
-    Executing: `/{command}`
+    Executing: `{invocation}`
     EXECUTE_COMMAND: {command}
+    EXECUTE_COMMAND_INVOCATION: {invocation}
 
     Wait for the result of the hook command before proceeding to the Outline.
     ```
+  - Here `{invocation}` is the command form for the current environment: usually `/{command}`, but skills-mode sessions render it differently (e.g. `/skill:speckit-*` or `$speckit-*`). Use the same value for both the `Executing:` and `EXECUTE_COMMAND_INVOCATION:` lines.
+  - **Dispatch contract for mandatory hooks**: the `EXECUTE_COMMAND:` line is only a dispatch signal for CLI orchestrators that watch agent output — emitting it does not run anything. You MUST then invoke the hook yourself using `{invocation}` (the value on the `EXECUTE_COMMAND_INVOCATION:` line) and wait for its result before proceeding.
 - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
 
 ## Outline
@@ -144,7 +147,10 @@ Check if `.specify/extensions.yml` exists in the project root.
     ## Extension Hooks
 
     **Automatic Hook**: {extension}
-    Executing: `/{command}`
+    Executing: `{invocation}`
     EXECUTE_COMMAND: {command}
+    EXECUTE_COMMAND_INVOCATION: {invocation}
     ```
+  - Here `{invocation}` is the command form for the current environment: usually `/{command}`, but skills-mode sessions render it differently (e.g. `/skill:speckit-*` or `$speckit-*`). Use the same value for both the `Executing:` and `EXECUTE_COMMAND_INVOCATION:` lines.
+  - **Dispatch contract for mandatory hooks**: the `EXECUTE_COMMAND:` line is only a dispatch signal for CLI orchestrators that watch agent output — emitting it does not run anything. You MUST then invoke the hook yourself using `{invocation}` (the value on the `EXECUTE_COMMAND_INVOCATION:` line) and wait for its result before reporting completion.
 - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently

templates/commands/implement.md

@@ -40,11 +40,14 @@ You **MUST** consider the user input before proceeding (if not empty).
     ## Extension Hooks
 
     **Automatic Pre-Hook**: {extension}
-    Executing: `/{command}`
+    Executing: `{invocation}`
     EXECUTE_COMMAND: {command}
+    EXECUTE_COMMAND_INVOCATION: {invocation}
 
     Wait for the result of the hook command before proceeding to the Outline.
     ```
+  - Here `{invocation}` is the command form for the current environment: usually `/{command}`, but skills-mode sessions render it differently (e.g. `/skill:speckit-*` or `$speckit-*`). Use the same value for both the `Executing:` and `EXECUTE_COMMAND_INVOCATION:` lines.
+  - **Dispatch contract for mandatory hooks**: the `EXECUTE_COMMAND:` line is only a dispatch signal for CLI orchestrators that watch agent output — emitting it does not run anything. You MUST then invoke the hook yourself using `{invocation}` (the value on the `EXECUTE_COMMAND_INVOCATION:` line) and wait for its result before proceeding.
 - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
 
 ## Outline
@@ -189,9 +192,12 @@ Check if `.specify/extensions.yml` exists in the project root.
     ## Extension Hooks
 
     **Automatic Hook**: {extension}
-    Executing: `/{command}`
+    Executing: `{invocation}`
     EXECUTE_COMMAND: {command}
+    EXECUTE_COMMAND_INVOCATION: {invocation}
     ```
+  - Here `{invocation}` is the command form for the current environment: usually `/{command}`, but skills-mode sessions render it differently (e.g. `/skill:speckit-*` or `$speckit-*`). Use the same value for both the `Executing:` and `EXECUTE_COMMAND_INVOCATION:` lines.
+  - **Dispatch contract for mandatory hooks**: the `EXECUTE_COMMAND:` line is only a dispatch signal for CLI orchestrators that watch agent output — emitting it does not run anything. You MUST then invoke the hook yourself using `{invocation}` (the value on the `EXECUTE_COMMAND_INVOCATION:` line) and wait for its result before reporting completion.
   - **Optional hook** (`optional: true`):
     ```
     ## Extension Hooks
@@ -212,5 +218,5 @@ Report final status with summary of completed work.
 
 - [ ] All tasks in tasks.md completed and marked `[X]`
 - [ ] Implementation validated against specification, plan, and test coverage
-- [ ] Extension hooks dispatched or skipped according to the rules in Mandatory Post-Execution Hooks above
+- [ ] Extension hooks dispatched or skipped according to the rules in Mandatory Post-Execution Hooks above (mandatory hooks actually invoked and completed — emitting `EXECUTE_COMMAND:` alone does not count as dispatched)
 - [ ] Completion reported to user with summary of completed work

templates/commands/plan.md

@@ -48,11 +48,14 @@ You **MUST** consider the user input before proceeding (if not empty).
     ## Extension Hooks
 
     **Automatic Pre-Hook**: {extension}
-    Executing: `/{command}`
+    Executing: `{invocation}`
     EXECUTE_COMMAND: {command}
+    EXECUTE_COMMAND_INVOCATION: {invocation}
 
     Wait for the result of the hook command before proceeding to the Outline.
     ```
+  - Here `{invocation}` is the command form for the current environment: usually `/{command}`, but skills-mode sessions render it differently (e.g. `/skill:speckit-*` or `$speckit-*`). Use the same value for both the `Executing:` and `EXECUTE_COMMAND_INVOCATION:` lines.
+  - **Dispatch contract for mandatory hooks**: the `EXECUTE_COMMAND:` line is only a dispatch signal for CLI orchestrators that watch agent output — emitting it does not run anything. You MUST then invoke the hook yourself using `{invocation}` (the value on the `EXECUTE_COMMAND_INVOCATION:` line) and wait for its result before proceeding.
 - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
 
 ## Outline
@@ -88,9 +91,12 @@ Check if `.specify/extensions.yml` exists in the project root.
     ## Extension Hooks
 
     **Automatic Hook**: {extension}
-    Executing: `/{command}`
+    Executing: `{invocation}`
     EXECUTE_COMMAND: {command}
+    EXECUTE_COMMAND_INVOCATION: {invocation}
     ```
+  - Here `{invocation}` is the command form for the current environment: usually `/{command}`, but skills-mode sessions render it differently (e.g. `/skill:speckit-*` or `$speckit-*`). Use the same value for both the `Executing:` and `EXECUTE_COMMAND_INVOCATION:` lines.
+  - **Dispatch contract for mandatory hooks**: the `EXECUTE_COMMAND:` line is only a dispatch signal for CLI orchestrators that watch agent output — emitting it does not run anything. You MUST then invoke the hook yourself using `{invocation}` (the value on the `EXECUTE_COMMAND_INVOCATION:` line) and wait for its result before reporting completion.
   - **Optional hook** (`optional: true`):
     ```
     ## Extension Hooks
@@ -167,5 +173,5 @@ Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generate
 ## Done When
 
 - [ ] Plan workflow executed and design artifacts generated
-- [ ] Extension hooks dispatched or skipped according to the rules in Mandatory Post-Execution Hooks above
+- [ ] Extension hooks dispatched or skipped according to the rules in Mandatory Post-Execution Hooks above (mandatory hooks actually invoked and completed — emitting `EXECUTE_COMMAND:` alone does not count as dispatched)
 - [ ] Completion reported to user with branch, plan path, and generated artifacts

templates/commands/specify.md

@@ -45,11 +45,14 @@ You **MUST** consider the user input before proceeding (if not empty).
     ## Extension Hooks
 
     **Automatic Pre-Hook**: {extension}
-    Executing: `/{command}`
+    Executing: `{invocation}`
     EXECUTE_COMMAND: {command}
+    EXECUTE_COMMAND_INVOCATION: {invocation}
 
     Wait for the result of the hook command before proceeding to the Outline.
     ```
+  - Here `{invocation}` is the command form for the current environment: usually `/{command}`, but skills-mode sessions render it differently (e.g. `/skill:speckit-*` or `$speckit-*`). Use the same value for both the `Executing:` and `EXECUTE_COMMAND_INVOCATION:` lines.
+  - **Dispatch contract for mandatory hooks**: the `EXECUTE_COMMAND:` line is only a dispatch signal for CLI orchestrators that watch agent output — emitting it does not run anything. You MUST then invoke the hook yourself using `{invocation}` (the value on the `EXECUTE_COMMAND_INVOCATION:` line) and wait for its result before proceeding.
 - If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently
 
 ## Outline
@@ -249,9 +252,12 @@ Check if `.specify/extensions.yml` exists in the project root.
     ## Extension Hooks
 
     **Automatic Hook**: {extension}
-    Executing: `/{command}`
+    Executing: `{invocation}`
     EXECUTE_COMMAND: {command}
+    EXECUTE_COMMAND_INVOCATION: {invocation}
     ```
+  - Here `{invocation}` is the command form for the current environment: usually `/{command}`, but skills-mode sessions render it differently (e.g. `/skill:speckit-*` or `$speckit-*`). Use the same value for both the `Executing:` and `EXECUTE_COMMAND_INVOCATION:` lines.
+  - **Dispatch contract for mandatory hooks**: the `EXECUTE_COMMAND:` line is only a dispatch signal for CLI orchestrators that watch agent output — emitting it does not run anything. You MUST then invoke the hook yourself using `{invocation}` (the value on the `EXECUTE_COMMAND_INVOCATION:` line) and wait for its result before reporting completion.
   - **Optional hook** (`optional: true`):
     ```
     ## Extension Hooks
@@ -338,5 +344,5 @@ Success criteria must be:
 ## Done When
 
 - [ ] Specification written to `SPEC_FILE` and validated against quality checklist
-- [ ] Extension hooks dispatched or skipped according to the rules in Mandatory Post-Execution Hooks above
+- [ ] Extension hooks dispatched or skipped according to the rules in Mandatory Post-Execution Hooks above (mandatory hooks actually invoked and completed — emitting `EXECUTE_COMMAND:` alone does not count as dispatched)
 - [ ] Completion reported to user with feature directory, spec file path, and checklist results