chore(release): promote dev to main

.github/dependabot.yml

@@ -30,7 +30,7 @@ updates:
     commit-message:
       prefix: "ci"
 
-  # The Python dev tools (ruff, mypy, detect-secrets, coverage, jsonschema, skills-ref, uv, actionlint-py, zizmor,
+  # The Python dev tools (ruff, mypy, detect-secrets, coverage, jsonschema, skills-ref, typos, uv, zizmor,
   # check-jsonschema), locked in uv.lock. The
   # Makefile, lefthook.yml and the workflows read each version from dev/tools/pyproject.toml.
   - package-ecosystem: uv
@@ -69,6 +69,25 @@ updates:
     commit-message:
       prefix: "build"
 
+  # The Go dev tools, each pinned as a Go `tool` in its own module with its dependencies: osv-scanner (the dependency
+  # audit in `make security`) and actionlint (`make workflow-lint`). The Makefile runs them with `go -C <dir> tool`.
+  - package-ecosystem: gomod
+    directories: ["/dev/tools/osv", "/dev/tools/actionlint"]
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7
+    open-pull-requests-limit: 0
+    ignore:
+      - dependency-name: "*"
+        update-types: ["version-update:semver-major"]
+    groups:
+      security-fixes:
+        applies-to: security-updates
+        patterns: ["*"]
+    commit-message:
+      prefix: "build"
+
   # Data, not dependencies: the greenfield template and the engine's test fixtures. No pull request, ever.
   - package-ecosystem: npm
     directories: ["/greenfield/templates", "/audit/engine/tests/fixtures/**"]

.github/pull_request_template.md

@@ -12,6 +12,7 @@
 - [ ] The base branch is `dev`, and the head is a work branch named `<type>/<topic>` that started from `dev`
 - [ ] `make check` and `make security` pass
 - [ ] `make docs-lint` passes when Markdown changed; Mermaid blocks validated (`make docs-mermaid FILES=<file.md>`)
+- [ ] `make docs-prose FILES=<file.md>` run on changed Markdown, and its warnings on the changed lines fixed (advisory)
 - [ ] New code has tests; a new engine check has a fixture that fails exactly that check
 - [ ] Documentation and decision records updated in the same change when an interface, behaviour or decision changed
 - [ ] Commits follow Conventional Commits, one logical change each, with a `Roadmap-Step:` trailer when a track applies

.github/rulesets/dev-protection.json

@@ -35,7 +35,7 @@
     {
       "type": "required_status_checks",
       "parameters": {
-        "strict_required_status_checks_policy": true,
+        "strict_required_status_checks_policy": false,
         "do_not_enforce_on_create": false,
         "required_status_checks": [
           {
@@ -44,6 +44,18 @@
           }
         ]
       }
+    },
+    {
+      "type": "merge_queue",
+      "parameters": {
+        "check_response_timeout_minutes": 30,
+        "grouping_strategy": "ALLGREEN",
+        "max_entries_to_build": 5,
+        "max_entries_to_merge": 5,
+        "merge_method": "MERGE",
+        "min_entries_to_merge": 1,
+        "min_entries_to_merge_wait_minutes": 5
+      }
     }
   ]
 }

.github/workflows/ci.yml

@@ -1,16 +1,26 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 # Copyright (C) 2026 K. C. Ramakrishna
 #
-# CI runs the same verbs a human or agent runs locally (see the Makefile): `make check` and `make security`.
+# CI runs the same verbs a human or agent runs locally (see the Makefile): `make check`, split into jobs that run at
+# once, and `make security`.
+# `make security` needs the network: its dependency audit (osv-scanner) queries osv.dev.
 # Python 3.11 is the supported minimum and 3.14 the newest release (Q8); Windows is supported through WSL only.
+# CI runs on Linux only for now, to keep the wait per pull request short. Restoring macOS and adding Windows is
+# tracked in issue #82.
 # The `docs` job runs `make docs-lint` and the Mermaid check when a Markdown file changed; it needs Node, so it
-# stays out of `make check` and the matrix.
-# It runs on every pull request and on every push to the two protected branches, `dev` and `main`
+# stays out of `make check` and the matrix. It also annotates the prose of the changed files, which never fails.
+# It runs on every pull request, on every merge group of the `dev` merge queue, and on every push to the two
+# protected branches, `dev` and `main`
 # (docs/reference/branch-protection.md).
 name: CI
 
 on:
   pull_request:
+  # The merge queue on `dev` tests each pull request merged onto the latest `dev` before it lands. CI Gate must
+  # report here too, or the queue waits until its timeout. Each group has its own ref, so the concurrency group
+  # below never cancels one group for another.
+  merge_group:
+    types: [checks_requested]
   push:
     branches: [main, dev]
 
@@ -22,13 +32,35 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  check:
-    name: check (${{ matrix.os }}, Python ${{ matrix.python }})
-    runs-on: ${{ matrix.os }}
+  # `make check` split into jobs that run at once; dev/tests/test_ci_parity.py fails when a step of `check` or a
+  # suite of `test` has no job here. The steps that are cheap share one job, because each job pays about 15 s of
+  # setup. Python 3.11 runs every step; Python 3.14 runs the runtime code: the suites and the schema cross-check.
+  static:
+    name: static (format, typecheck, rules, recipe lint, masters, workflow lint, spell)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version-file: .python-version
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          version-file: dev/tools/pyproject.toml
+      # Go builds actionlint (`make workflow-lint`) from dev/tools/actionlint/go.mod, through the Go module proxy.
+      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
+        with:
+          go-version-file: dev/tools/actionlint/go.mod
+          cache-dependency-path: dev/tools/actionlint/go.sum
+      - run: make format-check typecheck verify-rules recipe-lint masters-check workflow-lint spell
+
+  crosscheck:
+    name: crosscheck (Python ${{ matrix.python }})
+    runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-latest]
         python: ["3.11", "3.14"]
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -40,27 +72,90 @@ jobs:
       - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
         with:
           version-file: dev/tools/pyproject.toml
-      - run: make check
+      - run: make crosscheck
 
-  security:
-    name: security
+  # The suites under coverage.py, in parts that run at once (`make coverage-part`; TEST_SHARDS, SHARDED_SUITES and
+  # COVERAGE_PART_<i> in the Makefile). Part <i> runs shard <i> of the engine's and the audit tools' suites, plus
+  # the implement tools in part 1. dev/tests/test_ci_parity.py checks that the matrix lists 1 to TEST_SHARDS. Each
+  # part's data files go to the `coverage` job, which combines them all.
+  test-coverage:
+    name: test (part ${{ matrix.shard }}, Python 3.11, coverage)
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2]
+    env:
+      SHARD: ${{ matrix.shard }}
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      # The minimum Python the repository pins (.python-version); the `check` matrix above spans 3.11 and 3.14.
       - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
         with:
           python-version-file: .python-version
       - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
         with:
           version-file: dev/tools/pyproject.toml
-      - run: make security
+      - run: make coverage-part
+        env:
+          CI: "true"
+      # The data files' names start with a dot, so they are hidden files to upload-artifact. coverage-combine fails
+      # when one of them is missing.
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: coverage-part-${{ matrix.shard }}
+          path: dev/dist/coverage/.coverage.*
+          include-hidden-files: true
+          if-no-files-found: error
+          retention-days: 1
 
-  # The engine's and the recipe tools' suites under coverage.py; fails below the floor in .coveragerc.
+  # The dev checks' suite. coverage.py does not measure dev/ (.coveragerc), so this job runs it plainly.
+  test-dev:
+    name: test-dev (Python 3.11)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version-file: .python-version
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          version-file: dev/tools/pyproject.toml
+      - run: make test-dev
+
+  # Every suite on the newest Python, in parts with one shard of each sharded suite (`make test-part`;
+  # TEST_PART_<i> in the Makefile). Each part runs its targets at once, as `make test` runs its suites, so this job also proves the
+  # parallel run on every pull request. The nightly workflow runs the unsharded `make test`.
+  test-py314:
+    name: test (part ${{ matrix.shard }}, Python 3.14)
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2]
+    env:
+      SHARD: ${{ matrix.shard }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: "3.14"
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          version-file: dev/tools/pyproject.toml
+      - run: make test-part
+
+  # Combines the suites' data files and fails below the floor in .coveragerc (`fail_under`). `coverage-combine
+  # SHARDED=1` fails when a suite's or an engine shard's data file is missing, so a lost upload cannot pass with a
+  # partial total.
   coverage:
     name: coverage
+    needs: [test-coverage]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -72,9 +167,44 @@ jobs:
       - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
         with:
           version-file: dev/tools/pyproject.toml
-      - run: make coverage
-        env:
-          CI: "true"
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          pattern: coverage-*
+          merge-multiple: true
+          path: dev/dist/coverage
+      - run: make coverage-combine SHARDED=1
+
+  # `make security` in its two parts, as two jobs: the secrets scan needs Python and uv, the dependency audit needs
+  # Go. dev/tests/test_ci_parity.py fails when a part of `security` has no job here.
+  security-secrets:
+    name: security-secrets (detect-secrets)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      # The minimum Python the repository pins (.python-version).
+      - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version-file: .python-version
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          version-file: dev/tools/pyproject.toml
+      - run: make security-secrets
+
+  security-deps:
+    name: security-deps (osv-scanner)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      # Go builds osv-scanner, the dependency audit in `make security`, from dev/tools/osv/go.mod.
+      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
+        with:
+          go-version-file: dev/tools/osv/go.mod
+          cache-dependency-path: dev/tools/osv/go.sum
+      - run: make security-deps
 
   # The engine on this repository against the committed ratchet (.audit-baseline.json): exit 2 when a finding appears
   # that the baseline did not have. Read-only; the report stays under dist/self-audit/. Linux only.
@@ -103,7 +233,7 @@ jobs:
       - name: List changed Markdown
         id: changed
         env:
-          BASE: ${{ github.event.pull_request.base.sha || github.event.before }}
+          BASE: ${{ github.event.pull_request.base.sha || github.event.merge_group.base_sha || github.event.before }}
           HEAD_SHA: ${{ github.sha }}
         run: |
           list="$RUNNER_TEMP/changed-md.txt"
@@ -115,6 +245,13 @@ jobs:
           echo "Changed Markdown:"
           cat "$list"
           if [[ -s "$list" ]]; then echo "any=true" >> "$GITHUB_OUTPUT"; else echo "any=false" >> "$GITHUB_OUTPUT"; fi
+      # The prose check (docs/COMMUNICATION_RULES.md) is advisory: it annotates the changed Markdown with warnings and
+      # notices and always exits 0. Fixtures and test data are skipped, as in `make docs-prose`.
+      - if: steps.changed.outputs.any == 'true'
+        name: Annotate prose in changed Markdown
+        run: |
+          { grep -v -E '(^|/)(fixtures|testdata)/' "$RUNNER_TEMP/changed-md.txt" || true; } \
+            | xargs -r -d '\n' python3 dev/prose_check.py --format github
       - if: steps.changed.outputs.any == 'true'
         uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
         with:
@@ -132,8 +269,9 @@ jobs:
         name: Validate Mermaid blocks in changed Markdown
         run: xargs -d '\n' -a "$RUNNER_TEMP/changed-md.txt" python3 dev/mermaid_check.py --no-sandbox
 
-  # Every commit subject that the pull request (or the push) adds must follow Conventional Commits. The rule is in
-  # dev/commit_lint.py, which the lefthook commit-msg hook also runs. Merge commits are skipped.
+  # Every commit subject that the pull request (or the merge group, or the push) adds must follow Conventional
+  # Commits. The rule is in dev/commit_lint.py, which the lefthook commit-msg hook also runs. Merge commits are
+  # skipped.
   commits:
     name: commits
     runs-on: ubuntu-latest
@@ -144,59 +282,33 @@ jobs:
           fetch-depth: 0
       - name: Check the commit subjects
         env:
-          BASE: ${{ github.event.pull_request.base.sha || github.event.before }}
-          HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+          BASE: ${{ github.event.pull_request.base.sha || github.event.merge_group.base_sha || github.event.before }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha || github.event.merge_group.head_sha || github.sha }}
         run: |
           if [[ -z "$BASE" || "$BASE" =~ ^0+$ ]] || ! git cat-file -e "$BASE^{commit}" 2>/dev/null; then
             echo "No base commit to compare with (a new branch); nothing to check."
             exit 0
           fi
           python3 dev/commit_lint.py --range "$BASE..$HEAD_SHA"
 
-  # One required check that stands for the whole matrix, so adding or renaming a `check` leg (a Python
-  # version, an OS) never also requires a branch-protection edit.
+  # One required check that stands for every job above, so adding, splitting or renaming a job (a suite, a Python
+  # version, an OS) never also requires a branch-protection edit. It reads every result in `needs`, so a job listed
+  # there cannot be left unchecked.
   ci-gate:
     name: CI Gate
-    needs: [check, security, coverage, self-audit, docs, commits]
+    needs: [static, crosscheck, test-coverage, test-dev, test-py314, coverage, security-secrets, security-deps, self-audit, docs, commits]
     if: always()
     runs-on: ubuntu-latest
     steps:
-      - name: Require check, security, coverage, self-audit, docs and commits to have succeeded
+      - name: Require every needed job to have succeeded
+        # The results come in through env, never expanded into the script (zizmor: template-injection).
+        env:
+          NEEDS: ${{ toJSON(needs) }}
         run: |
-          check="${{ needs.check.result }}"
-          security="${{ needs.security.result }}"
-          coverage="${{ needs.coverage.result }}"
-          self_audit="${{ needs.self-audit.result }}"
-          docs="${{ needs.docs.result }}"
-          commits="${{ needs.commits.result }}"
-          echo "check: $check"
-          echo "security: $security"
-          echo "coverage: $coverage"
-          echo "self-audit: $self_audit"
-          echo "docs: $docs"
-          echo "commits: $commits"
-          if [[ "$check" != "success" ]]; then
-            echo "::error::check did not pass"
-            exit 1
-          fi
-          if [[ "$security" != "success" ]]; then
-            echo "::error::security did not pass"
-            exit 1
-          fi
-          if [[ "$coverage" != "success" ]]; then
-            echo "::error::coverage did not pass"
-            exit 1
-          fi
-          if [[ "$self_audit" != "success" ]]; then
-            echo "::error::self-audit did not pass"
-            exit 1
-          fi
-          if [[ "$docs" != "success" ]]; then
-            echo "::error::docs did not pass"
-            exit 1
-          fi
-          if [[ "$commits" != "success" ]]; then
-            echo "::error::commits did not pass"
+          jq -r 'to_entries[] | "\(.key): \(.value.result)"' <<< "$NEEDS"
+          failed=$(jq -r '[to_entries[] | select(.value.result != "success") | .key] | join(", ")' <<< "$NEEDS")
+          if [[ -n "$failed" ]]; then
+            echo "::error::did not pass: $failed"
             exit 1
           fi
           echo "CI Gate passed."