docs: make the catalog refresh a release step, not an afterthought

[mbeacom]

What and why

Cutting spec-kit-v0.1.4 surfaced a gap in the runbook rather than a one-off slip.

docs/RELEASING.md explains how the catalog .zip asset gets packed and what a catalog.community.json entry's download_url points at — and then never says to refresh that entry. Nothing in the pipeline does it: the entry is data in someone else's repository, pinned to a specific release asset.

So it didn't get refreshed. adrkit's community-catalog entry sat at 0.1.2 through both 0.1.3 and 0.1.4, still advertising speckit_version: >=0.13.0,<0.16.0 — a bound that by then refused to install on any current Spec Kit. Anyone discovering adrkit the idiomatic way (specify extension search) got a two-versions-old artifact whose manifest rejected their toolchain, while npm looked perfectly healthy the whole time. The npm publish looked like the whole release and wasn't.

The mechanism is an issue, not a pull request — upstream's publishing guide says so outright ("Do not open a pull request directly to edit extensions/catalog.community.json"), and routes version bumps through the same Extension Submission template as a first listing.

And it always was. adrkit's initial listing (at 0.1.2) went through issue #3942 on 2026-08-03, which a maintainer applied the same day in #3947. That pull request was the maintainer's step, not ours. So there was no process change to miss — the obligation was always "file the issue, every release", and we simply never repeated it after the first one. That is a duller story than "the rules moved", and it is the true one.

Changes

• docs/RELEASING.md — the adapter release section gains the refresh step: file the issue (not a PR), wait for the release asset to actually resolve because maintainers verify the download_url, and compare the proposed entry against extension.yml rather than against the previous entry.
• ADR-0019 action item 5 — was marked [x] and read as a completed one-time task. It's a standing per-release obligation, and reading it as one-time is what cost two releases. Now records that, corrects the listing history and date, and tracks the 0.1.4 submission honestly (see below).
• CHANGELOG — the [spec-kit-0.1.4] heading moves 2026-09-12 → 2026-09-13, the date the tag and release actually landed. The ADR addendum and evidence-index dates are deliberately unchanged: they date the re-verification, which did happen on 2026-09-12.

Catalog status — submitted, not yet refreshed

github/spec-kit#4571 is open. The catalog entry is still 0.1.2, and specify extension search keeps serving it until a maintainer applies the update. Filing is not refreshing, so neither this PR nor ADR-0019 records it as done — the refresh gets recorded when the catalog change actually lands. Upstream's stated review window is 3–7 business days, and the extension-submission label that starts automated validation can only be applied by a maintainer.

Review feedback addressed

All four points from the Copilot review were valid and are fixed in 7cacc69:

Finding	Resolution
The curl example hardcoded spec-kit-v0.1.4	In a step whose whole point is that it recurs, copying it for 0.1.5 would validate the old asset and return 200 — confirming the wrong thing while looking like verification. Now binds tag once and interpolates it.
#3947 listed 0.1.2, not 0.1.0	Verified against the PR diff and body. Corrected — and it turned out to also correct the shape of the story, as above.
"Change only [four fields]" was absolute	Upstream asks for "any other changed fields". A future release altering the description, category, effect, command/hook counts, or requires.tools would have followed that instruction straight into a stale entry the version number doesn't reveal. Reframed as the common case.
ADR-0019 called #4571 a completed refresh	It's an open submission. Recording it as done would have hidden live staleness behind a checked box — the exact failure this PR exists to fix. Now recorded as submitted and open.

Correcting the #3947 reference also exposed a pre-existing error in ADR-0019 action item 5: it said the listing "landed 2026-08-25", but both the issue and the pull request are dated 2026-08-03, corroborated by the catalog entry's own created_at. Corrected, with the prior claim noted rather than silently overwritten.

Release status (for context)

spec-kit-v0.1.4 is published and verified:

Check	Result
Release workflow	success
Tag object	annotated (d3438f77) peeling to c5cae1e on main
npm dist-tags.latest	0.1.4
Published dist.integrity	sha512-xAjP3GQQ… — byte-identical to the pre-merge pack dry run
GitHub release	published, carries adrkit.zip (16,335 bytes)
Asset URL	200, extension.yml at archive root, package.json correctly dropped
End-to-end install of the published asset on Spec Kit 1.0.6	exit 0; 3 commands + 3 skills; after_plan → optional: true; tree has no test/, tsconfig.json, package.json, node_modules/
context.sh (queue + path-scoped) against a real 38-record corpus	exit 0, valid JSON both modes
check.sh with no feature dir	exit 0 with the correct diagnostic, not a failure or a fabricated result

That non---dev install also confirms the .specify-dev/ note from #203: it's absent here, so it really is a dev-install artifact of the loader rather than anything shipped.

Checklist

• Commits are DCO signed off.
• Documentation only — schema, packages/ci, and every shipped artifact untouched.
• ADR-0019 gained no new addendum; an action item was corrected to match what the decision actually requires.
• check:changelog, check:doc-pins, check:deps, and adr lint (37 records, 0 errors) pass.

https://claude.ai/code/session_01UHoVZxZp529qJg1mgwJqxZ

[github-actions]

Decisions governing this change

• 0001 — Record architecture decisions as versioned markdown in git
  • via path: docs/adr/**
• 0031 — Publish a narrow consumer SDK as the contract, and document the CLI JSON as its sibling
  • via path: docs/RELEASING.md
• 0032 — Publish one lockstep OCI image after the coordinated release succeeds
  • via path: docs/RELEASING.md
• 0036 — Expose the governing-decisions Action through one root Marketplace entry point
  • via path: docs/RELEASING.md

[Copilot]

🟡 Changes recommended

Four unresolved documentation corrections remain, including the catalog refresh status.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Updates release documentation to make Spec Kit catalog refreshes a recurring release step and corrects related history.

Changes:

• Adds issue-based catalog refresh guidance to docs/RELEASING.md.
• Records the ongoing obligation in ADR-0019.
• Corrects the spec-kit-0.1.4 changelog date.

File summaries

File	Summary	Review findings
docs/RELEASING.md	Adds catalog refresh instructions and asset verification.	Three nit findings: parameterize the release version, correct the initial listing history, and scope metadata-update guidance.
docs/adr/0019-ship-the-spec-kit-extension-treating-the-spike-no-go-as-a-measurement-artifact.md	Records the recurring catalog obligation.	One nit finding: distinguish the submitted update request from a completed catalog refresh.
CHANGELOG.md	Corrects the 0.1.4 release date.	No findings.

Review details

Suppressed comments (2)

docs/RELEASING.md:221

• The linked upstream submission was for version 0.1.2, not 0.1.0: issue #3942 and PR #3947 both show 0.1.2. Calling it the original 0.1.0 listing misstates the release history; describe it as the initial catalog listing or name 0.1.2.

original 0.1.0 listing did land as a PR, [#3947](https://github.com/github/spec-kit/pull/3947);

docs/RELEASING.md:233

• This absolute instruction conflicts with upstream's update guidance, which says to include any other changed fields when extension metadata changes. Applied to a future release that changes commands, hooks, description, or tools, it would leave the catalog stale. Limit the four-field list to releases like 0.1.4 and say other changed extension metadata should also be submitted, while preserving only the maintainer-managed fields.

Change only `version`, `download_url`, `requires.speckit_version`, and
`updated_at`; `created_at`, `verified`, `downloads`, and `stars` are
maintainer-managed and must be preserved as listed.

• Files reviewed: 3/3 changed files
• Comments generated: 2
• Review effort level: Lite