docs(spec-kit): verify 1.0.5/1.0.6 and close PR #198's open review notes

[mbeacom]

What and why

#198 widened the Spec Kit pin to >=0.13.0,<1.1.0 and moved @adrkit/spec-kit to 0.1.4, but merged with Copilot's final review (🔵 Needs a closer look, submitted five minutes before the merge) still open on three points. Two were documentation sweeps that had already been fixed in the branch before merging. The third was substantive.

The substantive one. That pin's entire justification is that its upper bound is a verification boundary, not a guess. <1.1.0 admitted 1.0.5 — already released when #198 merged — while the evidence reached only 1.0.4. 1.0.6 shipped after. So the manifest was advertising support for upstream releases nobody had run it against, which is the one thing that bound is not allowed to do. Narrowing the bound instead would have rejected current upstream and undone #198's purpose, so this re-verifies and keeps the range.

Re-verification evidence (same maintainer-session terms as the 2026-09-09 addendum)

Check	Result
extensions/EXTENSION-API-REFERENCE.md at v1.0.4 vs v1.0.5 vs v1.0.6	byte-identical at all three — 896 lines, SHA-256 cb037d69fe62c7d8…. The extension-facing contract does not move inside the 1.0 line.
Loader v1.0.4 → v1.0.5	one hunk: __SPECKIT_COMMAND_([A-Z][A-Z0-9_]*)__ → ([A-Z][A-Z0-9_-]*). Strictly more permissive; nothing that matched stops matching.
Loader v1.0.5 → v1.0.6	three call sites pass author=manifest.data["extension"].get("author") into skill generation. .get(), so an author-less manifest is unaffected.
.extensionignore handling, SpecifierSet parsing, v1.0.4 → v1.0.6	unchanged — neither diff touches either path.
specify extension add --dev on 1.0.5 and 1.0.6 (PyPI), Python 3.12, --integration copilot	exit 0 on both; 3 commands + 3 agent skills registered; extension list / extension info exit 0 reporting v0.1.4
after_plan on both	.specify/extensions.yml records optional: true with enabled: true — the consent-preserving rendering
Installed tree on both	LICENSE, NOTICE, README.md, commands/, extension.yml, scripts/, plus the loader's .specify-dev/extension-skills/. No test/, tsconfig.json, package.json, node_modules/

The rule that stops this recurring

The hole existed because the granularity of the boundary was never written down. It is now explicit in the manifest header, ADR-0019, and the evidence index: the bound is declared and verified at minor granularity — endpoints and samples of each admitted line, not every patch. <1.1.0 asserts "verified through the 1.0 line"; a later 1.0.x patch does not reopen this, and 1.1.0 is where the gate fires and re-verification is owed. Chasing patches would mean a bound that moves on releases adrkit has no say over.

Recorded, not repaired

• .specify-dev/ is neither new nor a leak. A --dev install has generated it since at least 1.0.4 — it is the loader's own staging directory for the skills it registers. The 2026-09-09 "installed tree carries only …" row simply omitted it; .extensionignore is doing its job.
• 1.0.6 changes generated skill attribution. metadata.author is now Mark Beacom (@mbeacom) from extension.author, where 1.0.4 emitted github-spec-kit. Upstream improvement, no adrkit change needed — noted so a future reader does not read it as drift.

The other two review points

• bun.lock workspace version, and AGENTS.md:8 / plan.md:60 / site/…/spec-kit.mdx were all fixed in feat(spec-kit): verify and widen upstream pin to >=0.13.0,<1.1.0 #198 before it merged; the two threads were simply never resolved. Verified against main at b5385c4 — bun.lock:32 reads 0.1.4 and both of those docs already read >=0.13.0,<1.1.0. Resolving those threads with a pointer to this PR.
• AGENTS.md:8 claiming 0.1.4 is published was accurate about intent and premature about fact — npm's latest is still 0.1.3. That is resolved by cutting the release, which is the next step after this merges, not by walking the claim back.

Stale "current" text in ADR-0019

• The Trade-offs paragraph still described "the pin to a single upstream minor … breaks on the next Spec Kit minor". The range now spans 0.13 through the 1.0 line. Rewritten so the mechanism (fails loud on the first unverified minor) is what the paragraph asserts, with the as-accepted bound marked historical.
• Action item 3 still recorded <0.16.0 as the widened bound. It now notes both later re-verifications and points at the addenda rather than contradicting them.

One unrelated correction

docs/RELEASING.md's adapter recipe showed a lightweight git tag spec-kit-v0.1.0, while the lockstep recipes use -a and every spec-kit-v* tag ever pushed is annotated. release.yml's annotated-tag assertion is inside the lockstep == true branch, so a lightweight adapter tag would publish and then read as a permanent anomaly in git cat-file -t. Recipe corrected.

Checklist

• Commits are DCO signed off (check:dco: 1 signed, 0 unsigned).
• ADR-0019 gained a dated addendum (2026-09-12) rather than a superseding record — the change follows the path ADR-0019 itself specifies, and the pin's text is unchanged.
• Schema unchanged — no Zod source or generated JSON touched.
• packages/ci untouched. (Note: local Bun 1.4.0 vs the repo's pinned bun@1.3.14 makes bun run build rewrite the committed packages/ci/dist/* bundles with equivalent-but-different output. Reverted, not committed.)
• bun run typecheck && bun run build && bun test && bun run lint pass: 2812 pass, 0 fail, 1 skip.
• check:changelog (now 5 adapter releases), check:doc-pins, check:site-grammar, check:deps, check:freeze-hashes, and adr lint (37 records, 0 errors) all pass.
• bun run release:pack -- --only @adrkit/spec-kit --tag spec-kit-v0.1.4 packs 12 files with extension.yml at 0.1.4 / >=0.13.0,<1.1.0 and no development files.

Notes for reviewers

• No manifest change. The pin already read >=0.13.0,<1.1.0; only its evidence moved. @adrkit/spec-kit stays at 0.1.4 — this is the evidence the 0.1.4 release ships with, not a new version.
• CHANGELOG: the [Unreleased] entry becomes [spec-kit-0.1.4] - 2026-09-12 with its compare link, so the release can be cut immediately on merge.
• Still open, unchanged: the dogfood matrix (mbeacom/adrkit-t018-dogfood) exercises only 0.13.0/0.14.4/0.15.1. Bringing 0.16.5, 1.0.0, and 1.0.4–1.0.6 under that weekly gate remains the recorded follow-up. These are maintainer-session installs, deliberately not claimed as a rung-2 matrix extension.
• Separately, and not fixable here: the upstream community catalog entry is stale at 0.1.2 — it has a version-pinned download_url (spec-kit-v0.1.2/adrkit.zip) and still advertises speckit_version: >=0.13.0,<0.16.0. It missed the 0.1.3 release too. Completing this release properly needs a follow-up PR to github/spec-kit updating that entry to 0.1.4 and the widened pin.

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/**
• 0003 — Ship as a Spec Kit extension plus a standalone CLI, not a competing harness
  • via path: packages/adapters/spec-kit/**
• 0007 — Isolate integrations as optional adapters and build only against public surfaces
  • via path: packages/adapters/**
• 0011 — Host the canonical JSON Schema at its $id on adrkit.dev
  • via path: site/**
• 0014 — Stage phase-landing evidence across a three-rung validation ladder
  • via path: plan.md
• 0016 — Require every check to be observed failing before it counts as coverage
  • via path: packages/adapters/*/test/**
• 0019 — Ship the Spec Kit extension, treating the spike's no-go as a measurement artifact
  • via path: packages/adapters/spec-kit/**
• 0030 — Keep extension surfaces that carry a dependency tree outside this repository
  • via path: packages/adapters/**
• 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: README.md
  • via path: docs/RELEASING.md
• 0033 — Select interactive graph presentation at the CLI boundary while preserving piped DOT
  • via path: site/src/content/docs/**
• 0036 — Expose the governing-decisions Action through one root Marketplace entry point
  • via path: docs/RELEASING.md

Active proposals touching this change

These are not yet ratified and do not bind this change:

• 0037 — Treat generated knowledge systems as downstream read models, not decision authorities (proposed)
  • via path: README.md
  • via path: site/src/content/docs/**

[Copilot]

🔵 Needs a closer look

Three documented nit-level issues remain regarding the abbreviated digest and the 1.0.6 attribution summary.

Pull request overview

Documents Spec Kit 1.0.5/1.0.6 verification and synchronizes compatibility evidence, ADR guidance, release instructions, and the 0.1.4 changelog without changing the manifest pin.

Changes:

• Records minor-granularity verification through Spec Kit 1.0.6.
• Updates documentation, tests, ADR evidence, and compatibility references.
• Corrects annotated-tag release guidance.

File summaries

File	Summary
site/src/content/docs/spec-kit.mdx	Updates supported versions.
README.md	Updates compatibility claims.
plan.md	Updates verification status.
packages/adapters/spec-kit/test/packaging.test.ts	Refreshes packaging evidence.
packages/adapters/spec-kit/test/manifest.test.ts	Refreshes pin rationale.
packages/adapters/spec-kit/README.md	Updates support documentation.
packages/adapters/spec-kit/extension.yml	Documents the verification boundary.
docs/RELEASING.md	Corrects adapter tag guidance.
docs/reference-verification-spec-kit-extension.md	Adds 1.0.5/1.0.6 evidence.
docs/adr/0019-ship-the-spec-kit-extension-treating-the-spike-no-go-as-a-measurement-artifact.md	Adds verification addendum and sampling guidance.
CHANGELOG.md	Adds the 0.1.4 release entry.
AGENTS.md	Updates compatibility references.

Review details

Suppressed comments (3)

docs/adr/0019-ship-the-spec-kit-extension-treating-the-spike-no-go-as-a-measurement-artifact.md:325

• The accepted ADR repeats the abbreviated cb037d69fe62c7d8… instead of recording the complete SHA-256. Because this is the durable decision evidence, the digest should be independently verifiable; use the same full value recorded in the reference-verification document rather than an ellipsis.

| `extensions/EXTENSION-API-REFERENCE.md`: `v1.0.4` vs `v1.0.5` vs `v1.0.6` | byte-identical at all three tags (896 lines, SHA-256 `cb037d69fe62c7d8…`). The extension-facing contract does not move inside the `1.0` line. |

docs/reference-verification-spec-kit-extension.md:198

• This new evidence row records only cb037d69fe62c7d8… rather than a complete SHA-256, so the claimed byte identity cannot be independently verified. The same evidence file records full 64-character digests for its pinned artifacts at lines 48-51; please record the full digest here and keep it identical in the ADR addendum.

| `extensions/EXTENSION-API-REFERENCE.md` at `v1.0.4` vs `v1.0.5` vs `v1.0.6` | **byte-identical across all three** — 896 lines, SHA-256 `cb037d69fe62c7d8…` at every tag. The extension-facing contract did not move inside the `1.0` line. |

packages/adapters/spec-kit/extension.yml:7

• The 1.0.6 change documented in this PR (docs/reference-verification-spec-kit-extension.md:214-219) changes generated metadata.author; it is neither a refactor nor strictly more permissive. Describing all loader changes this way makes the manifest's compatibility rationale factually incomplete. Qualify this summary to call out the metadata attribution change separately.

# the loader's changes over it are additive, refactor, or strictly more permissive.

• Files reviewed: 12/12 changed files
• Comments generated: 0
• Review effort level: Lite