docs: add docs/ scaffolding with ADR and runbook conventions

.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

.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

.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

.gitignore

@@ -367,4 +367,4 @@ scratch/
 NOTES.local.md
 TODO.local.md
 *.local
-*.local.*
+*.local.*

.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

.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

.vscode/extensions.json

@@ -35,4 +35,4 @@
     "ms-azuretools.vscode-docker",
     "ms-azuretools.vscode-containers"
   ]
-}
+}

.vscode/settings.json

@@ -251,4 +251,4 @@
   "git.suggestSmartCommit": false,
 
   "terminal.integrated.scrollback": 10000
-}
+}

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>.