From a5689f975c9a7c6b38a60234727c56a3cc230021 Mon Sep 17 00:00:00 2001
From: Jason Anton <jason@stoopid.email>
Date: Fri, 1 May 2026 13:42:54 -0400
Subject: [PATCH 1/3] docs: add docs/ scaffolding with ADR and runbook
 conventions

Establish the docs/ structure as the canonical location for project
documentation that bridges business need and technical reality.

Adds:
- docs/README.md: tech spec template covering overview, goals/non-goals,
  current state, solution, constraints, open questions, and glossary.
- docs/adrs/: architectural decision records using an extended Michael
  Nygard format (Title, Status, Context, Decision, Consequences,
  Alternatives Considered). Includes README documenting when to write
  an ADR, the lifecycle, and numbering conventions.
- docs/runbooks/: operational runbook template optimized for
  high-stress reading. Includes README codifying when to write one
  and the maintenance discipline (review-on-use, quarterly audit).

Each subdirectory contains both a curated README index and a template
file. Templates use the same blockquote convention as the rest of the
repository (delete-after-instantiation).

This is the foundation for follow-up work: Makefile generation
targets (make adr / make runbook), CI-enforced docs hygiene
(adr-lint with pre-commit and GitHub Actions integration), staleness
detection, and broader documentation automation. Those land in
subsequent commits to keep this change reviewable in isolation.
---
 .github/PULL_REQUEST_TEMPLATE.md |   0
 .github/workflows/adr-lint.yml   |  34 +++++
 .gitignore                       |   2 +-
 .pre-commit-config.yaml          |  41 +++++-
 .vscode/extensions.json          |   2 +-
 .vscode/settings.json            |   2 +-
 CODE_OF_CONDUCT.md               |   6 +-
 CONTRIBUTING.md                  |  18 +--
 Makefile                         | 145 +++++++++++++++++++
 docs/README.md                   | 133 +++++++++++++++++
 docs/adrs/README.md              |  93 ++++++++++++
 docs/adrs/template.md            |  50 +++++++
 docs/runbooks/README.md          | 101 +++++++++++++
 docs/runbooks/template.md        |  88 ++++++++++++
 scripts/README.md                | 110 +++++++++++++++
 scripts/adr-lint.py              | 235 +++++++++++++++++++++++++++++++
 16 files changed, 1041 insertions(+), 19 deletions(-)
 mode change 100755 => 100644 .github/PULL_REQUEST_TEMPLATE.md
 create mode 100644 .github/workflows/adr-lint.yml
 create mode 100644 docs/README.md
 create mode 100644 docs/adrs/README.md
 create mode 100644 docs/adrs/template.md
 create mode 100644 docs/runbooks/README.md
 create mode 100644 docs/runbooks/template.md
 create mode 100644 scripts/README.md
 create mode 100755 scripts/adr-lint.py

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
old mode 100755
new mode 100644
diff --git a/.github/workflows/adr-lint.yml b/.github/workflows/adr-lint.yml
new file mode 100644
index 0000000..b5e7dc9
--- /dev/null
+++ b/.github/workflows/adr-lint.yml
@@ -0,0 +1,34 @@
+name: ADR Lint
+
+on:
+  pull_request:
+    paths:
+      - "docs/adrs/**"
+      - "scripts/adr-lint.py"
+      - ".github/workflows/adr-lint.yml"
+  push:
+    branches: [ main ]
+    paths:
+      - "docs/adrs/**"
+      - "scripts/adr-lint.py"
+      - ".github/workflows/adr-lint.yml"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: adr-lint-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  adr-lint:
+    name: ADR lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Run adr-lint (strict mode)
+        run: scripts/adr-lint.py --adr-dir docs/adrs --strict
diff --git a/.gitignore b/.gitignore
index 2e527d3..1fb8fe1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -367,4 +367,4 @@ scratch/
 NOTES.local.md
 TODO.local.md
 *.local
-*.local.*
\ No newline at end of file
+*.local.*
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index b389896..dd667f3 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -47,13 +47,24 @@ repos:
   # Conventional Commits validation
   # ===========================================================================
   - repo: https://github.com/compilerla/conventional-pre-commit
-    rev: v3.6.0
+    rev: v4.0.0
     hooks:
       - id: conventional-pre-commit
         stages: [ commit-msg ]
         args:
-          - --types
-          - feat,fix,docs,style,refactor,perf,test,build,ci,chore,revert
+          [
+            feat,
+            fix,
+            docs,
+            style,
+            refactor,
+            perf,
+            test,
+            build,
+            ci,
+            chore,
+            revert,
+          ]
 
   # ===========================================================================
   # Markdown
@@ -147,11 +158,30 @@ repos:
       - id: prettier
         name: prettier
         language: system
-        entry: pnpm exec prettier --write --ignore-unknown
-        files: \.(js|jsx|ts|tsx|mjs|cjs|json|jsonc|css|scss|html|md|yaml|yml)$
+        entry: bash -c 'test -f package.json && pnpm exec prettier --write
+          --ignore-unknown "$@" || exit 0' --
+        files: \.(js|jsx|ts|tsx|mjs|cjs|json|jsonc|css|scss|html)$
         pass_filenames: true
         require_serial: false
 
+  # ===========================================================================
+  # Documentation — runs only when ADR files or the index change
+  # ===========================================================================
+  - repo: local
+    hooks:
+      - id: adr-lint
+        name: adr-lint
+        language: system
+        entry: scripts/adr-lint.py
+        files: ^docs/adrs/.*\.md$
+        pass_filenames: false
+        require_serial: true
+        description: >
+          Validate ADR numbering, status fields, supersession references, and
+          index synchronization. Runs on the entire docs/adrs/ tree, not just
+          changed files, because ADR integrity is a global property (gaps,
+          duplicates, cross-references).
+
 ci:
   autofix_commit_msg: "style: pre-commit auto-fixes"
   autoupdate_commit_msg: "chore(deps): pre-commit autoupdate"
@@ -161,3 +191,4 @@ ci:
     - prettier
     - cargo-check
     - terraform_validate
+    - adr-lint
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
index 3ec3f9e..80cf73c 100644
--- a/.vscode/extensions.json
+++ b/.vscode/extensions.json
@@ -35,4 +35,4 @@
     "ms-azuretools.vscode-docker",
     "ms-azuretools.vscode-containers"
   ]
-}
\ No newline at end of file
+}
diff --git a/.vscode/settings.json b/.vscode/settings.json
index 2ce71e3..0d9b95b 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -251,4 +251,4 @@
   "git.suggestSmartCommit": false,
 
   "terminal.integrated.scrollback": 10000
-}
\ No newline at end of file
+}
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
index 184c7e9..76cc266 100644
--- a/CODE_OF_CONDUCT.md
+++ b/CODE_OF_CONDUCT.md
@@ -86,12 +86,12 @@ harassment of an individual, or aggression toward or disparagement of classes of
 ## Attribution
 
 This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0, available at
-https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+<https://www.contributor-covenant.org/version/2/0/code_of_conduct.html>.
 
 Community Impact Guidelines were inspired by
 [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
 
 [homepage]: https://www.contributor-covenant.org
 
-For answers to common questions about this code of conduct, see the FAQ at https://www.contributor-covenant.org/faq.
-Translations are available at https://www.contributor-covenant.org/translations.
+For answers to common questions about this code of conduct, see the FAQ at <https://www.contributor-covenant.org/faq>.
+Translations are available at <https://www.contributor-covenant.org/translations>.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 64ae6f6..699120e 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -232,7 +232,7 @@ reasonable choice; consult the project's `README.md` for specifics.
 
 The exact layout varies by project, but common top-level directories include:
 
-```
+```sh
 <repo>/
 ├── .github/             # CI workflows, issue/PR templates, Dependabot config
 ├── .vscode/             # Shared editor settings and extension recommendations
@@ -283,12 +283,14 @@ A CI check (commitlint) verifies every commit on every pull request.
 
 ### Format
 
-```
-<type>(<scope>)<!>: <subject>
-
-<body>
-
-<footer>
+```html
+<type
+  >(<scope
+    >)<!>:
+    <subject>
+      <body>
+        <footer></footer></body></subject></scope
+></type>
 ```
 
 - `<type>` — one of: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`
@@ -300,7 +302,7 @@ A CI check (commitlint) verifies every commit on every pull request.
 
 ### Examples
 
-```
+```sh
 feat(auth): add refresh token rotation
 
 fix: handle null user agent in request logger
diff --git a/Makefile b/Makefile
index b2c35b4..f168495 100644
--- a/Makefile
+++ b/Makefile
@@ -219,6 +219,151 @@ docker-push: ## Push Docker image
 	@docker push $(IMAGE):$(TAG)
 	@docker push $(IMAGE):latest
 
+# =============================================================================
+##@ Documentation
+# =============================================================================
+
+ADR_DIR     := docs/adrs
+RUNBOOK_DIR := docs/runbooks
+
+.PHONY: adr
+adr: ## Create a new ADR (usage: make adr TITLE="Use Postgres")
+	@if [ -z "$(TITLE)" ]; then \
+		echo "ERROR: TITLE is required. Usage: make adr TITLE=\"Your decision title\""; \
+		exit 1; \
+	fi
+	@if [ ! -f $(ADR_DIR)/template.md ]; then \
+		echo "ERROR: $(ADR_DIR)/template.md not found."; \
+		exit 1; \
+	fi
+	@next=$$(ls $(ADR_DIR) 2>/dev/null | grep -E '^[0-9]{4}-' | sort | tail -1 | grep -oE '^[0-9]{4}' || echo "0000"); \
+	num=$$(printf "%04d" $$((10#$$next + 1))); \
+	slug=$$(echo "$(TITLE)" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$$//'); \
+	file="$(ADR_DIR)/$$num-$$slug.md"; \
+	today=$$(date +%Y-%m-%d); \
+	sed -e "s/ADR-NNNN: <short title of the decision>/ADR-$$num: $(TITLE)/" \
+	    -e "s/<YYYY-MM-DD>/$$today/" \
+	    $(ADR_DIR)/template.md > "$$file"; \
+	echo "Created $$file"; \
+	echo "Edit it, then add to the ADR index in $(ADR_DIR)/README.md"
+
+.PHONY: runbook
+runbook: ## Create a new runbook (usage: make runbook TITLE="Restore from backup")
+	@if [ -z "$(TITLE)" ]; then \
+		echo "ERROR: TITLE is required. Usage: make runbook TITLE=\"Your runbook title\""; \
+		exit 1; \
+	fi
+	@if [ ! -f $(RUNBOOK_DIR)/template.md ]; then \
+		echo "ERROR: $(RUNBOOK_DIR)/template.md not found."; \
+		exit 1; \
+	fi
+	@slug=$$(echo "$(TITLE)" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$$//'); \
+	file="$(RUNBOOK_DIR)/$$slug.md"; \
+	if [ -e "$$file" ]; then \
+		echo "ERROR: $$file already exists."; \
+		exit 1; \
+	fi; \
+	today=$$(date +%Y-%m-%d); \
+	sed -e "s/<short title — what this runbook is for>/$(TITLE)/" \
+	    -e "s/<YYYY-MM-DD>/$$today/" \
+	    $(RUNBOOK_DIR)/template.md > "$$file"; \
+	echo "Created $$file"; \
+	echo "Edit it, then add to the runbook index in $(RUNBOOK_DIR)/README.md"
+
+.PHONY: docs-check
+docs-check: ## Verify docs structure exists and templates are present
+	@missing=0; \
+	for f in docs/README.md $(ADR_DIR)/README.md $(ADR_DIR)/template.md $(RUNBOOK_DIR)/README.md $(RUNBOOK_DIR)/template.md; do \
+		if [ ! -f "$$f" ]; then \
+			echo "MISSING: $$f"; \
+			missing=1; \
+		fi; \
+	done; \
+	if [ $$missing -eq 0 ]; then \
+		echo "==> Docs structure is complete."; \
+	else \
+		exit 1; \
+	fi
+
+.PHONY: adr-lint
+adr-lint: ## Validate ADR integrity (numbering, status, supersession, index)
+	@scripts/adr-lint.py --adr-dir $(ADR_DIR)
+
+.PHONY: adr-lint-strict
+adr-lint-strict: ## Validate ADRs with warnings promoted to errors (CI-equivalent)
+	@scripts/adr-lint.py --adr-dir $(ADR_DIR) --strict
+
+# =============================================================================
+##@ Git
+# =============================================================================
+
+.PHONY: commit
+commit: ## Stage changes (with confirmation), commit, and push
+	@if git diff --quiet && git diff --staged --quiet && [ -z "$$(git ls-files --others --exclude-standard)" ]; then \
+		echo "Nothing to commit. Working tree is clean."; \
+		exit 0; \
+	fi; \
+	echo "==> Pending changes:"; \
+	git status --short; \
+	echo ""; \
+	echo "==> Diff stat:"; \
+	git diff --stat HEAD; \
+	echo ""; \
+	printf "Stage all changes (including untracked) and commit? [y/N] "; \
+	read confirm; \
+	case "$$confirm" in \
+		y|Y|yes|YES) ;; \
+		*) echo "Aborted."; exit 1 ;; \
+	esac; \
+	git add -A; \
+	if command -v cz >/dev/null 2>&1; then \
+		echo "==> Using commitizen (cz commit)"; \
+		cz commit || exit 1; \
+	elif command -v git-cz >/dev/null 2>&1; then \
+		echo "==> Using commitizen (git cz)"; \
+		git cz || exit 1; \
+	else \
+		echo "==> commitizen not found; opening git commit editor"; \
+		echo "    (conventional-pre-commit hook will validate the message)"; \
+		git commit || exit 1; \
+	fi
+	@if [ -z "$(NO_PUSH)" ]; then \
+		$(MAKE) --no-print-directory push; \
+	else \
+		echo "==> NO_PUSH set; skipping push. Run 'make push' when ready."; \
+	fi
+
+.PHONY: push
+push: ## Push current branch with safety checks
+	@branch=$$(git rev-parse --abbrev-ref HEAD); \
+	if [ "$$branch" = "HEAD" ]; then \
+		echo "ERROR: detached HEAD state. Check out a branch before pushing."; \
+		exit 1; \
+	fi; \
+	echo "==> Fetching origin/$$branch..."; \
+	git fetch origin "$$branch" 2>/dev/null || true; \
+	if [ "$$branch" = "main" ]; then \
+		if git rev-parse --verify --quiet origin/main >/dev/null; then \
+			local_sha=$$(git rev-parse main); \
+			remote_sha=$$(git rev-parse origin/main); \
+			base_sha=$$(git merge-base main origin/main); \
+			if [ "$$local_sha" != "$$remote_sha" ]; then \
+				if [ "$$base_sha" = "$$local_sha" ]; then \
+					echo "ERROR: local main is behind origin/main."; \
+					echo "       Run 'git pull --ff-only' before pushing."; \
+					exit 1; \
+				elif [ "$$base_sha" != "$$remote_sha" ]; then \
+					echo "ERROR: local main has diverged from origin/main."; \
+					echo "       Local has commits origin/main does not, AND vice versa."; \
+					echo "       Resolve before pushing."; \
+					exit 1; \
+				fi; \
+			fi; \
+		fi; \
+	fi; \
+	echo "==> Pushing $$branch to origin..."; \
+	git push --set-upstream origin "$$branch"
+
 # =============================================================================
 ##@ Cleanup
 # =============================================================================
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..8fd5ed7
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,133 @@
+# <PROJECT_NAME>
+
+> **Template note:** This is the technical specification for the project. It
+> is the bridge between business need and technical reality — the document a
+> new engineer reads to understand _what_ this project is and _why_ it exists,
+> and the document a business stakeholder reads to understand _what_ is
+> actually being built. Keep it current; a stale tech spec is worse than no
+> tech spec.
+>
+> Replace `<PROJECT_NAME>` and all other placeholders below before publishing.
+> Delete this blockquote once instantiated.
+
+**Status:** <draft | active | deprecated>
+**Last reviewed:** <YYYY-MM-DD>
+**Owner:** <team or individual>
+
+## Table of Contents
+
+- [\<PROJECT_NAME\>](#project_name)
+  - [Table of Contents](#table-of-contents)
+  - [Overview](#overview)
+  - [Goals and Non-goals](#goals-and-non-goals)
+    - [Goals](#goals)
+    - [Non-goals](#non-goals)
+  - [Current State](#current-state)
+  - [Solution](#solution)
+    - [Key components](#key-components)
+    - [Significant design decisions](#significant-design-decisions)
+  - [Constraints and Assumptions](#constraints-and-assumptions)
+    - [Technical](#technical)
+    - [Regulatory and organizational](#regulatory-and-organizational)
+    - [Assumptions](#assumptions)
+  - [Open Questions](#open-questions)
+  - [Glossary](#glossary)
+
+## Overview
+
+<One paragraph: what this project is, who it serves, and what it produces.
+Written so a non-technical stakeholder can understand it.>
+
+<One paragraph: the problem it solves. What was the situation before this
+project existed, what was painful, and why is solving it worth doing now.>
+
+## Goals and Non-goals
+
+### Goals
+
+What this project will do. Each goal should be specific enough to be testable.
+
+- <Goal 1 — e.g. "Reduce average report generation time from 4 hours to under 5 minutes">
+- <Goal 2>
+- <Goal 3>
+
+### Non-goals
+
+What this project will explicitly **not** do. This section is as important as
+the goals section — it prevents scope creep and sets expectations.
+
+Use the `(deferred)` suffix for items that are out of scope _for now_ but may
+be revisited. Items without the suffix are out of scope permanently.
+
+- <Non-goal 1 — e.g. "Real-time report generation (deferred to v2)">
+- <Non-goal 2 — e.g. "Support for legacy XYZ format">
+- <Non-goal 3>
+
+## Current State
+
+What is actually built and working today. This section drifts faster than any
+other; review it whenever a meaningful capability lands or is removed.
+
+- <Capability 1 — what works, where it lives>
+- <Capability 2>
+- <Known gaps — things planned but not yet built>
+- <Known issues — things built but not working as intended>
+
+## Solution
+
+<High-level description of the architecture. What the major components are,
+how they fit together, and how data and control flow through the system.>
+
+<Embed or link a diagram here. Diagram source files belong in `diagrams/` if
+this project uses that directory.>
+
+### Key components
+
+- **<Component 1>** — <one-line purpose>. <Where it lives in the repo.>
+- **<Component 2>** — <one-line purpose>. <Where it lives in the repo.>
+
+### Significant design decisions
+
+Significant decisions live in [`adrs/`](./adrs/) as ADRs. Reference them inline
+where relevant rather than restating them here. Examples:
+
+- See [ADR-0001](./adrs/0001-example.md) for <decision topic>.
+- See [ADR-0002](./adrs/0002-example.md) for <decision topic>.
+
+## Constraints and Assumptions
+
+Things outside the team's control that shape the solution. Keep this honest —
+unstated assumptions cause the worst kinds of failure.
+
+### Technical
+
+- <e.g. "Must run on Kubernetes 1.28+">
+- <e.g. "Downstream system X has a 100 req/sec rate limit">
+
+### Regulatory and organizational
+
+- <e.g. "PII must remain in US-East region">
+- <e.g. "Quarterly security audit required by compliance">
+
+### Assumptions
+
+- <e.g. "Upstream service Y will continue to provide field Z in its current format">
+- <e.g. "Team has at least one engineer with Rust experience for the duration">
+
+## Open Questions
+
+Append-only. When a question is answered, either:
+
+1. Move the resolution into the relevant section above and delete the question, or
+2. If the resolution involves a significant design decision, capture it in an ADR and link from here.
+
+- <Question 1 — owner, date raised>
+- <Question 2 — owner, date raised>
+
+## Glossary
+
+Project-specific terms. Generic industry terms do not belong here. When this
+list grows past ~20 entries, split it into `docs/glossary.md`.
+
+- **<Term>** — <definition>
+- **<Term>** — <definition>
diff --git a/docs/adrs/README.md b/docs/adrs/README.md
new file mode 100644
index 0000000..10cdeed
--- /dev/null
+++ b/docs/adrs/README.md
@@ -0,0 +1,93 @@
+# Architectural Decision Records
+
+This directory contains the architectural decision records (ADRs) for this
+project. ADRs document the significant choices made during the project's
+lifetime — the choices that are non-obvious, hard to reverse, or that affect
+multiple components.
+
+## When to write an ADR
+
+Write an ADR when a decision is:
+
+- **Non-obvious** — a future engineer might reasonably wonder why this choice was made.
+- **Hard to reverse** — once made, undoing it requires meaningful migration work.
+- **Cross-cutting** — it affects multiple components, services, or teams.
+- **Externally constrained** — driven by regulation, contract, or an organizational mandate that should be recorded.
+
+Do **not** write an ADR for:
+
+- Implementation details that are clear from the code itself.
+- Reversible defaults (e.g. choice of CSS framework in a single-page UI).
+- Decisions covered by an existing ADR — supersede or amend it instead.
+
+If you are unsure whether something deserves an ADR, the cost of writing one
+is low and the cost of not having one years later is high. Write the ADR.
+
+## Format
+
+Every ADR follows the [Michael Nygard
+template](https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/locales/en/templates/decision-record-template-by-michael-nygard/index.md)
+extended with a few sections we have found useful:
+
+- **Status** — proposed / accepted / deprecated / superseded by ADR-NNNN
+- **Date** — when the decision was made (or last updated)
+- **Deciders** — who agreed to it
+- **Context** — what forces are at play
+- **Decision** — the choice made
+- **Consequences** — what becomes true, easier, and harder
+- **Alternatives Considered** — what was rejected and why
+- **References** — optional, links to prior art and related ADRs
+
+The canonical template is in [`template.md`](./template.md).
+
+## Lifecycle
+
+ADRs are append-only as a body of work. Individual ADRs progress through
+statuses; they are never deleted.
+
+```text
+proposed → accepted → (deprecated | superseded by ADR-NNNN)
+```
+
+- **proposed** — the decision is drafted but not yet ratified. Open for discussion.
+- **accepted** — the decision is in effect.
+- **deprecated** — the decision no longer applies, but no replacement exists. Rare.
+- **superseded by ADR-NNNN** — the decision has been replaced. Link to the replacement.
+
+When superseding an ADR, update the old one's status to
+`superseded by ADR-NNNN` and add a one-line note pointing at the new ADR.
+Never edit the body of a superseded ADR — its content is the historical
+record.
+
+## Numbering
+
+ADRs are numbered sequentially with a four-digit zero-padded prefix:
+
+```text
+0001-use-postgres-for-primary-storage.md
+0002-adopt-conventional-commits.md
+0003-deploy-via-helm.md
+```
+
+Numbers are never reused. If an ADR is abandoned before acceptance, leave a
+short stub explaining why.
+
+## Creating a new ADR
+
+Use the Makefile target from the repository root:
+
+```sh
+make adr TITLE="Use Postgres for primary storage"
+```
+
+This finds the next available number, copies [`template.md`](./template.md),
+and fills in the title, date, and slug. It does not commit the file —
+review and edit before committing.
+
+## Index
+
+<!-- Update this section when adding or changing ADRs. Do not auto-generate -->
+<!-- — the index is part of the documentation, and a hand-curated list reads -->
+<!-- better than a `ls`-style dump. -->
+
+- _(no ADRs yet)_
diff --git a/docs/adrs/template.md b/docs/adrs/template.md
new file mode 100644
index 0000000..dd88d7e
--- /dev/null
+++ b/docs/adrs/template.md
@@ -0,0 +1,50 @@
+# ADR-NNNN: <short title of the decision>
+
+**Status:** proposed
+**Date:** <YYYY-MM-DD>
+**Deciders:** <names or roles>
+
+## Context
+
+<What is the issue that is motivating this decision? Describe the forces at
+play: technical, business, organizational, regulatory. State facts, not
+opinions. A reader who knows nothing about this decision should understand
+_why it needs to be made_ after reading this section.>
+
+## Decision
+
+<What is the change being made? State it as a clear directive in the active
+voice. "We will use X." Not "X seems like a good option.">
+
+## Consequences
+
+<What becomes easier, what becomes harder, and what is now true that was not
+true before. Include both positive and negative consequences. Be honest about
+the tradeoffs — an ADR with only upsides is not an ADR, it is marketing.>
+
+### Positive
+
+- <Consequence>
+
+### Negative
+
+- <Consequence>
+
+### Neutral
+
+- <Consequence>
+
+## Alternatives Considered
+
+<Brief notes on the alternatives that were rejected and why. One paragraph or
+short bullet list per alternative. This section exists so future readers
+understand why the obvious-seeming alternative was not chosen.>
+
+- **<Alternative 1>** — <why rejected>
+- **<Alternative 2>** — <why rejected>
+
+## References
+
+<Optional. Links to related ADRs, external documentation, RFCs, prior art.>
+
+- <Link>
diff --git a/docs/runbooks/README.md b/docs/runbooks/README.md
new file mode 100644
index 0000000..bfe663b
--- /dev/null
+++ b/docs/runbooks/README.md
@@ -0,0 +1,101 @@
+# Runbooks
+
+This directory contains operational runbooks — step-by-step procedures for
+handling specific operational situations. Runbooks are written to be followed
+under stress, often by someone who did not write them.
+
+## When to write a runbook
+
+Write a runbook for any procedure that:
+
+- An on-call engineer might need to execute at 3 AM.
+- Recurs predictably (weekly maintenance, quarterly key rotation, deployment cutover).
+- Has a non-obvious recovery path.
+- Has caused an incident before — the runbook is the first artifact of the post-mortem.
+
+Do **not** write a runbook for:
+
+- One-off tasks that will not recur.
+- Procedures fully automated by tooling — automate further or document the tool's usage instead.
+- General development workflow — that belongs in `CONTRIBUTING.md`.
+
+## What makes a good runbook
+
+A runbook is read by a tired, stressed person who needs to act. Optimize for
+that reader, not for completeness or elegance.
+
+- **Specific triggers.** Vague triggers ("when the system is slow") make
+  runbooks get followed at the wrong time. State exact alerts, exact
+  thresholds, exact symptoms.
+- **One action per step.** Multi-action steps cause skipped actions under
+  pressure.
+- **Expected results inline.** Every action says what should happen if it
+  worked. Without this, the responder cannot tell whether to continue or
+  stop.
+- **Mandatory rollback section.** Even if the answer is "no rollback
+  possible," state that explicitly.
+- **Verification before declaring done.** Resolution without verification is
+  just hope.
+
+## Format
+
+The canonical template is in [`template.md`](./template.md). It includes:
+
+- Status header (last reviewed date, owner, severity)
+- Purpose
+- When to use this runbook (the trigger)
+- Prerequisites (access, tools, context)
+- Diagnosis (confirm before acting)
+- Resolution (numbered steps, expected results)
+- Verification
+- Rollback
+- Escalation
+- Post-incident
+- References
+
+## Naming
+
+Use a short, action-oriented filename:
+
+```text
+restore-from-backup.md
+rotate-database-credentials.md
+recover-from-failed-deploy.md
+handle-elevated-error-rate.md
+```
+
+Avoid alert names as filenames — alert names change. Describe what the
+runbook _does_.
+
+## Maintenance
+
+Runbooks rot faster than any other documentation because the systems they
+operate on change. To stay useful:
+
+- **Review on use.** Anyone who runs a runbook updates the
+  `Last reviewed` date and corrects anything that was wrong, missing, or
+  unclear. This is non-negotiable. A runbook that worked in March may not
+  work in November.
+- **Quarterly audit.** Owner reviews any runbook not touched in 90 days.
+  Either re-validate, update, or archive.
+- **Archive, don't delete.** When a runbook is no longer needed (system
+  retired, automated away), move it to an `archived/` subdirectory rather
+  than deleting. The historical record is useful.
+
+## Creating a new runbook
+
+Use the Makefile target from the repository root:
+
+```sh
+make runbook TITLE="Restore from backup"
+```
+
+This copies [`template.md`](./template.md) and fills in the title, date, and
+slug. It does not commit the file — review and edit before committing.
+
+## Index
+
+<!-- Update this section when adding or changing runbooks. Group by category -->
+<!-- when the list grows past ~10 entries. -->
+
+- _(no runbooks yet)_
diff --git a/docs/runbooks/template.md b/docs/runbooks/template.md
new file mode 100644
index 0000000..e8036cf
--- /dev/null
+++ b/docs/runbooks/template.md
@@ -0,0 +1,88 @@
+# Runbook: <short title — what this runbook is for>
+
+**Last reviewed:** <YYYY-MM-DD>
+**Owner:** <team or individual>
+**Severity:** <SEV-1 | SEV-2 | SEV-3 | informational>
+
+## Purpose
+
+<One or two sentences: what condition or task this runbook addresses, and who
+should follow it. If a reader is not the right audience, they should know
+within five seconds.>
+
+## When to use this runbook
+
+<The trigger. An alert firing, a customer report, a scheduled task, a
+deployment step. Be specific — a runbook with a vague trigger gets followed
+when it shouldn't and ignored when it should.>
+
+- <Specific symptom, alert name, or condition>
+- <Specific symptom, alert name, or condition>
+
+## Prerequisites
+
+What the responder needs before starting. If any of these are not true, stop
+and acquire them before continuing — half-credentialed operators cause
+incidents.
+
+- **Access:** <required permissions, VPN, bastion, kubeconfig, etc.>
+- **Tools:** <CLI tools, dashboard URLs, query consoles>
+- **Context:** <links to relevant dashboards, on-call channel, incident channel>
+
+## Diagnosis
+
+How to confirm the condition matches what this runbook is written for. Do not
+skip this step — running the wrong runbook makes things worse.
+
+1. <Check 1 — what to look at, what "good" looks like, what "bad" looks like>
+2. <Check 2>
+3. <Check 3>
+
+If diagnosis does not match, **stop**. Either find the correct runbook or
+escalate per the [Escalation](#escalation) section.
+
+## Resolution
+
+Numbered steps. One action per step. Each step states the expected result so
+the responder knows whether to continue or stop.
+
+1. <Action> — _expected result:_ <what should happen>
+2. <Action> — _expected result:_ <what should happen>
+3. <Action> — _expected result:_ <what should happen>
+
+### Verification
+
+How to confirm the issue is resolved. Resolution without verification is just
+hope.
+
+- <Verification check 1>
+- <Verification check 2>
+
+## Rollback
+
+If resolution makes things worse, how to undo it. This section is mandatory
+even when "no rollback needed" — make that explicit rather than leaving it
+ambiguous.
+
+1. <Rollback action> — _expected result:_ <what should happen>
+
+## Escalation
+
+When this runbook is not enough.
+
+- **If <condition>:** <who to page, channel to post in, ticket to file>
+- **If unresolved after <duration>:** <next escalation step>
+
+## Post-incident
+
+What to do after the immediate situation is handled.
+
+- File an incident report if this was a SEV-1 or SEV-2.
+- Update this runbook if any step was wrong, missing, or unclear.
+- Open a follow-up ticket for any underlying cause that this runbook only worked around.
+
+## References
+
+- <Link to related ADRs>
+- <Link to dashboards, alerts, or upstream docs>
+- <Link to past incident reports involving this runbook>
diff --git a/scripts/README.md b/scripts/README.md
new file mode 100644
index 0000000..a6dff76
--- /dev/null
+++ b/scripts/README.md
@@ -0,0 +1,110 @@
+# Scripts
+
+Supporting scripts that aren't part of any package or service. This directory
+holds repository-level tooling — linters, validators, generators, one-off
+utilities — that operate on the project as a whole.
+
+## What belongs here
+
+- Validators that check repository-wide invariants (e.g. `adr-lint.py`)
+- Generators that produce documentation, reports, or scaffolding
+- Migration helpers that don't fit inside any one service
+- Utility scripts called by `Makefile` targets, CI workflows, or pre-commit hooks
+
+## What does **not** belong here
+
+- Code that is part of a package or service — that lives in `packages/` or `services/`
+- Generic developer tooling already provided by language ecosystems (use the tool directly)
+- One-off scripts that won't be re-run — keep those in a personal scratch directory, not in version control
+
+## Conventions
+
+### Language
+
+Default to Python for any script over ~30 lines. Bash is acceptable for
+short, obvious scripts (a few `find` and `sed` invocations). Past 30 lines,
+bash becomes harder to maintain than Python and the case for switching is
+strong.
+
+### Self-contained Python
+
+Python scripts use [`uv` inline script
+metadata](https://docs.astral.sh/uv/guides/scripts/) so they have no
+project-level dependencies. The shebang and metadata block at the top of
+the file declare what the script needs:
+
+```python
+#!/usr/bin/env -S uv run --quiet --script
+# /// script
+# requires-python = ">=3.11"
+# dependencies = []
+# ///
+```
+
+This means scripts can be invoked directly (`./scripts/foo.py`) without
+activating a virtualenv or running `uv sync`. If `uv` is not installed,
+they can still be run as `python3 scripts/foo.py` provided the dependencies
+are available.
+
+Prefer stdlib over external dependencies. If a script needs an external
+package, weigh whether the script earns its dependency cost.
+
+### Naming
+
+Hyphenated, lowercase, descriptive of what the script does:
+
+```text
+adr-lint.py
+docs-staleness-check.py
+generate-codeowners.sh
+```
+
+Avoid underscored names. Scripts are CLI tools, not Python modules — they
+are never imported.
+
+### Executable bit
+
+All scripts are committed with the executable bit set:
+
+```sh
+chmod +x scripts/<name>
+```
+
+Verify after creating a new script.
+
+### Exit codes
+
+Scripts use conventional exit codes:
+
+- `0` — success
+- `1` — checks failed (the script ran correctly but found problems)
+- `2` — invocation error (bad arguments, missing files, environment issue)
+
+This separation matters in CI — a `1` is a "fix the code" signal, a `2` is
+"fix the workflow" signal.
+
+### Arguments
+
+Use `argparse` (Python) or document `getopts` flags (bash). Every script
+supports `--help` and prints something useful.
+
+## Invocation
+
+Scripts are typically invoked via:
+
+- A `Makefile` target (preferred for anything a developer runs locally)
+- A CI workflow step
+- A pre-commit hook
+- Direct invocation when debugging
+
+Avoid invoking scripts from inside other scripts unless there is a clear
+reason. Composition belongs in the `Makefile` or workflow YAML, not buried
+in script chains.
+
+## Index
+
+<!-- Update this section when adding or removing scripts. -->
+
+| Script                         | Purpose                                                  |
+| ------------------------------ | -------------------------------------------------------- |
+| [`adr-lint.py`](./adr-lint.py) | Validate the integrity of architectural decision records |
diff --git a/scripts/adr-lint.py b/scripts/adr-lint.py
new file mode 100755
index 0000000..f7f3acd
--- /dev/null
+++ b/scripts/adr-lint.py
@@ -0,0 +1,235 @@
+#!/usr/bin/env -S uv run --quiet --script
+# /// script
+# requires-python = ">=3.11"
+# dependencies = []
+# ///
+"""
+adr-lint — validate the integrity of architectural decision records.
+
+Checks performed:
+  1. Filename format: NNNN-slug.md (four-digit zero-padded prefix)
+  2. Numbering: no gaps, no duplicates, starts at 0001
+  3. Status: every ADR has a Status line with an allowed value
+  4. Supersession: 'superseded by ADR-NNNN' references resolve to a real ADR
+  5. Index sync: every ADR file has an entry in docs/adrs/README.md, and
+     every entry in the README points to a real file
+
+Exit codes:
+  0  all checks passed
+  1  one or more checks failed
+  2  invocation error (missing directory, etc.)
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+ALLOWED_STATUSES = {"proposed", "accepted", "deprecated"}
+SUPERSEDED_PATTERN = re.compile(r"^superseded by ADR-(\d{4})\b", re.IGNORECASE)
+FILENAME_PATTERN = re.compile(r"^(\d{4})-([a-z0-9]+(?:-[a-z0-9]+)*)\.md$")
+STATUS_LINE_PATTERN = re.compile(r"^\*\*Status:\*\*\s*(.+?)\s*$", re.MULTILINE)
+ADR_LINK_PATTERN = re.compile(r"\[(?:ADR-)?(\d{4})[^\]]*\]\((\d{4}-[^)]+\.md)\)")
+
+
+@dataclass
+class ADR:
+    path: Path
+    number: int
+    slug: str
+    status: str | None
+    superseded_by: int | None
+
+
+@dataclass
+class Finding:
+    level: str  # "error" or "warning"
+    message: str
+
+    def __str__(self) -> str:
+        prefix = "ERROR" if self.level == "error" else "WARN "
+        return f"  [{prefix}] {self.message}"
+
+
+def parse_adr(path: Path) -> tuple[ADR | None, list[Finding]]:
+    findings: list[Finding] = []
+    match = FILENAME_PATTERN.match(path.name)
+    if not match:
+        findings.append(
+            Finding("error", f"{path.name}: filename does not match NNNN-slug.md")
+        )
+        return None, findings
+
+    number = int(match.group(1))
+    slug = match.group(2)
+
+    try:
+        content = path.read_text(encoding="utf-8")
+    except OSError as e:
+        findings.append(Finding("error", f"{path.name}: cannot read file: {e}"))
+        return None, findings
+
+    status_match = STATUS_LINE_PATTERN.search(content)
+    if not status_match:
+        findings.append(Finding("error", f"{path.name}: missing **Status:** line"))
+        return ADR(path, number, slug, None, None), findings
+
+    status_raw = status_match.group(1).strip().lower()
+    superseded_by: int | None = None
+
+    if status_raw in ALLOWED_STATUSES:
+        status = status_raw
+    elif sup_match := SUPERSEDED_PATTERN.match(status_raw):
+        status = "superseded"
+        superseded_by = int(sup_match.group(1))
+    else:
+        findings.append(
+            Finding(
+                "error",
+                f"{path.name}: status '{status_match.group(1)}' is not "
+                f"one of: {sorted(ALLOWED_STATUSES)} or 'superseded by ADR-NNNN'",
+            )
+        )
+        status = None
+
+    return ADR(path, number, slug, status, superseded_by), findings
+
+
+def check_numbering(adrs: list[ADR]) -> list[Finding]:
+    findings: list[Finding] = []
+    if not adrs:
+        return findings
+
+    numbers = sorted(adr.number for adr in adrs)
+
+    seen: dict[int, list[Path]] = {}
+    for adr in adrs:
+        seen.setdefault(adr.number, []).append(adr.path)
+    for num, paths in seen.items():
+        if len(paths) > 1:
+            names = ", ".join(p.name for p in paths)
+            findings.append(
+                Finding("error", f"ADR-{num:04d} appears in multiple files: {names}")
+            )
+
+    expected = list(range(1, max(numbers) + 1))
+    missing = sorted(set(expected) - set(numbers))
+    for num in missing:
+        findings.append(
+            Finding("error", f"ADR-{num:04d} is missing (gap in numbering)")
+        )
+
+    if 0 in numbers:
+        findings.append(Finding("error", "ADR numbering must start at 0001, not 0000"))
+
+    return findings
+
+
+def check_supersession(adrs: list[ADR]) -> list[Finding]:
+    findings: list[Finding] = []
+    by_number = {adr.number: adr for adr in adrs}
+    for adr in adrs:
+        if adr.superseded_by is None:
+            continue
+        target = by_number.get(adr.superseded_by)
+        if target is None:
+            findings.append(
+                Finding(
+                    "error",
+                    f"{adr.path.name}: superseded by ADR-{adr.superseded_by:04d} "
+                    f"but that ADR does not exist",
+                )
+            )
+        elif target.number == adr.number:
+            findings.append(
+                Finding("error", f"{adr.path.name}: cannot supersede itself")
+            )
+    return findings
+
+
+def check_index_sync(adrs: list[ADR], readme_path: Path) -> list[Finding]:
+    findings: list[Finding] = []
+    if not readme_path.exists():
+        findings.append(Finding("error", f"{readme_path} does not exist"))
+        return findings
+
+    content = readme_path.read_text(encoding="utf-8")
+    referenced_files: set[str] = set()
+    for match in ADR_LINK_PATTERN.finditer(content):
+        referenced_files.add(match.group(2))
+
+    actual_files = {adr.path.name for adr in adrs}
+    in_dir_not_index = actual_files - referenced_files
+    in_index_not_dir = referenced_files - actual_files
+
+    for name in sorted(in_dir_not_index):
+        findings.append(Finding("warning", f"{name} is not listed in {readme_path}"))
+    for name in sorted(in_index_not_dir):
+        findings.append(
+            Finding("error", f"index references {name} but file does not exist")
+        )
+
+    return findings
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[1])
+    parser.add_argument(
+        "--adr-dir",
+        default="docs/adrs",
+        help="ADR directory (default: docs/adrs)",
+    )
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="Treat warnings as errors",
+    )
+    args = parser.parse_args()
+
+    adr_dir = Path(args.adr_dir)
+    if not adr_dir.is_dir():
+        print(f"adr-lint: {adr_dir} is not a directory", file=sys.stderr)
+        return 2
+
+    files = sorted(
+        p
+        for p in adr_dir.iterdir()
+        if p.is_file()
+        and p.suffix == ".md"
+        and p.name not in {"README.md", "template.md"}
+    )
+
+    all_findings: list[Finding] = []
+    adrs: list[ADR] = []
+
+    for path in files:
+        adr, findings = parse_adr(path)
+        all_findings.extend(findings)
+        if adr is not None:
+            adrs.append(adr)
+
+    all_findings.extend(check_numbering(adrs))
+    all_findings.extend(check_supersession(adrs))
+    all_findings.extend(check_index_sync(adrs, adr_dir / "README.md"))
+
+    errors = [f for f in all_findings if f.level == "error"]
+    warnings = [f for f in all_findings if f.level == "warning"]
+
+    if all_findings:
+        print(f"adr-lint: scanned {len(adrs)} ADR(s) in {adr_dir}")
+        for finding in all_findings:
+            print(finding)
+        print(f"\n{len(errors)} error(s), {len(warnings)} warning(s)")
+    else:
+        print(f"adr-lint: scanned {len(adrs)} ADR(s) in {adr_dir} — all checks passed")
+
+    if errors or (args.strict and warnings):
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

From f9ca05f8cc4e5a3973c130dda705b7fcc0407b9f Mon Sep 17 00:00:00 2001
From: Jason Anton <jason@stoopid.email>
Date: Sat, 2 May 2026 12:08:35 -0400
Subject: [PATCH 2/3] feat(make): adopt mise for tool version management

Add .tool-versions as the source of truth for runtime versions, with
Makefile bootstrap detection and CONTRIBUTING.md updates to recommend
mise to new contributors.

Changes:
- .tool-versions: template file with conventions documented inline.
  All entries commented out; projects derived from this template
  uncomment the lines they need.
- Makefile: HAS_TOOLVERSIONS detection, bootstrap step that runs
  mise install (or asdf as fallback) when .tool-versions is present,
  graceful degradation with instructional message when neither
  tool is installed.
- CONTRIBUTING.md: prerequisites updated to recommend mise as the
  primary version manager. Existing language-specific manifests
  (package.json engines, pyproject.toml, etc.) are kept but framed
  as derivative of .tool-versions.

Eliminates the duplication of version specs across CONTRIBUTING.md,
CI workflows, Dockerfiles, and language manifests. Bumping a tool
version becomes a single-file change.
---
 .tool-versions  | 55 +++++++++++++++++++++++++++++++++++++++++++++++++
 CONTRIBUTING.md | 28 +++++++++++++++----------
 Makefile        | 15 ++++++++++++++
 3 files changed, 87 insertions(+), 11 deletions(-)
 create mode 100644 .tool-versions

diff --git a/.tool-versions b/.tool-versions
new file mode 100644
index 0000000..74988ff
--- /dev/null
+++ b/.tool-versions
@@ -0,0 +1,55 @@
+# =============================================================================
+
+# Tool versions
+
+# =============================================================================
+
+# This file pins the exact versions of language runtimes and CLI tools used
+
+# by this project. Read by mise (https://mise.jdx.dev) and asdf
+
+# (https://asdf-vm.com), both of which support this format.
+
+#
+
+# Run `mise install` (or `asdf install`) from the repo root to install all
+
+# pinned versions. Your shell will automatically switch to these versions
+
+# when you cd into the repo.
+
+#
+
+# Template setup:
+
+# 1. Set the actual versions your project requires below.
+
+# 2. Delete any lines for tools the project doesn't use.
+
+# 3. Delete this comment block once setup is complete.
+
+#
+
+# Conventions:
+
+# - Pin to exact versions (3.12.7), not ranges (3.12, latest).
+
+# - Bumping a version is a deliberate PR with CI verification.
+
+# - The set of tools listed here is the SOURCE OF TRUTH for what this
+
+# project requires. CONTRIBUTING.md, Dockerfiles, and CI workflows
+
+# should align with these versions.
+
+# =============================================================================
+
+# python 3.12.7
+
+# nodejs 22.10.0
+
+# pnpm 9.12.3
+
+# rust 1.82.0
+
+# terraform 1.9.8
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 699120e..9e7395f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -173,18 +173,24 @@ Install the toolchain for whichever languages this project uses:
 - **Git** — current version
 - **Make** — for the standard task runner
 - **Docker** — for containerized builds and local services
+- **mise** _(recommended)_ — manages language runtime versions per project via
+  [`.tool-versions`](https://mise.jdx.dev/configuration.html#tool-versions).
+  Install with `brew install mise` or `curl https://mise.run | sh`. After
+  installation, run `mise install` from the repo root to install the exact
+  versions this project requires. [`asdf`](https://asdf-vm.com) is a
+  supported alternative; both read the same file.
 - **pre-commit** — for git hooks (`pip install pre-commit` or `brew install pre-commit`)
-- **Node.js** + **pnpm** — if the project includes TypeScript/JavaScript
-- **Python** + **uv** — if the project includes Python
-- **Rust** + **cargo** — if the project includes Rust
-- **Terraform** — if the project includes infrastructure code
-
-Project-specific tool versions are pinned in:
-
-- `.tool-versions` (asdf / mise) if present
-- `package.json` `engines` field for Node
-- `pyproject.toml` `requires-python` for Python
-- `rust-toolchain.toml` for Rust
+- **Node.js** + **pnpm** — if the project includes TypeScript/JavaScript _(installed automatically by mise)_
+- **Python** + **uv** — if the project includes Python _(Python installed automatically by mise; install uv via `pip install uv` or `brew install uv`)_
+- **Rust** + **cargo** — if the project includes Rust _(installed automatically by mise)_
+- **Terraform** — if the project includes infrastructure code _(installed automatically by mise)_
+
+The source of truth for tool versions is **`.tool-versions`** at the repo
+root. Run `mise install` to align your local environment with the versions
+this project requires. Language-specific manifests
+(`package.json` `engines`, `pyproject.toml` `requires-python`,
+`rust-toolchain.toml`) should align with `.tool-versions` and are kept in
+sync as part of any version bump.
 
 ### Bootstrap
 
diff --git a/Makefile b/Makefile
index f168495..c036b1a 100644
--- a/Makefile
+++ b/Makefile
@@ -15,6 +15,7 @@ HAS_RUST   := $(shell test -f Cargo.toml && echo 1)
 HAS_TF     := $(shell find . -maxdepth 3 -name '*.tf' -not -path './.terraform/*' -print -quit 2>/dev/null)
 HAS_DOCKER := $(shell test -f Dockerfile -o -f docker-compose.yml -o -f compose.yml && echo 1)
 HAS_TILT   := $(shell test -f Tiltfile && echo 1)
+HAS_TOOLVERSIONS := $(shell test -f .tool-versions && echo 1)
 
 # Pick the JS package manager: pnpm preferred, fall back to npm
 ifdef HAS_PNPM
@@ -63,6 +64,19 @@ endif
 	@echo "==> Installing pre-commit hooks..."
 	@command -v pre-commit >/dev/null 2>&1 && pre-commit install || echo "pre-commit not installed; skipping"
 	@echo "==> Bootstrap complete."
+ifdef HAS_TOOLVERSIONS
+	@if command -v mise >/dev/null 2>&1; then \
+		echo "==> Installing tool versions (mise)..."; \
+		mise install; \
+	elif command -v asdf >/dev/null 2>&1; then \
+		echo "==> Installing tool versions (asdf)..."; \
+		asdf install; \
+	else \
+		echo "==> .tool-versions present but neither mise nor asdf is installed."; \
+		echo "    Install mise (https://mise.jdx.dev) for automatic version management,"; \
+		echo "    or ensure your local toolchain matches the versions in .tool-versions."; \
+	fi
+endif
 
 .PHONY: install
 install: bootstrap ## Alias for bootstrap
@@ -401,3 +415,4 @@ detect: ## Show what languages and tools are detected
 	@echo "Terraform (*.tf):            $(if $(HAS_TF),yes,no)"
 	@echo "Docker (Dockerfile/compose): $(if $(HAS_DOCKER),yes,no)"
 	@echo "Tilt (Tiltfile):             $(if $(HAS_TILT),yes,no)"
+	@echo "Tool versions (.tool-versions): $(if $(HAS_TOOLVERSIONS),yes,no)"

From 9d830691f1a0937ce54814cfeebb48ebd212dfb2 Mon Sep 17 00:00:00 2001
From: Jason Anton <jason@stoopid.email>
Date: Sat, 2 May 2026 12:12:51 -0400
Subject: [PATCH 3/3] fix(ci): split commit lint into separate workflows with
 correct permissions

The previous commitlint.yml combined PR title validation and commit
message validation in a single workflow under pull_request_target.
This caused two problems:

1. The amannn/action-semantic-pull-request action failed with
   "Resource not accessible by integration" because the workflow
   was missing the statuses: write permission required to post
   check results back to the PR.

2. The commits job ran under pull_request_target while explicitly
   checking out the PR head SHA. This is the pwn-request pattern:
   PR-author-supplied code (commitlint config, npm install scripts)
   would execute with the workflow's elevated permissions, allowing
   a malicious PR to compromise the repo.

Splits the validation into two workflows with appropriate triggers
and permission scopes:

- pr-title.yml: pull_request_target, reads PR metadata only, posts
  status check. Safe because the action never executes PR code.
- commit-lint.yml: pull_request, checks out PR code in its own
  reduced-permission context. The check result is the workflow
  exit code, no API write needed.

Branch protection rules should be updated to require both checks:
"PR Title Lint / PR title" and "Commit Lint / Commit messages".
The old "Commit Lint / PR title" and "Commit Lint / Commit messages"
check names will no longer exist.
---
 .github/workflows/commit-lint.yml | 50 +++++++++++++++++
 .github/workflows/commitlint.yml  | 92 -------------------------------
 .github/workflows/pr-title.yml    | 42 ++++++++++++++
 3 files changed, 92 insertions(+), 92 deletions(-)
 create mode 100644 .github/workflows/commit-lint.yml
 delete mode 100644 .github/workflows/commitlint.yml
 create mode 100644 .github/workflows/pr-title.yml

diff --git a/.github/workflows/commit-lint.yml b/.github/workflows/commit-lint.yml
new file mode 100644
index 0000000..3e896a6
--- /dev/null
+++ b/.github/workflows/commit-lint.yml
@@ -0,0 +1,50 @@
+name: Commit Lint
+
+on:
+  pull_request:
+    branches: [ main ]
+    types: [ opened, reopened, synchronize ]
+
+permissions:
+  contents: read
+
+jobs:
+  commits:
+    name: Commit messages
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install commitlint
+        run: |
+          npm install --no-save \
+            @commitlint/cli \
+            @commitlint/config-conventional
+
+      - name: Write commitlint config
+        run: |
+          cat > commitlint.config.cjs <<'EOF'
+          module.exports = {
+            extends: ['@commitlint/config-conventional'],
+            rules: {
+              'subject-case': [2, 'never', ['upper-case', 'pascal-case', 'start-case']],
+              'header-max-length': [2, 'always', 100],
+              'body-max-line-length': [2, 'always', 100],
+              'footer-max-line-length': [2, 'always', 100],
+            },
+          };
+          EOF
+
+      - name: Lint commits in PR range
+        run: |
+          npx commitlint \
+            --from "${{ github.event.pull_request.base.sha }}" \
+            --to "${{ github.event.pull_request.head.sha }}" \
+            --verbose
diff --git a/.github/workflows/commitlint.yml b/.github/workflows/commitlint.yml
deleted file mode 100644
index a10eb47..0000000
--- a/.github/workflows/commitlint.yml
+++ /dev/null
@@ -1,92 +0,0 @@
-name: Commit Lint
-
-on:
-  pull_request_target:
-    branches: [ main ]
-    types: [ opened, edited, reopened, synchronize ]
-
-permissions:
-  contents: read
-  pull-requests: write
-
-jobs:
-  # ===========================================================================
-  # Validate the PR title (becomes the squash-merge commit message)
-  # ===========================================================================
-  pr-title:
-    name: PR title
-    runs-on: ubuntu-latest
-    permissions:
-      pull-requests: write
-    steps:
-      - name: Validate PR title follows Conventional Commits
-        uses: amannn/action-semantic-pull-request@v5.5.3
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          types: |
-            feat
-            fix
-            docs
-            style
-            refactor
-            perf
-            test
-            build
-            ci
-            chore
-            revert
-          requireScope: false
-          subjectPattern: ^(?![A-Z]).+$
-          subjectPatternError: |
-            The subject "{subject}" found in the PR title "{title}"
-            didn't match the configured pattern. The subject must start with
-            a lowercase character.
-          wip: true
-          validateSingleCommit: false
-
-  # ===========================================================================
-  # Validate every commit on the PR branch
-  # ===========================================================================
-  commits:
-    name: Commit messages
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          # Under pull_request_target, the default ref is the base branch.
-          # Explicitly check out the PR head so we can validate its commits.
-          ref: ${{ github.event.pull_request.head.sha }}
-          fetch-depth: 0
-
-      - name: Set up Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: "20"
-
-      - name: Install commitlint
-        run: |
-          npm install --no-save \
-            @commitlint/cli \
-            @commitlint/config-conventional
-
-      - name: Write commitlint config
-        run: |
-          cat > commitlint.config.cjs <<'EOF'
-          module.exports = {
-            extends: ['@commitlint/config-conventional'],
-            rules: {
-              'subject-case': [2, 'never', ['upper-case', 'pascal-case', 'start-case']],
-              'header-max-length': [2, 'always', 100],
-              'body-max-line-length': [2, 'always', 100],
-              'footer-max-line-length': [2, 'always', 100],
-            },
-          };
-          EOF
-
-      - name: Lint commits in PR range
-        run: |
-          npx commitlint \
-            --from "${{ github.event.pull_request.base.sha }}" \
-            --to "${{ github.event.pull_request.head.sha }}" \
-            --verbose
diff --git a/.github/workflows/pr-title.yml b/.github/workflows/pr-title.yml
new file mode 100644
index 0000000..d5125e8
--- /dev/null
+++ b/.github/workflows/pr-title.yml
@@ -0,0 +1,42 @@
+name: PR Title Lint
+
+on:
+  pull_request_target:
+    branches: [ main ]
+    types: [ opened, edited, reopened, synchronize ]
+
+permissions:
+  contents: read
+  pull-requests: read
+  statuses: write
+
+jobs:
+  pr-title:
+    name: PR title
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate PR title follows Conventional Commits
+        uses: amannn/action-semantic-pull-request@v5.5.3
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          types: |
+            feat
+            fix
+            docs
+            style
+            refactor
+            perf
+            test
+            build
+            ci
+            chore
+            revert
+          requireScope: false
+          subjectPattern: ^(?![A-Z]).+$
+          subjectPatternError: |
+            The subject "{subject}" found in the PR title "{title}"
+            didn't match the configured pattern. The subject must start with
+            a lowercase character.
+          wip: true
+          validateSingleCommit: false