From 136886356d021799949870daa13c5e295e7a25af Mon Sep 17 00:00:00 2001 From: shaktimaan00 <97835032+shaktimaan00@users.noreply.github.com> Date: Mon, 16 Nov 2026 18:37:27 +0000 Subject: [PATCH 1/2] feat(hooks): pass SPECKIT_FEATURE_DIR to every extension hook block A hook that needs the feature it belongs to has to derive it from the branch name or .specify/feature.json. Every rendered hook block now carries SPECKIT_FEATURE_DIR: the FEATURE_DIR the command's setup script resolves before the hooks run. It resolves to nothing for before_specify, where the directory does not exist yet. after_converge already existed, but converge's step 9 reads as optional next to the "Mandatory Post-Execution Hooks" sections the other commands carry, so an agent can report the handoff and never run it. It is now framed as mandatory, without reordering, so the event still fires when converge finishes. Refs #5339 --- docs/extensions/api.md | 24 ++++++++++++ templates/commands/analyze.md | 4 ++ templates/commands/checklist.md | 4 ++ templates/commands/clarify.md | 4 ++ templates/commands/constitution.md | 4 ++ templates/commands/converge.md | 8 ++++ templates/commands/implement.md | 4 ++ templates/commands/plan.md | 4 ++ templates/commands/specify.md | 7 ++++ templates/commands/tasks.md | 4 ++ tests/test_command_template_hooks.py | 56 ++++++++++++++++++++++++++++ 11 files changed, 123 insertions(+) diff --git a/docs/extensions/api.md b/docs/extensions/api.md index 2bc3b5256f..9c06ff371e 100644 --- a/docs/extensions/api.md +++ b/docs/extensions/api.md @@ -788,6 +788,30 @@ Executing: `/{command}` EXECUTE_COMMAND: {command} ``` +### Hook Context + +Every rendered hook block carries the feature directory its command is running for, so a hook does +not have to derive it from the branch name or `.specify/feature.json`: + +```markdown +## Extension Hooks + +**Optional Hook**: {extension} +SPECKIT_FEATURE_DIR: /repo/specs/003-user-auth +Command: `/{command}` +Description: {description} + +Prompt: {prompt} +To execute: `/{command}` +``` + +- `SPECKIT_FEATURE_DIR` is the absolute path of the current feature directory, the `FEATURE_DIR` + the command's setup script resolves before the hooks run. +- It resolves to nothing for `before_specify`, because the feature directory does not exist yet at + that point. A hook must treat the empty value as "no feature yet" rather than guessing one. +- Hooks are prompts run in the same session, so the value reaches the hook through the block, not + through an environment variable. + --- ## Extension Runtime Events diff --git a/templates/commands/analyze.md b/templates/commands/analyze.md index 7de2d28f0d..fe554b737a 100644 --- a/templates/commands/analyze.md +++ b/templates/commands/analyze.md @@ -30,6 +30,7 @@ You **MUST** consider the user input before proceeding (if not empty). ## Extension Hooks **Optional Pre-Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} @@ -41,6 +42,7 @@ You **MUST** consider the user input before proceeding (if not empty). ## Extension Hooks **Automatic Pre-Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} @@ -216,6 +218,7 @@ After reporting, check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Optional Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} @@ -227,6 +230,7 @@ After reporting, check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Automatic Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} ``` diff --git a/templates/commands/checklist.md b/templates/commands/checklist.md index 6e33f5d422..42b4685de1 100644 --- a/templates/commands/checklist.md +++ b/templates/commands/checklist.md @@ -60,6 +60,7 @@ You **MUST** consider the user input before proceeding (if not empty). ## Extension Hooks **Optional Pre-Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} @@ -71,6 +72,7 @@ You **MUST** consider the user input before proceeding (if not empty). ## Extension Hooks **Automatic Pre-Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} @@ -361,6 +363,7 @@ Check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Optional Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} @@ -372,6 +375,7 @@ Check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Automatic Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} ``` diff --git a/templates/commands/clarify.md b/templates/commands/clarify.md index f48d8bd703..6e85b0375d 100644 --- a/templates/commands/clarify.md +++ b/templates/commands/clarify.md @@ -34,6 +34,7 @@ You **MUST** consider the user input before proceeding (if not empty). ## Extension Hooks **Optional Pre-Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} @@ -45,6 +46,7 @@ You **MUST** consider the user input before proceeding (if not empty). ## Extension Hooks **Automatic Pre-Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} @@ -256,6 +258,7 @@ Check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Automatic Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} ``` @@ -265,6 +268,7 @@ Check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Optional Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} diff --git a/templates/commands/constitution.md b/templates/commands/constitution.md index f2c107a158..9d5da7404e 100644 --- a/templates/commands/constitution.md +++ b/templates/commands/constitution.md @@ -53,6 +53,7 @@ and commands read the constitution at runtime and are not modified here. ## Extension Hooks **Optional Pre-Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} @@ -64,6 +65,7 @@ and commands read the constitution at runtime and are not modified here. ## Extension Hooks **Automatic Pre-Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} @@ -161,6 +163,7 @@ Check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Optional Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} @@ -172,6 +175,7 @@ Check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Automatic Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} ``` diff --git a/templates/commands/converge.md b/templates/commands/converge.md index f6a44c3e91..e6161170e2 100644 --- a/templates/commands/converge.md +++ b/templates/commands/converge.md @@ -32,6 +32,7 @@ You **MUST** consider the user input before proceeding (if not empty). ## Extension Hooks **Optional Pre-Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} @@ -45,6 +46,7 @@ You **MUST** consider the user input before proceeding (if not empty). ## Extension Hooks **Automatic Pre-Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} @@ -241,6 +243,10 @@ Append to the **end** of `tasks.md`, per the append contract: ### 9. Check for extension hooks +**You MUST complete this section before reporting converge as finished.** These hooks are the +only completion signal this command produces, so a run that ends without them has not told +anything downstream that convergence finished. + After producing the result, check if `.specify/extensions.yml` exists in the project root. - If it exists, read it and look for entries under the `hooks.after_converge` key @@ -258,6 +264,7 @@ After producing the result, check if `.specify/extensions.yml` exists in the pro ## Extension Hooks **Optional Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} @@ -271,6 +278,7 @@ After producing the result, check if `.specify/extensions.yml` exists in the pro ## Extension Hooks **Automatic Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} ``` diff --git a/templates/commands/implement.md b/templates/commands/implement.md index f98ba525de..41bdeef212 100644 --- a/templates/commands/implement.md +++ b/templates/commands/implement.md @@ -30,6 +30,7 @@ You **MUST** consider the user input before proceeding (if not empty). ## Extension Hooks **Optional Pre-Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} @@ -41,6 +42,7 @@ You **MUST** consider the user input before proceeding (if not empty). ## Extension Hooks **Automatic Pre-Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} @@ -194,6 +196,7 @@ Check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Automatic Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} ``` @@ -203,6 +206,7 @@ Check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Optional Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} diff --git a/templates/commands/plan.md b/templates/commands/plan.md index d559e517ae..bbd249ffa8 100644 --- a/templates/commands/plan.md +++ b/templates/commands/plan.md @@ -38,6 +38,7 @@ You **MUST** consider the user input before proceeding (if not empty). ## Extension Hooks **Optional Pre-Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} @@ -49,6 +50,7 @@ You **MUST** consider the user input before proceeding (if not empty). ## Extension Hooks **Automatic Pre-Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} @@ -89,6 +91,7 @@ Check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Automatic Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} ``` @@ -98,6 +101,7 @@ Check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Optional Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} diff --git a/templates/commands/specify.md b/templates/commands/specify.md index 2dbad6d63d..583f170209 100644 --- a/templates/commands/specify.md +++ b/templates/commands/specify.md @@ -32,12 +32,16 @@ You **MUST** consider the user input before proceeding (if not empty). - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: - If the hook has no `condition` field, or it is null/empty, treat the hook as executable - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation +- For this event `SPECKIT_FEATURE_DIR` resolves to nothing: the feature directory does not exist + yet when the pre-hooks run, so leave the value empty rather than deriving one from the branch + or `.specify/feature.json` - For each executable hook, output the following based on its `optional` flag: - **Optional hook** (`optional: true`): ``` ## Extension Hooks **Optional Pre-Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} @@ -49,6 +53,7 @@ You **MUST** consider the user input before proceeding (if not empty). ## Extension Hooks **Automatic Pre-Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} @@ -255,6 +260,7 @@ Check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Automatic Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} ``` @@ -264,6 +270,7 @@ Check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Optional Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} diff --git a/templates/commands/tasks.md b/templates/commands/tasks.md index 1b9c4255fe..a13557beba 100644 --- a/templates/commands/tasks.md +++ b/templates/commands/tasks.md @@ -39,6 +39,7 @@ You **MUST** consider the user input before proceeding (if not empty). ## Extension Hooks **Optional Pre-Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} @@ -50,6 +51,7 @@ You **MUST** consider the user input before proceeding (if not empty). ## Extension Hooks **Automatic Pre-Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} @@ -110,6 +112,7 @@ Check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Automatic Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} ``` @@ -119,6 +122,7 @@ Check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Optional Hook**: {extension} + SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} diff --git a/tests/test_command_template_hooks.py b/tests/test_command_template_hooks.py index d1c7677bae..2567b7d27f 100644 --- a/tests/test_command_template_hooks.py +++ b/tests/test_command_template_hooks.py @@ -63,6 +63,62 @@ def test_unreadable_manifest_is_never_skipped_silently(name: str): ) +_HOOK_BLOCK_HEADER = re.compile( + r"^\s+\*\*(?:Optional|Automatic)(?: Pre-Hook| Hook)\*\*: \{extension\}$" +) +_FEATURE_DIR_LINE = "SPECKIT_FEATURE_DIR: {FEATURE_DIR}" +# The one hook event that runs before the feature directory exists. +_EMPTY_FEATURE_DIR_NOTE = "`SPECKIT_FEATURE_DIR` resolves to nothing" + + +@pytest.mark.parametrize("name", HOOK_TEMPLATES) +def test_every_hook_block_carries_the_feature_directory(name: str): + """A hook block without SPECKIT_FEATURE_DIR leaves its consumer guessing. + + The block is the only surface a hook sees, so the value has to be in it, + directly under the hook header and inside the same fence. + """ + lines = (TEMPLATES_DIR / name).read_text(encoding="utf-8").splitlines() + headers = [i for i, line in enumerate(lines) if _HOOK_BLOCK_HEADER.match(line)] + # Guard: the before/after sites each render an optional and a mandatory block. + assert len(headers) >= 4, f"{name}: found only {len(headers)} hook blocks" + for index in headers: + following = lines[index + 1].strip() if index + 1 < len(lines) else "" + assert following == _FEATURE_DIR_LINE, ( + f"{name}: hook block at line {index + 1} does not carry " + f"{_FEATURE_DIR_LINE!r} as its second line, found {following!r}" + ) + + +def test_specify_says_the_feature_directory_is_empty_before_it_exists(): + """before_specify runs before the directory exists, so the value is empty. + + The note has to sit in the pre-hook section, ahead of the first hook block, + or an agent reads it as applying to the post-hook blocks that do carry a + real path. + """ + lines = (TEMPLATES_DIR / "specify.md").read_text(encoding="utf-8").splitlines() + notes = [i for i, line in enumerate(lines) if _EMPTY_FEATURE_DIR_NOTE in line] + headers = [i for i, line in enumerate(lines) if _HOOK_BLOCK_HEADER.match(line)] + assert notes, "specify.md does not say SPECKIT_FEATURE_DIR is empty before the folder exists" + assert notes[0] < headers[0], ( + "specify.md states the empty case after the first hook block, where it " + "reads as an exception to the blocks that carry a real path" + ) + + +def test_converge_post_hooks_are_mandatory(): + """after_converge is the only completion signal converge produces. + + Without the mandatory framing the other commands carry, an agent may report + the handoff and end the command before the hooks run. + """ + text = (TEMPLATES_DIR / "converge.md").read_text(encoding="utf-8") + assert "MUST complete this section before reporting converge as finished" in text, ( + "converge.md does not make the after_converge hooks mandatory" + ) + + @pytest.mark.parametrize("name", HOOK_TEMPLATES) def test_every_parse_failure_line_reports_before_continuing(name: str): text = (TEMPLATES_DIR / name).read_text(encoding="utf-8") From 944b640524c07a32d109a1ecb3ee92b2fe92fb5d Mon Sep 17 00:00:00 2001 From: shaktimaan00 <97835032+shaktimaan00@users.noreply.github.com> Date: Tue, 17 Nov 2026 03:59:45 +0000 Subject: [PATCH 2/2] refactor: drop the hook feature-dir injection, keep the converge completion step The pre-hook blocks this added sit under "Pre-Execution Checks", which run before Outline step 1 resolves FEATURE_DIR, so `SPECKIT_FEATURE_DIR: {FEATURE_DIR}` in plan, tasks, implement, checklist, analyze, clarify and converge was a placeholder nothing fills. The renderer that actually formats hook blocks for an agent is HookExecutor.format_hook_message, where this change added nothing. A hook can already resolve its feature directory: check_prerequisites --paths-only reports FEATURE_DIR from .specify/feature.json, or from SPECIFY_FEATURE_DIRECTORY when that is set, and fails with a clear error when neither exists. The resolver covers the case, so a second name next to SPECIFY_FEATURE_DIRECTORY and FEATURE_DIR is not needed. Keep the converge change: step 9 now has to run before the command reports convergence finished, which is the completion signal the issue asked for. Refs #5339 --- docs/extensions/api.md | 24 ------------ templates/commands/analyze.md | 4 -- templates/commands/checklist.md | 4 -- templates/commands/clarify.md | 4 -- templates/commands/constitution.md | 4 -- templates/commands/converge.md | 4 -- templates/commands/implement.md | 4 -- templates/commands/plan.md | 4 -- templates/commands/specify.md | 7 ---- templates/commands/tasks.md | 4 -- tests/test_command_template_hooks.py | 56 ---------------------------- 11 files changed, 119 deletions(-) diff --git a/docs/extensions/api.md b/docs/extensions/api.md index 9c06ff371e..2bc3b5256f 100644 --- a/docs/extensions/api.md +++ b/docs/extensions/api.md @@ -788,30 +788,6 @@ Executing: `/{command}` EXECUTE_COMMAND: {command} ``` -### Hook Context - -Every rendered hook block carries the feature directory its command is running for, so a hook does -not have to derive it from the branch name or `.specify/feature.json`: - -```markdown -## Extension Hooks - -**Optional Hook**: {extension} -SPECKIT_FEATURE_DIR: /repo/specs/003-user-auth -Command: `/{command}` -Description: {description} - -Prompt: {prompt} -To execute: `/{command}` -``` - -- `SPECKIT_FEATURE_DIR` is the absolute path of the current feature directory, the `FEATURE_DIR` - the command's setup script resolves before the hooks run. -- It resolves to nothing for `before_specify`, because the feature directory does not exist yet at - that point. A hook must treat the empty value as "no feature yet" rather than guessing one. -- Hooks are prompts run in the same session, so the value reaches the hook through the block, not - through an environment variable. - --- ## Extension Runtime Events diff --git a/templates/commands/analyze.md b/templates/commands/analyze.md index fe554b737a..7de2d28f0d 100644 --- a/templates/commands/analyze.md +++ b/templates/commands/analyze.md @@ -30,7 +30,6 @@ You **MUST** consider the user input before proceeding (if not empty). ## Extension Hooks **Optional Pre-Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} @@ -42,7 +41,6 @@ You **MUST** consider the user input before proceeding (if not empty). ## Extension Hooks **Automatic Pre-Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} @@ -218,7 +216,6 @@ After reporting, check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Optional Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} @@ -230,7 +227,6 @@ After reporting, check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Automatic Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} ``` diff --git a/templates/commands/checklist.md b/templates/commands/checklist.md index 42b4685de1..6e33f5d422 100644 --- a/templates/commands/checklist.md +++ b/templates/commands/checklist.md @@ -60,7 +60,6 @@ You **MUST** consider the user input before proceeding (if not empty). ## Extension Hooks **Optional Pre-Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} @@ -72,7 +71,6 @@ You **MUST** consider the user input before proceeding (if not empty). ## Extension Hooks **Automatic Pre-Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} @@ -363,7 +361,6 @@ Check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Optional Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} @@ -375,7 +372,6 @@ Check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Automatic Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} ``` diff --git a/templates/commands/clarify.md b/templates/commands/clarify.md index 6e85b0375d..f48d8bd703 100644 --- a/templates/commands/clarify.md +++ b/templates/commands/clarify.md @@ -34,7 +34,6 @@ You **MUST** consider the user input before proceeding (if not empty). ## Extension Hooks **Optional Pre-Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} @@ -46,7 +45,6 @@ You **MUST** consider the user input before proceeding (if not empty). ## Extension Hooks **Automatic Pre-Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} @@ -258,7 +256,6 @@ Check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Automatic Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} ``` @@ -268,7 +265,6 @@ Check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Optional Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} diff --git a/templates/commands/constitution.md b/templates/commands/constitution.md index 9d5da7404e..f2c107a158 100644 --- a/templates/commands/constitution.md +++ b/templates/commands/constitution.md @@ -53,7 +53,6 @@ and commands read the constitution at runtime and are not modified here. ## Extension Hooks **Optional Pre-Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} @@ -65,7 +64,6 @@ and commands read the constitution at runtime and are not modified here. ## Extension Hooks **Automatic Pre-Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} @@ -163,7 +161,6 @@ Check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Optional Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} @@ -175,7 +172,6 @@ Check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Automatic Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} ``` diff --git a/templates/commands/converge.md b/templates/commands/converge.md index e6161170e2..2c23a9b844 100644 --- a/templates/commands/converge.md +++ b/templates/commands/converge.md @@ -32,7 +32,6 @@ You **MUST** consider the user input before proceeding (if not empty). ## Extension Hooks **Optional Pre-Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} @@ -46,7 +45,6 @@ You **MUST** consider the user input before proceeding (if not empty). ## Extension Hooks **Automatic Pre-Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} @@ -264,7 +262,6 @@ After producing the result, check if `.specify/extensions.yml` exists in the pro ## Extension Hooks **Optional Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} @@ -278,7 +275,6 @@ After producing the result, check if `.specify/extensions.yml` exists in the pro ## Extension Hooks **Automatic Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} ``` diff --git a/templates/commands/implement.md b/templates/commands/implement.md index 41bdeef212..f98ba525de 100644 --- a/templates/commands/implement.md +++ b/templates/commands/implement.md @@ -30,7 +30,6 @@ You **MUST** consider the user input before proceeding (if not empty). ## Extension Hooks **Optional Pre-Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} @@ -42,7 +41,6 @@ You **MUST** consider the user input before proceeding (if not empty). ## Extension Hooks **Automatic Pre-Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} @@ -196,7 +194,6 @@ Check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Automatic Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} ``` @@ -206,7 +203,6 @@ Check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Optional Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} diff --git a/templates/commands/plan.md b/templates/commands/plan.md index bbd249ffa8..d559e517ae 100644 --- a/templates/commands/plan.md +++ b/templates/commands/plan.md @@ -38,7 +38,6 @@ You **MUST** consider the user input before proceeding (if not empty). ## Extension Hooks **Optional Pre-Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} @@ -50,7 +49,6 @@ You **MUST** consider the user input before proceeding (if not empty). ## Extension Hooks **Automatic Pre-Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} @@ -91,7 +89,6 @@ Check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Automatic Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} ``` @@ -101,7 +98,6 @@ Check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Optional Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} diff --git a/templates/commands/specify.md b/templates/commands/specify.md index 583f170209..2dbad6d63d 100644 --- a/templates/commands/specify.md +++ b/templates/commands/specify.md @@ -32,16 +32,12 @@ You **MUST** consider the user input before proceeding (if not empty). - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: - If the hook has no `condition` field, or it is null/empty, treat the hook as executable - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation -- For this event `SPECKIT_FEATURE_DIR` resolves to nothing: the feature directory does not exist - yet when the pre-hooks run, so leave the value empty rather than deriving one from the branch - or `.specify/feature.json` - For each executable hook, output the following based on its `optional` flag: - **Optional hook** (`optional: true`): ``` ## Extension Hooks **Optional Pre-Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} @@ -53,7 +49,6 @@ You **MUST** consider the user input before proceeding (if not empty). ## Extension Hooks **Automatic Pre-Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} @@ -260,7 +255,6 @@ Check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Automatic Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} ``` @@ -270,7 +264,6 @@ Check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Optional Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} diff --git a/templates/commands/tasks.md b/templates/commands/tasks.md index a13557beba..1b9c4255fe 100644 --- a/templates/commands/tasks.md +++ b/templates/commands/tasks.md @@ -39,7 +39,6 @@ You **MUST** consider the user input before proceeding (if not empty). ## Extension Hooks **Optional Pre-Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} @@ -51,7 +50,6 @@ You **MUST** consider the user input before proceeding (if not empty). ## Extension Hooks **Automatic Pre-Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} @@ -112,7 +110,6 @@ Check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Automatic Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Executing: `/{command}` EXECUTE_COMMAND: {command} ``` @@ -122,7 +119,6 @@ Check if `.specify/extensions.yml` exists in the project root. ## Extension Hooks **Optional Hook**: {extension} - SPECKIT_FEATURE_DIR: {FEATURE_DIR} Command: `/{command}` Description: {description} diff --git a/tests/test_command_template_hooks.py b/tests/test_command_template_hooks.py index 2567b7d27f..d1c7677bae 100644 --- a/tests/test_command_template_hooks.py +++ b/tests/test_command_template_hooks.py @@ -63,62 +63,6 @@ def test_unreadable_manifest_is_never_skipped_silently(name: str): ) -_HOOK_BLOCK_HEADER = re.compile( - r"^\s+\*\*(?:Optional|Automatic)(?: Pre-Hook| Hook)\*\*: \{extension\}$" -) -_FEATURE_DIR_LINE = "SPECKIT_FEATURE_DIR: {FEATURE_DIR}" -# The one hook event that runs before the feature directory exists. -_EMPTY_FEATURE_DIR_NOTE = "`SPECKIT_FEATURE_DIR` resolves to nothing" - - -@pytest.mark.parametrize("name", HOOK_TEMPLATES) -def test_every_hook_block_carries_the_feature_directory(name: str): - """A hook block without SPECKIT_FEATURE_DIR leaves its consumer guessing. - - The block is the only surface a hook sees, so the value has to be in it, - directly under the hook header and inside the same fence. - """ - lines = (TEMPLATES_DIR / name).read_text(encoding="utf-8").splitlines() - headers = [i for i, line in enumerate(lines) if _HOOK_BLOCK_HEADER.match(line)] - # Guard: the before/after sites each render an optional and a mandatory block. - assert len(headers) >= 4, f"{name}: found only {len(headers)} hook blocks" - for index in headers: - following = lines[index + 1].strip() if index + 1 < len(lines) else "" - assert following == _FEATURE_DIR_LINE, ( - f"{name}: hook block at line {index + 1} does not carry " - f"{_FEATURE_DIR_LINE!r} as its second line, found {following!r}" - ) - - -def test_specify_says_the_feature_directory_is_empty_before_it_exists(): - """before_specify runs before the directory exists, so the value is empty. - - The note has to sit in the pre-hook section, ahead of the first hook block, - or an agent reads it as applying to the post-hook blocks that do carry a - real path. - """ - lines = (TEMPLATES_DIR / "specify.md").read_text(encoding="utf-8").splitlines() - notes = [i for i, line in enumerate(lines) if _EMPTY_FEATURE_DIR_NOTE in line] - headers = [i for i, line in enumerate(lines) if _HOOK_BLOCK_HEADER.match(line)] - assert notes, "specify.md does not say SPECKIT_FEATURE_DIR is empty before the folder exists" - assert notes[0] < headers[0], ( - "specify.md states the empty case after the first hook block, where it " - "reads as an exception to the blocks that carry a real path" - ) - - -def test_converge_post_hooks_are_mandatory(): - """after_converge is the only completion signal converge produces. - - Without the mandatory framing the other commands carry, an agent may report - the handoff and end the command before the hooks run. - """ - text = (TEMPLATES_DIR / "converge.md").read_text(encoding="utf-8") - assert "MUST complete this section before reporting converge as finished" in text, ( - "converge.md does not make the after_converge hooks mandatory" - ) - - @pytest.mark.parametrize("name", HOOK_TEMPLATES) def test_every_parse_failure_line_reports_before_continuing(name: str): text = (TEMPLATES_DIR / name).read_text(encoding="utf-8")