[Extension]: Add spec-kit-arch-governance

[ashbrener]

Extension ID

arch-governance

Extension Name

Architecture Governance

Version

1.2.2

Description

Keep specs, code & ADRs in sync: citation slots + a read-only, fail-closed validator.

Author

Ash Brener

Repository URL

https://github.com/ashbrener/spec-kit-arch-governance

Download URL

https://github.com/ashbrener/spec-kit-arch-governance/archive/refs/tags/v1.2.2.zip

License

MIT

Homepage (optional)

https://github.com/ashbrener/spec-kit-arch-governance

Documentation URL (optional)

https://github.com/ashbrener/spec-kit-arch-governance/blob/main/README.md

Changelog URL (optional)

https://github.com/ashbrener/spec-kit-arch-governance/blob/main/CHANGELOG.md

Required Spec Kit Version

=0.1.0

Required Tools (optional)

• python (>=3.11) — required
• uv — required; the commands invoke the bundled scripts via uv run
• pydantic (>=2.6), pyyaml (>=6.0) — required, resolved on demand by uv, nothing to pre-install
• git — optional; used only to check that accepted ADR bodies have not been edited in place. Absent git degrades to an advisory note, never a failure.

The validator performs no network access and never writes to the repository it inspects.

Number of Commands

6

Number of Hooks (optional)

3

Tags

architecture, governance, adr, citations, spec-sync

Key Features

Spec Kit produces specs, plans and code that are individually correct and collectively drifting: a plan cites a decision that has since been superseded, a spec derives from an upstream feature that has moved, and nothing tells you until someone reads both. This extension makes those links declared, checkable, and enforced on the lifecycle — without asking you to rename a file or adopt a new folder layout.

The convention is defined once, as data. ARCH-ADR-000 (shipped in docs/adr/, with a machine-readable vocabulary.json) fixes the vocabulary: repo roles, artefact kinds, the typed relations derived_from / cites / implements / supersedes, and the ADR-identifier grammar. Other tools conform to it as a documented format — no runtime dependency on this extension.

• Born-compliant templates. install prepends the derived_from: / cites: citation slots to your spec-template.md and plan-template.md, so every artefact Spec Kit generates already carries the slot. Idempotent and non-destructive — a hand-edited slot is left alone.
• /speckit.arch-governance.validate — a read-only validator running six checks: citations resolve, cited ADRs are current (not superseded/deprecated), identifiers are well-formed, accepted ADR bodies are unedited, the governance ADR is adopted, and cited upstream content has not moved. It never mutates the repo.
• /speckit.arch-governance.gate — the same engine as a decision at the implementation boundary: proceed / warn / halt. Fail-closed — an unevaluable citation set in blocking mode halts rather than waving work through.
• /speckit.arch-governance.repin — reconciles the watermark pins that detect upstream drift. Dry-run by default; --apply writes only this repo's pin file, never a peer and never a remote.
• /speckit.arch-governance.sync and /speckit.arch-governance.issues — multi-repo self-configuration from a shared domain manifest, and an optional mirror of validated staleness facts into GitHub issues.

Design properties worth knowing before installing:

• Advisory before blocking. Enforcement ships as warnings. Flipping a repo to hard-blocking is a guarded per-repo decision, and install refuses the flip while citations are still failing — so you only ever go blocking from a proven-clean state.
• Zero-rename adoption. A repo whose ADRs are stored as plain ADR-007 conforms without renaming anything: the namespace is declared in configuration, not in the filename. Cross-repo citations must still be fully qualified.
• Immutable targets. Accepted ADRs are content-frozen above an ## Amendments heading; a decision change is a new ADR that supersedes the old, so a citation means the same thing forever.
• Read-only and offline. No network access, no writes to the artefacts it checks. Drift detection hashes content locally — it never reaches across to a peer repository.
• Topology-agnostic. source / build / standalone are first-class; a single-repo project is not a degraded case. No repository names are hardcoded anywhere.
• Graceful in every direction. Unpinned citations are advisory nudges, not failures, so a project that adopts nothing keeps working; every cannot-evaluate state degrades to an informational note rather than a crash or a false block.

Dogfooded on itself — the repository governs its own specs and ADRs with this extension — and exercised on a private multi-repo project across a docs/backend/frontend topology.

Testing Checklist

• Extension installs successfully via download URL
• All commands execute without errors
• Documentation is complete and accurate
• No security vulnerabilities identified
• Tested on at least one real project

Submission Requirements

• Valid extension.yml manifest included
• README.md with installation and usage instructions
• LICENSE file included
• GitHub release created with version tag
• All command files exist and are properly formatted
• Extension ID follows naming conventions (lowercase-with-hyphens)

[github-actions]

cc @github/spec-kit-maintainers — new catalog submission for review.

[github-actions]

Pull request created: #4085

Generated by Add Community Extension from Issue Submission · 344.1 AIC · ⌖ 16.3 AIC · ⊞ 35.3K

[KSchlobohm]

Hi @ashbrener — Copilot found an issue in PR #4085 that blocks review:

The linked README currently advertises Version: 1.1.0 and Provides: 5 commands on both main and the v1.2.2 tag, while this catalog entry publishes version 1.2.2 with 6 commands. This conflicts with the submission's claim that documentation is complete and accurate and gives catalog users stale compatibility/surface information. Please update the upstream README so this URL documents the submitted release accurately before publishing the entry.
#4085 (comment)

Please reply here when fixed so we can re-check the PR.

[ashbrener]

Thanks @KSchlobohm — good catch, and the finding was correct. Fixed and re-verified.

What was wrong: README.md advertised Version: 1.1.0 · Provides: 5 commands, 3 hooks while the manifest was 1.2.2 with 6 commands. The README body already documented all six commands correctly — only the header line was stale — but as you say, that's what a catalog user reads, and it understated the release by a version and a whole command (issues).

Fixed in v1.2.3 (ashbrener/spec-kit-arch-governance#21):

• README header now reads Version: 1.2.3 · Provides: 6 commands, 3 hooks, matching the manifest.
• Added a regression guard — test_readme_header_matches_the_manifest pins the README header to extension.yml, so this specific drift now fails the suite rather than reaching a reviewer. Verified red-first.

I cut a new patch release rather than re-pointing the v1.2.2 tag, since the v1.2.2 archive itself carries the stale README and quietly moving a published tag would have hidden the problem rather than fixed it.

Two fields in PR #4085 need updating to match — apologies for the extra step:

Field	From	To
version	1.2.2	1.2.3
download_url	.../tags/v1.2.2.zip	https://github.com/ashbrener/spec-kit-arch-governance/archive/refs/tags/v1.2.3.zip

Everything else in the entry is unchanged.

Verified just now against the published artifacts:

• download_url returns HTTP 200
• README inside the archive: Version: 1.2.3 · Provides: 6 commands, 3 hooks
• extension.yml inside the archive: 1.2.3, 6 commands, 3 hooks
• Documentation URL (/blob/main/README.md): same header, consistent with the entry
• uv run pytest -q → 316 passed

Ready for re-check whenever you are.