Spec Kit: from testable intent to traceable acceptance
Spec Kit safety boundaries: inspect hooks, upgrades and the meaning of Converged
Protect project instructions and deployment authority while reviewing the side effects around analysis and append-only convergence.
What you will learn
- A prompt contract is not a filesystem sandbox
- Inspect consequential changes before adopting customization
- Keep acceptance distinct from release authorization
Before you start
- Basic requirements, Git and testing concepts
- Understanding of local development versus application deployment
Trace a small feature from intent to evidence and distinguish workflow contracts from verified behavior.
Key takeaways
- Core prompt constraints do not sandbox surrounding hooks.
- Missing gate evidence should not be mistaken for success.
- Converged is an assessment outcome, not release permission.
A prompt contract is not a filesystem sandbox
The analyze command says to produce a read-only report, and converge restricts its core write to appending a convergence section to tasks.md. Both also describe pre- and post-extension hooks. A hook may invoke additional behavior; the read-only or append-only description is not a technical sandbox around the whole session.
The templates report invalid extension configuration and continue, potentially without checking mandatory hooks. They also leave non-empty hook conditions to the HookExecutor implementation rather than evaluating them in the prompt. Do not interpret “analysis finished” as proof that every organizational gate ran successfully.
Inspect consequential changes before adopting customization
A preset or extension changes instructions or capabilities, and a bundle can install several components. Review the selected source, version and effective commands before use. The README explicitly warns that community contributions are independently maintained. A recognizable project name is not a security review of every component.
Avoid copying --force initialization or a bare self upgrade into a live repository without considering the files and installation they change. Keep credentials and confidential requirements out of a synthetic learning exercise. This article did not modify project principles, install hooks or grant external write access.
Keep acceptance distinct from release authorization
Converge assesses current code rather than Git history and appends traceable work for missing, partial, contradictory or unrequested behavior. It does not repair code, remove unrequested functionality or publish a release itself. A clean result still depends on the quality of the artifacts and the assessment.
Retain independent tests and review before deployment, and verify the deployed revision afterward. If an organizational constraint must be fail-closed, implement and test that enforcement explicitly rather than relying solely on Markdown instructions. No full security audit or adversarial execution test is claimed here.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Inspect enabled hooks and their authority.
- 2
Record unresolved configuration and skipped gates.
- 3
Review initialization and upgrade side effects.
- 4
Require independent acceptance and production verification.
Copy-ready example
{
"proposedReleaseGate": true,
"assessment": "converged",
"mandatoryHookEvidence": null,
"independentTests": null,
"releaseAuthorized": false,
"productionVerified": false
}Frequently asked questions
Can an analysis hook have side effects?
The templates allow hook invocation; inspect the actual hook separately.
Will converge delete unrequested code?
No. Its documented core action is to append a review or remediation task.
Sources
- Spec Kit / templates/commands/analyze.mdSource checked 2026-09-14
- Spec Kit / templates/commands/converge.mdSource checked 2026-09-14
- Spec Kit / README.mdSource checked 2026-09-14
- Spec Kit / scripts/powershell/check-prerequisites.ps1Source checked 2026-09-14