v0.7.2: extension packaging hygiene + handoff documentation#14
Merged
Conversation
The Quick Start install snippet hardcoded the v0.7.0 release zip URL, so end users following the README after the v0.7.1 release would still install v0.7.0. This is documentation drift introduced by v0.7.1 that we missed during the release ceremony. specify extension add v-model --from <...>/tags/v0.7.0.zip → specify extension add v-model --from <...>/tags/v0.7.1.zip Surfaced while preparing the Epic 3 / dogfood-refresh work on this branch — the README install path is what every end user goes through, so this is a higher-priority fix than the dogfood-state refresh. Going forward, the release ceremony should include "bump the README install URL" alongside the version bumps in pyproject.toml / extension.yml / catalog-entry.json (the MF-8 atomic-release-bump pattern from the master plan).
… surface
When `specify extension add v-model --from <zip-url>` runs on the v0.7.1
release archive, upstream spec-kit-core's `_load_extensionignore` reads
this file and excludes the listed paths from the vendor copy in
`.specify/extensions/v-model/`. Without this file the entire repo zip
gets vendored verbatim (~700 files at v0.7.1, including tests, specs,
the MkDocs site output, recursive .specify/, recursive .github/, etc.),
which makes the dogfood-in-source pattern unworkable: each refresh
produces hundreds of file changes and the recursive vendor compounds.
The exclusions fall into four groups:
- Recursive-vendor hazards: .specify/ and .github/ — this repo
dogfoods the extension on itself, so including these would copy
the extension into itself.
- Development sources: tests/, specs/, docs/, site/, examples/,
media/, presentations/, refactoring_plan/. Not runtime
dependencies of the installed extension.
- Build / tooling / IDE / OS cruft: __pycache__, .pytest_cache,
*.swp, .DS_Store, etc.
- Project-internal files: AGENTS.md, conftest.py, testResults.xml,
requirements-dev.txt — relevant to contributors evolving the
extension, not to end users running it.
What survives: commands/ (the prompts), scripts/ (deterministic
verification logic), templates/ (output templates), commands/overlays/
+ templates/overlays/ (domain overlays), extension.yml,
catalog-entry.json, config-template.yml.example, README, CHANGELOG,
LICENSE, and a few small metadata files. Roughly 165 files instead of
~700.
This file is itself excluded (line at bottom) so it doesn't get
vendored either.
Will take effect once consumers install via a release that contains
this file — v0.7.2 onward. Local installs require `specify-cli`
recent enough to honour the .extensionignore mechanism (upstream
extensions.py line 344 with `ignore=ignore_fn`).
Surfaced during Epic 3 / dogfood-refresh investigation: the install
attempt at v0.7.1 brought in 737 files because no .extensionignore
existed.
…t (Epic 3 Task 7)
`commands/requirements.md` and `commands/acceptance.md` each documented
a §Domain Overlay step instructing the LLM to read a domain-specific
template overlay file:
templates/overlays/{domain}/requirements-template.md
templates/overlays/{domain}/acceptance-plan-template.md
These files were claimed to exist (with conditional "If it exists / If
it does not exist: use base only" handling), but in fact the
`templates/overlays/iso_26262/`, `do_178c/`, and `iec_62304/`
directories have only contained `.gitkeep` placeholders since they
were created in April 2026. No domain template overlay file has ever
existed in any release.
The audit (refactoring_plan/stabilization-audit-roadmap.md Epic 3
Task 7 — "Resolve template overlay mismatch") calls this out and
specifies the DoD: either implement OR remove the instructions.
Implementing would require writing 6 domain-specific template
overlay files (3 domains × 2 commands) — substantial domain-expertise
work that does not fit the "no new functionality" stabilization
scope. So we remove the instructions instead.
The empty `templates/overlays/{domain}/` directories are LEFT IN
PLACE as placeholders signalling future intent. If domain templates
land later, the directory structure is ready; the prompt instructions
can be re-added alongside the actual template files.
The `commands/overlays/{domain}/<command>.md` mechanism is unchanged
— those files are populated and the prompts still load them. Only
the template-overlay step is removed.
- commands/requirements.md: remove step 2, renumber step 3 → 2
- commands/acceptance.md: remove step 2, renumber step 3 → 2
No other commands reference template overlays (verified by grep).
Verification:
pytest tests/evals/ tests/structural/ -m structural → 122 passed
Inventory and document every handoff declared in commands/*.md
frontmatter so contributors can reason about workflow ergonomics
without re-reading 17 frontmatter blocks.
The new §11 satisfies the Epic 3 Task 5 DoD ("Every handoff has one
source, one target, one reason, and allowed re-entry points; circular
handoffs are intentional and documented") by:
- Listing the forward V-Model lifecycle (L1–L4 design→test→trace).
- Listing the cross-cutting/reporting handoffs (hazard-analysis,
impact-analysis, peer-review, test-results, audit-report).
- Listing the bridge-command handoffs (plan→tasks→implement) and
noting the OPTIONAL/CORE classification.
- Enumerating the 9 backward "Back to X" user buttons.
- Documenting the three intentional cycles (peer-review self-loop;
trace↔acceptance gap-fix loop; plan↔tasks↔implement bridge
refinement) with their termination conditions.
- Documenting one historically-removed handoff (plan → implement
direct, removed in v0.7.0 per MF-10) so it doesn't get
re-introduced by accident.
- Stating three invariants the graph enforces: every auto-dispatch
converges on trace; every backward handoff is a user button (never
send: true); every handoff has all four fields.
Renumbering: previous §11/§12/§13 (Cleanup / Common pitfalls / When in
doubt) shift to §12/§13/§14.
Verification:
pytest tests/evals/ tests/structural/ -m structural → 122 passed
Release narrative for v0.7.2: extension packaging hygiene + handoff documentation. Covers the four substantive commits accumulated on chore/v0.7.2-prompt-deduplication since v0.7.1: - README install URL bump (drift from v0.7.0 to v0.7.1) - .extensionignore (eliminates the ~700-file dogfood-refresh hazard) - Template overlay mismatch removed (Epic 3 Task 7) - Handoff graph documented in AGENTS.md §11 (Epic 3 Task 5) Plus the structural-test allow-list update for .extensionignore. Epic 3 Tasks 2, 3, 4 are explicitly deferred — their Definition of Done presupposes tooling (build-time generator or install-time include mechanism) that doesn't fit the v0.7.x stabilization scope. Documented in the "Deferred" section so the deferral is visible. No new commands. No new features. No new functionality.
Part of the v0.7.2 release ceremony — keep the README's Quick Start install snippet pointing at the current release. specify extension add v-model --from <...>/tags/v0.7.1.zip → specify extension add v-model --from <...>/tags/v0.7.2.zip Going forward this bump is part of the standing release ceremony, alongside the atomic version bump in pyproject.toml / extension.yml / catalog-entry.json. (Surfaced as documentation drift during the v0.7.2 preparation; previous v0.7.0 → v0.7.1 drift was caught after the fact.)
… + catalog)
Per master plan MF-8 / Step D.3, version metadata bumped atomically
across all three artefacts that carry it.
- pyproject.toml version = "0.7.1" → "0.7.2"
- extension.yml version: "0.7.1" → "0.7.2"
- catalog-entry.json version "0.7.1" → "0.7.2"
download_url ...v0.7.1.zip → ...v0.7.2.zip
`updated_at` fields stay at 2026-05-17 (both v0.7.1 and v0.7.2 land
on the same calendar day).
The release narrative is in CHANGELOG.md [0.7.2] (commit a58bdae).
Tag `v0.7.2` and the GitHub release will be published after this branch
merges to main.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
v0.7.2 addresses two drift hazards surfaced during the v0.7.1 release and the dogfood-refresh investigation, plus lands two Epic 3 stabilization tasks from the refactoring roadmap. No new commands, no new features, no new functionality — surgical hygiene and documentation.
Full release narrative:
CHANGELOG.md[0.7.2] entry.What's in
v0.7.0.zipafter v0.7.1 shipped; now bumped through tov0.7.2.zip. Future release ceremonies include this bump alongside the three metadata files..extensionignore. Tellsspecify extension addto skip development sources (tests/,specs/,docs/,site/,.specify/,.github/, etc.). Without it, the install vendored ~700 files including the recursive-vendor hazard.specify/extensions/v-model/.specify/.... With it, the install footprint is ~165 files.commands/requirements.mdandcommands/acceptance.mdinstructed the LLM to read domain-specific template overlays (templates/overlays/{domain}/*-template.md) that have never existed. Per the audit's DoD ("either implement OR remove the instructions"), the instructions are removed. The empty domain directories are kept as placeholders for future intent. Thecommands/overlays/{domain}/<command>.mdmechanism (which IS populated) is unchanged.AGENTS.md§11 inventories every handoff declared incommands/*.mdfrontmatter (forward V-Model lifecycle, cross-cutting handoffs, bridge handoffs, backward refinement handoffs), documents the three intentional cycles with their termination conditions, the one historically-removed handoff (plan→implementdirect), and the invariants the graph enforces..extensionignore.What's NOT in
[0.7.2]under "Deferred."Verification
pytest tests/evals/ tests/structural/ -m structural→ 122 passed, 0 failed./tests/bats/lib/bats-core/bin/bats tests/bats/→ 457 passed, 0 failedpytest tests/evals/ -m llm_judge(full pre-tag sweep) → 9 passed / 1 LLM-variance flake; flake passes on targeted re-run → 10/10 effectively passingPost-merge
git tag v0.7.2on the mergedmaingh release create v0.7.2 --notes-file <CHANGELOG [0.7.2] section>github/spec-kit#2613) from v0.7.1 → v0.7.2 (or open a fresh PR if #2613 has already merged).