Skip to content

fix(converge): run the completion hooks before converge reports finished - #5452

Open
shaktimaan00 wants to merge 2 commits into
github:mainfrom
shaktimaan00:feat/5339-hook-feature-dir
Open

shaktimaan00 wants to merge 2 commits into
github:mainfrom
shaktimaan00:feat/5339-hook-feature-dir

Conversation

@shaktimaan00

@shaktimaan00 shaktimaan00 commented Nov 16, 2026 •

Copy link
Copy Markdown

Converge can finish without ever running the hooks registered under hooks.after_converge, so an extension that
wants to mark the feature complete, or update a board, has nothing to listen to — the second half of #5339.

Step 9 now says the hook check must complete before the command reports converge as finished, and says why: those
hooks are the only completion signal converge produces, so a run that ends without them has told nothing downstream
that convergence finished.

Scope

One template, text only: templates/commands/converge.md, +4/-0. No code, no docs, no template tests.

The SPECKIT_FEATURE_DIR half attempted earlier on this branch is dropped. A pre-hook block has no FEATURE_DIR to
fill at the point it runs, the runtime renderer is HookExecutor.format_hook_message and gained nothing, and
check_prerequisites --paths-only already reports the path from SPECIFY_FEATURE_DIRECTORY or
.specify/feature.json. The reasoning is in the thread below.

Gates

The template-reading suites (tests/test_converge_template_scaffold.py, tests/test_command_template_hooks.py,
tests/integrations) give the same counts with and without these four lines, so nothing asserted on the text moved.

Part of #5339

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

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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_DIR to all four hook blocks in nine command templates.
  • Document hook context and the empty before_specify case.
  • 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)

Comment thread templates/commands/constitution.md Resolved
Comment thread templates/commands/plan.md Resolved
Comment thread templates/commands/specify.md Resolved
@mnriem mnriem added the triage-nice-to-have Verdict: evidence-backed fix or greenlit feature — land after review label Nov 16, 2026
@mnriem

mnriem commented Nov 16, 2026

Copy link
Copy Markdown
Collaborator

Could you provide a concrete example showing why the existing SPECIFY_FEATURE_DIRECTORY environment override and feature-directory resolver are insufficient for these hooks? The resolver already uses that override before falling back to .specify/feature.json, so extensions should not need to guess from branch names. This PR adds SPECKIT_FEATURE_DIR as prompt text rather than an environment variable, and it is not yet clear what failure that fixes. There are also unresolved context cases: pre-hooks run before setup obtains FEATURE_DIR, constitution does not establish a feature directory, and specify uses SPECIFY_FEATURE_DIRECTORY rather than FEATURE_DIR. Before adding another context name across the core templates, could you demonstrate a failing hook invocation and show that this change fixes it? The converge completion wording can be assessed separately.

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
Copilot AI adaptive review requested due to automatic review settings November 17, 2026 03:59
@shaktimaan00 shaktimaan00 changed the title feat(hooks): pass SPECKIT_FEATURE_DIR to every extension hook block fix(converge): run the completion hooks before converge reports finished Nov 17, 2026
@shaktimaan00

Copy link
Copy Markdown
Author

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 plan.md the blocks sit under Pre-Execution Checks (line 25) and run before Outline 1. Setup (line 64) resolves FEATURE_DIR, so SPECKIT_FEATURE_DIR: {FEATURE_DIR} would be emitted as literal text. Same for the pre-hooks in tasks, implement, checklist, analyze, clarify and converge.

2. The renderer that formats hook blocks is not the templates. HookExecutor.format_hook_message (src/specify_cli/extensions/__init__.py:6086) is what produces a block for an agent at runtime, and this PR never touched it. A before_plan block from it today:

## Extension Hooks

Hooks available for event 'before_plan':

**Optional Hook**: demo
Command: `/speckit.demo.hook`
Description: demo pre-hook that needs the feature directory

Prompt: Write the plan into the feature directory named here.
To execute: `/speckit.demo.hook`

3. A hook can already get the directory — your point exactly. With .specify/feature.json in the project:

$ python3 .specify/scripts/python/check_prerequisites.py --paths-only
REPO_ROOT: /demo
BRANCH: 003-user-auth
FEATURE_DIR: /demo/specs/003-user-auth

With the override, which wins over feature.json and is not persisted by --paths-only:

$ SPECIFY_FEATURE_DIRECTORY=specs/009-other python3 .specify/scripts/python/check_prerequisites.py --paths-only
FEATURE_DIR: /demo/specs/009-other

And with neither set, the case you flagged for constitution and before_specify, it already fails loudly instead of guessing:

$ python3 .specify/scripts/python/check_prerequisites.py --paths-only
ERROR: Feature directory not found. Set SPECIFY_FEATURE_DIRECTORY or run the specify command to create .specify/feature.json.
ERROR: Failed to resolve feature paths

So the resolver covers it, and an empty SPECKIT_FEATURE_DIR would have been a second way to say "no feature" next to an error the resolver already raises.

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 (tests/test_command_template_hooks.py green; the template/integration selection fails identically against this branch's parent in this container).

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 HookExecutor.format_hook_message using the existing FEATURE_DIR name — say the word and I will follow up with that instead of the nine-template version.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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)

Comment thread templates/commands/converge.md Resolved
@mnriem

mnriem commented Nov 17, 2026

Copy link
Copy Markdown
Collaborator

Please narrow the PR title description to the converge update only

@shaktimaan00

shaktimaan00 commented Nov 17, 2026 •

Copy link
Copy Markdown
Author

Done — both narrowed to the converge update.

  • Title was already converge-only: fix(converge): run the completion hooks before converge reports finished.
  • Body rewritten: it now describes only templates/commands/converge.md (+4/-0, step 9 must run the after_converge hooks before converge reports finished). The SPECKIT_FEATURE_DIR post-mortem, the docs section and the 11 removed template tests are gone from it, and there are no testing claims beyond the template suites giving identical counts with and without the diff.

The reasoning for dropping the first half stays in this thread rather than the description. Net diff is one file, four lines.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

triage-nice-to-have Verdict: evidence-backed fix or greenlit feature — land after review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants