### 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 - [X] Extension installs successfully via download URL - [X] All commands execute without errors - [X] Documentation is complete and accurate - [X] No security vulnerabilities identified - [X] Tested on at least one real project ### Submission Requirements - [X] Valid `extension.yml` manifest included - [X] README.md with installation and usage instructions - [X] LICENSE file included - [X] GitHub release created with version tag - [X] All command files exist and are properly formatted - [X] Extension ID follows naming conventions (lowercase-with-hyphens)