Repository navigation
fix(converge): run the completion hooks before converge reports finished - #5452
shaktimaan00 wants to merge 2 commits into
Conversation
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 github#5339
There was a problem hiding this comment.
🟡 Changes recommended
Hooks reference undefined or unresolved FEATURE_DIR values across multiple workflows, risking missing or stale feature context, while constitution hooks lack defined behavior when no feature exists.
3 open issues
What changed in this PR
This PR addresses #5339 by adding feature-directory context to Spec Kit’s core command hook blocks and making the existing after_converge hook check explicitly mandatory before completion.
Changes:
- Add
SPECKIT_FEATURE_DIRto all four hook blocks in nine command templates. - Document hook context and the empty
before_specifycase. - Add template assertions for context fields, the empty case, and mandatory converge post-hooks.
| File | Description |
|---|---|
tests/test_command_template_hooks.py |
Add assertions for hook context and completion instructions. |
templates/commands/tasks.md |
Add feature context to task hook blocks. |
templates/commands/specify.md |
Add feature context and explain empty pre-hook values. |
templates/commands/plan.md |
Add feature context to planning hook blocks. |
templates/commands/implement.md |
Add feature context to implementation hook blocks. |
templates/commands/converge.md |
Add feature context and mandatory post-hook instructions. |
templates/commands/constitution.md |
Add feature context to constitution hook blocks. |
templates/commands/clarify.md |
Add feature context to clarification hook blocks. |
templates/commands/checklist.md |
Add feature context to checklist hook blocks. |
templates/commands/analyze.md |
Add feature context to analysis hook blocks. |
docs/extensions/api.md |
Document hook context delivery and empty-value semantics. |
Review effort: Balanced (adaptive)
|
Could you provide a concrete example showing why the existing AI disclosure: Prepared for @mnriem using GitHub Copilot (GPT-6.1 Sol), interactively at the user's request; AI inspected the PR and repository and drafted this comment. |
…letion 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 github#5339
|
You're right, and the demonstration settles it against the change rather than for it. I have dropped the feature-dir half, so the net diff on this branch is now the converge completion step only. What I checked, in this branch's container: 1. The pre-hook blocks this added cannot be filled. In 2. The renderer that formats hook blocks is not the templates. 3. A hook can already get the directory — your point exactly. With With the override, which wins over And with neither set, the case you flagged for constitution and So the resolver covers it, and an empty What is left is the part you said could be assessed separately: converge step 9 has to run before the command reports convergence finished, which is the completion signal the other half of #5339 asks for. Text-only, and the template-text tests still pass ( If you would rather have the directory available to a hook without shelling out to a script, the place for it is one call in |
There was a problem hiding this comment.
🟡 Changes recommended
The diff only makes after_converge mandatory, omitting the SPECKIT_FEATURE_DIR propagation, Hook Context documentation, and regression tests claimed by the PR.
1 open issue
3 resolved since last review
Review effort: Balanced (adaptive)
| **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. |

Converge can finish without ever running the hooks registered under
hooks.after_converge, so an extension thatwants to mark the feature complete, or update a board, has nothing to listen to — the second half of #5339.
Step 9 now says it must run before the command reports convergence finished, and says why: those hooks are the only
completion signal converge produces.
The first half,
SPECKIT_FEATURE_DIR, is droppedEarlier commits on this branch put
SPECKIT_FEATURE_DIR: {FEATURE_DIR}in nine templates, in the extensions docs andin a template test. Reviewing that against the code, the value is not needed and, in the pre-hook blocks, cannot even
be filled:
Nothing fills the placeholder in a pre-hook. In
plan.mdthe blocks sit under Pre-Execution Checks (line 25)and run before Outline 1. Setup (line 64) resolves
FEATURE_DIR, so an agent would emit the literal{FEATURE_DIR}. The same holds for the pre-hooks intasks,implement,checklist,analyze,clarifyandconverge.The renderer that formats hook blocks is not the templates.
HookExecutor.format_hook_message(
src/specify_cli/extensions/__init__.py) is what produces a block for an agent at runtime, and it gained nothing.The resolver already answers the question.
check_prerequisites --paths-onlyreportsFEATURE_DIRfromSPECIFY_FEATURE_DIRECTORYwhen set, else from.specify/feature.json, and--paths-onlydoes not persistanything:
So
before_specifyandconstitutionalready get an explicit error rather than a value to guess from, and a thirdname next to
SPECIFY_FEATURE_DIRECTORYandFEATURE_DIRbuys nothing.Gates
Text-only change in one template. The tests that read the templates as text
(
tests/test_command_template_hooks.py,tests/integrations) fail identically on this branch's parent in thecontainer used here — 807 failures on both sides — so nothing regressed; the only difference is the 11
SPECKIT_FEATURE_DIRtemplate tests this PR added and I have removed.Part of #5339