Merge pull request 'Prepare release 2.2.0: changelog section and guides at @v2' (#216) from release-2.2.0 into main

The unreleased entries become the 2.2.0 section (the English-comments workflow
and the WireGuard and Tailscale actions). The guides no longer say to call
@main until a release: the examples use @v2, and the VPN guides state that the
actions are released but have not run on a real tunnel yet.

Refs #188
Refs #191
Refs #207

.editorconfig

@@ -5,3 +5,8 @@ root = true
 end_of_line = lf
 charset = utf-8
 insert_final_newline = true
+
+[*.sh]
+indent_style = space
+indent_size = 2
+switch_case_indent = true

.gitea/scoped_workflows/publish-wiki.yml

@@ -1,48 +0,0 @@
-name: Publish wiki
-
-# DEPRECATED (ADR-0009, MIL-008): repositories publish their wiki by calling
-# the reusable workflow publish-wiki-pages.yml. This scoped workflow stays
-# until every repository that has wiki/.publish has migrated; it is then
-# removed in a later major release.
-
-# Shared through scoped delivery: it runs in every repository of an
-# organization, but writes only where the repository has opted in with
-# wiki/.publish (ADR-0004). TOKEN_FOR_GITEA_WIKI is read from the organization
-# secrets; there is no fallback to the read-only sync token. The script is a
-# file of TirSystem/github-action (tools/publish_wiki.py), fetched with a
-# second checkout so that it is readable, lintable and tested as a file
-# (MIL-004 task 6).
-on:
-  push:
-    branches: [ main ]
-    paths:
-      - "wiki/**"
-  workflow_dispatch:
-
-concurrency:
-  group: publish-wiki
-  cancel-in-progress: false
-
-jobs:
-  publish-wiki:
-    permissions:
-      contents: read
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    steps:
-      - name: Check out the repository
-        uses: actions/checkout@v4.2.2
-
-      - name: Fetch the shared script
-        uses: actions/checkout@v4.2.2
-        with:
-          repository: TirSystem/github-action
-          ref: v1
-          path: shared-scripts
-
-      - name: Publish the pages to the wiki
-        env:
-          GITEA_API_URL: ${{ gitea.api_url }}
-          SOURCE_REPOSITORY: ${{ gitea.repository }}
-          WIKI_CREDENTIALS: ${{ secrets.TOKEN_FOR_GITEA_WIKI }}
-        run: python3 shared-scripts/tools/publish_wiki.py

.gitea/workflows/code-metrics.yml

@@ -0,0 +1,95 @@
+name: Code metrics
+
+# Reusable workflow (ADR-0010). A repository calls it with
+#
+#   on:
+#     push:
+#       branches: [main]
+#   jobs:
+#     metrics:
+#       uses: TirSystem/github-action/.gitea/workflows/code-metrics.yml@v2
+#       permissions:
+#         contents: write
+#
+# It counts the code files and the lines of code of the repository (comment
+# and blank lines are not counted), reads an optional Cobertura XML coverage
+# report (an artifact of an earlier job of the caller, or a file of the
+# repository) and commits three SVG badges to a branch of the calling
+# repository.
+# It runs no test, needs no secret and writes only the badges branch.
+on:
+  workflow_call:
+    inputs:
+      working-directory:
+        description: "Directory, relative to the repository root, whose code is counted"
+        type: string
+        default: "."
+      exclude:
+        description: "Comma list of patterns of files and directories that are not counted, in addition to the defaults of ADR-0010"
+        type: string
+        default: ""
+      coverage-report:
+        description: "Path, relative to the repository root, of a Cobertura XML coverage report; empty writes no coverage badge"
+        type: string
+        default: ""
+      coverage-artifact:
+        description: "Name of an artifact, uploaded by an earlier job of the same run, that holds the coverage report; empty reads coverage-report from the checkout"
+        type: string
+        default: ""
+      coverage-warn:
+        description: "Coverage in percent below which the coverage badge is red"
+        type: string
+        default: "60"
+      coverage-good:
+        description: "Coverage in percent from which the coverage badge is green"
+        type: string
+        default: "80"
+      badges-branch:
+        description: "Branch that holds the badge files; it is created when it does not exist"
+        type: string
+        default: "badges"
+      tools-ref:
+        description: "Tag or branch of TirSystem/github-action whose tools/ files are run; pin it to the exact tag together with the workflow"
+        type: string
+        default: "v2"
+
+jobs:
+  code-metrics:
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    env:
+      WORKING_DIRECTORY: ${{ inputs.working-directory }}
+      EXCLUDE: ${{ inputs.exclude }}
+      COVERAGE_REPORT: ${{ inputs.coverage-report }}
+      COVERAGE_ARTIFACT: ${{ inputs.coverage-artifact }}
+      COVERAGE_WARN: ${{ inputs.coverage-warn }}
+      COVERAGE_GOOD: ${{ inputs.coverage-good }}
+      BADGES_BRANCH: ${{ inputs.badges-branch }}
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@v4.2.2
+
+      - name: Fetch the shared scripts
+        uses: actions/checkout@v4.2.2
+        with:
+          repository: TirSystem/github-action
+          ref: ${{ inputs.tools-ref }}
+          path: shared-scripts
+
+      - name: Validate the inputs
+        run: bash shared-scripts/tools/code-metrics.sh validate
+
+      - name: Download the coverage report
+        if: ${{ inputs.coverage-artifact != '' }}
+        uses: actions/download-artifact@v4.1.8
+        with:
+          name: ${{ inputs.coverage-artifact }}
+          path: coverage-artifact
+
+      - name: Count the code and write the badges
+        run: bash shared-scripts/tools/code-metrics.sh measure
+
+      - name: Publish the badges
+        run: bash shared-scripts/tools/code-metrics.sh publish

.gitea/workflows/english-comments.yml

@@ -0,0 +1,117 @@
+name: English comments
+
+# Reusable workflow (MIL-013, ADR-0012). A repository calls it on its pull
+# requests with
+#
+#   on:
+#     pull_request:
+#   jobs:
+#     english-comments:
+#       uses: TirSystem/github-action/.gitea/workflows/english-comments.yml@v2
+#
+# It reads the comments and docstrings that the pull request adds, judges their
+# language, fails the run when one is not English and writes one comment on the
+# pull request that mentions the author. It changes no file. Mark the check as
+# required in the branch protection of the target branch to block the merge
+# (the workflow cannot do that).
+on:
+  workflow_call:
+    inputs:
+      scope:
+        description: "changed: the comments on the lines the pull request adds; all: every tracked file"
+        type: string
+        default: "changed"
+      exclude:
+        description: "Comma list of file name or path patterns that are not checked (* and ** are wildcards)"
+        type: string
+        default: ""
+      allowed-words-file:
+        description: "File of the repository with words that are never judged, one per line"
+        type: string
+        default: ""
+      threshold:
+        description: "Probability, above 0 and at most 1, from which a comment counts as not English (ADR-0012)"
+        type: string
+        default: "0.6"
+      min-words:
+        description: "A comment with fewer words is not judged (ADR-0012)"
+        type: string
+        default: "3"
+      langid-version:
+        description: "Version of the langid package"
+        type: string
+        default: "1.1.6"
+      numpy-version:
+        description: "Version of numpy, which langid needs"
+        type: string
+        default: "2.1.3"
+      tools-ref:
+        description: "Tag or branch of TirSystem/github-action whose tools/english_comments.py is run; pin it to the exact tag together with the workflow"
+        type: string
+        default: "v2"
+    secrets:
+      REPORT_TOKEN:
+        description: "Optional Gitea token that may comment on pull requests; without it the token of the run is used"
+        required: false
+
+jobs:
+  english-comments:
+    permissions:
+      contents: read
+      issues: write
+      pull-requests: write
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      SCOPE: ${{ inputs.scope }}
+      EXCLUDE: ${{ inputs.exclude }}
+      ALLOWED_WORDS: ${{ inputs.allowed-words-file }}
+      THRESHOLD: ${{ inputs.threshold }}
+      MIN_WORDS: ${{ inputs.min-words }}
+      LANGID_VERSION: ${{ inputs.langid-version }}
+      NUMPY_VERSION: ${{ inputs.numpy-version }}
+      BASE_REF: ${{ gitea.base_ref }}
+      FINDINGS_FILE: /tmp/english-comments-findings.json
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@v4.2.2
+        with:
+          fetch-depth: 0
+
+      - name: Fetch the shared scripts
+        uses: actions/checkout@v4.2.2
+        with:
+          repository: TirSystem/github-action
+          ref: ${{ inputs.tools-ref }}
+          path: shared-scripts
+
+      - name: Install the language detector
+        run: |
+          python3 -m venv /tmp/english-comments-venv
+          /tmp/english-comments-venv/bin/pip install --quiet "langid==${LANGID_VERSION}" "numpy==${NUMPY_VERSION}"
+
+      - name: Check the comments
+        id: check
+        continue-on-error: true
+        run: >-
+          /tmp/english-comments-venv/bin/python shared-scripts/tools/english_comments.py check
+          --scope "$SCOPE" --base "origin/$BASE_REF" --exclude "shared-scripts/**,$EXCLUDE"
+          --allowed-words "$ALLOWED_WORDS" --threshold "$THRESHOLD" --min-words "$MIN_WORDS"
+          --output "$FINDINGS_FILE"
+
+      - name: Tell the author
+        # in a called workflow gitea.event_name is workflow_call, so ask for the pull request itself
+        if: ${{ always() && gitea.event.pull_request.number != '' }}
+        continue-on-error: true
+        env:
+          GITEA_API_URL: ${{ gitea.api_url }}
+          SOURCE_REPOSITORY: ${{ gitea.repository }}
+          PR_NUMBER: ${{ gitea.event.pull_request.number }}
+          PR_AUTHOR: ${{ gitea.event.pull_request.user.login }}
+          RUN_URL: ${{ gitea.server_url }}/${{ gitea.repository }}/actions/runs/${{ gitea.run_id }}
+          REPORT_TOKEN: ${{ secrets.REPORT_TOKEN || gitea.token }}
+        run: python3 shared-scripts/tools/english_comments_report.py
+
+      - name: Fail the run when a comment is not in English
+        if: ${{ steps.check.outcome == 'failure' }}
+        run: exit 1

.gitea/workflows/publish-wiki-pages.yml

@@ -31,7 +31,7 @@ on:
       tools-ref:
         description: "Tag or branch of TirSystem/github-action whose tools/publish_wiki.py is run; pin it to the exact tag together with the workflow"
         type: string
-        default: "v1"
+        default: "v2"
     secrets:
       TOKEN_FOR_GITEA_WIKI:
         description: "Gitea token with write access to the wiki of the calling repository"

.gitea/workflows/quality-checks-cpp.yml

@@ -36,7 +36,7 @@ on:
       tools-ref:
         description: "Tag or branch of TirSystem/github-action whose tools/quality-checks-cpp.sh is run; pin it to the exact tag together with the workflow"
         type: string
-        default: "v1"
+        default: "v2"
 
 jobs:
   quality-checks-cpp:

.gitea/workflows/quality-checks-csharp.yml

@@ -27,7 +27,7 @@ on:
       tools-ref:
         description: "Tag or branch of TirSystem/github-action whose tools/quality-checks-csharp.sh is run; pin it to the exact tag together with the workflow"
         type: string
-        default: "v1"
+        default: "v2"
 
 jobs:
   quality-checks-csharp:

.gitea/workflows/quality-checks.yml

@@ -38,7 +38,7 @@ on:
       tools-ref:
         description: "Tag or branch of TirSystem/github-action whose tools/quality-checks.sh is run; pin it to the exact tag together with the workflow"
         type: string
-        default: "v1"
+        default: "v2"
 
 jobs:
   quality-checks:

.gitea/workflows/validate-workflows.yml

@@ -26,3 +26,9 @@ jobs:
 
       - name: Check the coverage of the tools
         run: .venv/bin/python -m coverage report
+
+      - name: Lint the shell scripts of the actions
+        env:
+          SHELLCHECK: .venv/bin/shellcheck
+          SHFMT: .venv/bin/shfmt
+        run: bash tools/lint-action-scripts.sh actions

CHANGELOG.md

@@ -20,6 +20,67 @@ Each release lists its changes in these groups, in this order:
 
 ## [Unreleased]
 
+## [2.2.0] - 2026-10-21
+
+### Added
+
+- `english-comments.yml`, a reusable workflow that judges the language of the comments and docstrings a pull request adds, fails the run when one is not English and writes one comment on the pull request that mentions the author (ADR-0012), with the scripts `tools/english_comments.py` and `tools/english_comments_report.py`, the guide `guides/english-comments.md` and wiki pages in three languages. The scanner of `tools/count_loc.py` can return the text of the comments it finds.
+- `actions/connect-wireguard`, a composite action that brings a WireGuard tunnel up on a Gitea Actions runner for a deployment, with the guide `guides/vpn-wireguard.md`. Experimental.
+- `actions/connect-tailscale`, a composite action for Gitea Actions that joins a Tailscale network for a deployment (the Gitea counterpart of the marketplace action `tailscale/github-action`), with the guide `guides/vpn-tailscale.md`. Experimental.
+
+## [2.1.1] - 2026-10-14
+
+### Fixed
+
+- `code-metrics.yml` could not be called as documented. Its guide, header
+  comment and `tools-ref` default named `v1`, which has neither the workflow nor
+  `tools/code-metrics.sh`: a call at `@v1` created no run, and a call at `@v2`
+  with the defaults failed in "Validate the inputs" (exit 127). The default
+  `tools-ref` of `code-metrics.yml`, `quality-checks.yml`,
+  `quality-checks-cpp.yml`, `quality-checks-csharp.yml` and
+  `publish-wiki-pages.yml` is now the current major (`v2`), defined once in
+  `MAJOR_TAG`, and a test fails when a default differs from it or names a tag
+  without the script. The guides, README and wiki pages call
+  `code-metrics.yml` at `@v2`.
+
+## [2.1.0] - 2026-10-14
+
+### Added
+
+- The reusable workflow `code-metrics.yml` (ADR-0010, MIL-010). It counts the
+  code files and the lines of code (without comment and blank lines) of a
+  repository, reads a Cobertura XML coverage report that the caller uploads as an
+  artifact, and commits three SVG badges (code files, lines of code, coverage) to
+  a `badges` branch. It needs `contents: write` and no secret; the inputs are
+  `working-directory`, `exclude`, `coverage-report`, `coverage-artifact`,
+  `coverage-warn`, `coverage-good`, `badges-branch` and `tools-ref`. See
+  `guides/code-metrics.md`.
+
+## [2.0.0] - 2026-10-14
+
+### Breaking
+
+- The scoped workflow `publish-wiki.yml` and the `wiki/.publish` marker are
+  removed (ADR-0009, MIL-009). A repository publishes its wiki by calling the
+  reusable workflow `publish-wiki-pages.yml`; one that still has the marker no
+  longer publishes. The seven repositories that used the scoped workflow on
+  2026-10-13 have a caller (checked on 2026-10-14). A repository that has
+  `wiki/.publish` moves `wiki/` to `docs/wiki/`, copies
+  `templates/ci/publish-wiki.yml` of the SQA and QC framework (0.7.0 or later)
+  to `.gitea/workflows/publish-wiki.yml` and removes the marker.
+- `tools/publish_wiki.py` requires `WIKI_PRUNE` (`true` or `false`) and no longer
+  reads a marker; `WIKI_DIR` defaults to `docs/wiki`.
+
+### Changed
+
+- The README, the onboarding, troubleshooting and upgrading guides and the
+  wiki pages (English, Danish, Bahasa Malaysia) no longer describe the scoped
+  workflow or the marker.
+- ADR-0004 is `Superseded by ADR-0009`.
+- Callers of `quality-checks.yml`, `quality-checks-cpp.yml`,
+  `quality-checks-csharp.yml`, `release.yml` and `publish-wiki-pages.yml` need no
+  change; `v1` stays at 1.2.2 and `v2` is the new moving major tag.
+
 ## [1.2.2] - 2026-10-13
 
 ### Added

MAJOR_TAG

@@ -0,0 +1 @@
+v2

README.md

@@ -17,20 +17,21 @@ A collection of reusable Gitea Actions workflows for DevOps professionals and so
 
 This repository is the central collection of reusable automation for TirSystem repositories. The primary repository lives at `git.tirsystem.com` (Gitea) and is push-mirrored to GitHub.
 
-It contains ten workflows: metadata sync to the GitHub mirror, wiki publishing (scoped, and reusable for repositories that call it), shared quality checks for Python and shell, for C and C++ and for C#, a release workflow, the publishing of accepted milestones and the repository's own validation. They are listed with their purpose and a diagram under [Workflows](#-workflows).
+It contains eleven workflows: metadata sync to the GitHub mirror, wiki publishing (called by each repository), shared quality checks for Python and shell, for C and C++ and for C#, code metrics and coverage badges, a check that comments are in English, a release workflow, the publishing of accepted milestones and the repository's own validation. They are listed with their purpose and a diagram under [Workflows](#-workflows).
 
 ## 🔧 Workflows
 
-Ten workflows live in this repository. A **scoped** workflow is delivered by the instance to every repository of the TirSystem organizations and needs nothing in the repository; a **reusable** workflow is called by a repository with `uses:`; the others run only here. The diagrams are PlantUML source.
+Eleven workflows live in this repository. A **scoped** workflow is delivered by the instance to every repository of the TirSystem organizations and needs nothing in the repository; a **reusable** workflow is called by a repository with `uses:`; the others run only here. The diagrams are PlantUML source.
 
 | Workflow | File | Kind | Starts on | Purpose |
 | --- | --- | --- | --- | --- |
 | Sync GitHub mirror metadata | [`sync-github-metadata.yml`](.gitea/scoped_workflows/sync-github-metadata.yml) | Scoped | push to `main`, manual, daily 03:17 UTC | Copies the description and topics of a Gitea repository to its GitHub push mirror |
-| Publish wiki | [`publish-wiki.yml`](.gitea/scoped_workflows/publish-wiki.yml) | Scoped, opt-in with `wiki/.publish`; deprecated, replaced by the reusable workflow below (ADR-0009) | push to `main` that changes `wiki/**`, manual | Publishes the pages in `wiki/` to the repository wiki |
 | Publish wiki pages | [`publish-wiki-pages.yml`](.gitea/workflows/publish-wiki-pages.yml) | Reusable (`workflow_call`) | a call from another repository | Publishes the pages in `docs/wiki/` (or the folder named by `wiki_dir`) to the wiki of the calling repository |
 | Quality checks | [`quality-checks.yml`](.gitea/workflows/quality-checks.yml) | Reusable (`workflow_call`) | a call from another repository | Runs ruff, mypy, shellcheck and shfmt on the tracked files and changes nothing |
 | Quality checks C++ | [`quality-checks-cpp.yml`](.gitea/workflows/quality-checks-cpp.yml) | Reusable (`workflow_call`) | a call from another repository | Runs clang-format and clang-tidy at exact versions on the tracked C and C++ files and changes nothing |
 | Quality checks C# | [`quality-checks-csharp.yml`](.gitea/workflows/quality-checks-csharp.yml) | Reusable (`workflow_call`) | a call from another repository | Runs `dotnet format` and `dotnet build` on an exact .NET SDK 10 or later and changes nothing |
+| Code metrics | [`code-metrics.yml`](.gitea/workflows/code-metrics.yml) | Reusable (`workflow_call`) | a call from another repository | Counts the code files and the lines of code (without comment and blank lines), reads a Cobertura coverage report and commits three SVG badges to a `badges` branch |
+| English comments | [`english-comments.yml`](.gitea/workflows/english-comments.yml) | Reusable (`workflow_call`) | a call from another repository, on a pull request | Judges the language of the comments and docstrings a pull request adds, fails the run when one is not English and writes one comment on the pull request that mentions the author |
 | Publish own wiki | [`publish-own-wiki.yml`](.gitea/workflows/publish-own-wiki.yml) | This repository only | push to `main` that changes `docs/wiki/**`, manual | Calls the reusable Publish wiki pages workflow for the wiki of this repository |
 | Release | [`release.yml`](.gitea/workflows/release.yml) | This repository only | manual | Creates the version tag, the release page and the major tag after the checks |
 | Publish accepted milestones | [`sync-milestones.yml`](.gitea/workflows/sync-milestones.yml) | This repository only | push to `main` that changes `docs/milestones/**` or `docs/sqa/reviews/**`, manual (dry run by default) | Creates or updates the Gitea milestone and issues of every milestone that is Accepted with a Go review |
@@ -102,50 +103,6 @@ deactivate Workflow
 @enduml
 ```
 
-### 📖 Publish wiki (scoped, deprecated)
-
-Publishes `wiki/` to the repository wiki, only in a repository that has opted in with `wiki/.publish`. The word `prune` in that file also deletes pages that are not in `wiki/`.
-
-#### 🔀 Workflow
-
-```plantuml
-@startuml
-title Publish wiki/ to the repository wiki
-
-autonumber
-
-actor "Push to main that changes wiki/**,\nor manual trigger" as Trigger
-participant "Gitea Actions\npublish-wiki" as Workflow
-participant "shared-scripts\n(tools/publish_wiki.py at v1)" as Script
-participant "Gitea wiki API" as Wiki
-
-Trigger -> Workflow: Start workflow
-activate Workflow
-Workflow -> Script: Check out the repository and the script, run it
-activate Script
-
-alt wiki/.publish does not exist
-  Script --> Workflow: Log that publishing is not enabled and succeed\n(nothing is written)
-else wiki/ has no Markdown pages
-  Script --> Workflow: Fail with [configuration]\n(an empty wiki/ never deletes pages)
-else
-  Script -> Script: Read the marker (empty, or the word prune)\nand TOKEN_FOR_GITEA_WIKI
-  Script -> Wiki: GET repository (preflight)
-  Wiki --> Script: Wiki is enabled, token accepted
-  Script -> Wiki: GET pages
-  Wiki --> Script: Existing pages
-  Script -> Wiki: Create new pages, update changed pages
-  opt marker says prune
-    Script -> Wiki: Delete pages that are not in wiki/
-  end
-  Script --> Workflow: Log created, updated and deleted counts
-end
-deactivate Script
-Workflow --> Trigger: Workflow result
-deactivate Workflow
-@enduml
-```
-
 ### ✅ Quality checks
 
 A reusable workflow for Python and shell, called with `uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v1` (see the [guide](guides/quality-checks.md)).
@@ -282,6 +239,90 @@ deactivate Workflow
 @enduml
 ```
 
+### 🏅 Code metrics
+
+A reusable workflow that counts the code files and the lines of code (without comment and blank lines) of a repository and publishes them, with the test coverage, as three SVG badges on a `badges` branch, called with `uses: TirSystem/github-action/.gitea/workflows/code-metrics.yml@v2` (ADR-0010). It needs `contents: write` and runs no test: an earlier job of the caller produces a Cobertura XML coverage report and uploads it as an artifact ([guide](guides/code-metrics.md)).
+
+#### 🔀 Workflow
+
+```plantuml
+@startuml
+title Code metrics and coverage badges (reusable workflow)
+
+autonumber
+
+actor "Calling repository\nuses: ...code-metrics.yml@v2" as Caller
+participant "Gitea Actions\ncode-metrics" as Workflow
+participant "Branch badges\nof the caller" as Branch
+
+Caller -> Workflow: workflow_call with working-directory, exclude,\ncoverage-report and thresholds
+activate Workflow
+
+Workflow -> Workflow: Check out the caller and the shared scripts
+Workflow -> Workflow: Validate the inputs
+alt an input is invalid
+  Workflow --> Caller: Fail with [configuration]
+end
+
+Workflow -> Workflow: Download the coverage artifact (when given)
+Workflow -> Workflow: Count code files and lines of code
+alt a coverage report is given but missing or malformed
+  Workflow --> Caller: Fail with [configuration] that names the file
+else
+  Workflow -> Workflow: Write code-files.svg, code-lines.svg\nand coverage.svg
+end
+
+Workflow -> Branch: Compare with the files of the branch
+alt no badge changed
+  Workflow --> Caller: Notice: nothing to commit, pass
+else
+  Workflow -> Branch: One commit with [skip ci]
+  Workflow --> Caller: Badges published
+end
+deactivate Workflow
+@enduml
+```
+
+### 🔤 English comments
+
+A reusable workflow that checks that the comments and docstrings a pull request adds are written in English, fails the run when one is not, and writes one comment on the pull request that mentions the author. It changes no file and sends no source text outside the instance; marking the check as required in the branch protection is what blocks the merge ([guide](guides/english-comments.md), ADR-0012).
+
+#### 🔀 Workflow
+
+```plantuml
+@startuml
+title English comments check (reusable workflow)
+
+autonumber
+
+actor "Pull request
+uses: ...english-comments.yml@v2" as Caller
+participant "Gitea Actions
+english-comments" as Workflow
+participant "Gitea REST API" as Gitea
+
+Caller -> Workflow: workflow_call with scope, exclude,
+allowed-words-file, threshold and min-words
+activate Workflow
+
+Workflow -> Workflow: Check out the full history and the shared scripts
+Workflow -> Workflow: Install the pinned language detector
+Workflow -> Workflow: Read the comments on the added lines
+Workflow -> Workflow: Remove paths, options, identifiers and allowed words
+Workflow -> Workflow: Judge the language of each comment block
+
+alt a block is not English
+  Workflow -> Gitea: Create or update one comment that mentions the author
+  Workflow --> Caller: run failed (the required check blocks the merge)
+else all blocks are English
+  Workflow -> Gitea: Mark an earlier comment resolved
+  Workflow --> Caller: run passed
+end
+
+deactivate Workflow
+@enduml
+```
+
 ### 🏷️ Release
 
 Started by hand by a maintainer; with `dry_run` `true` (the default) it only checks (see the [release process](guides/release-process.md)).
@@ -542,10 +583,11 @@ Rows that say Implemented or Guides written exist today. The rest is planned and
 | Synchronize repository metadata (Gitea to GitHub mirror) | Implemented in `.gitea/scoped_workflows/`, with offline tests and a validation workflow |
 | Configure and validate workflow credentials | Implemented for the sync workflow: preflight checks both tokens before any change ([guide](guides/credentials.md)) |
 | Onboard a repository, manage runners, diagnose failures | Guides written ([onboarding](guides/onboarding.md), [troubleshooting](guides/troubleshooting.md)); scoped delivery to the repositories of all four organizations verified (MIL-002) |
-| Publish a repository wiki from `wiki/` (opt-in, delivered to every organization) | Implemented in `.gitea/scoped_workflows/publish-wiki.yml`, with offline tests; a pilot in a second repository publishes its wiki (MIL-006); being replaced by the reusable workflow below (ADR-0009) |
-| Publish a repository wiki from `docs/wiki/` through a called workflow | Implemented as the reusable workflow `.gitea/workflows/publish-wiki-pages.yml`, with offline tests; this repository's own wiki is in `docs/wiki/` and published by it through `publish-own-wiki.yml`; not yet called from another repository (MIL-008) |
+| Publish a repository wiki from `docs/wiki/` through a called workflow | Implemented as the reusable workflow `.gitea/workflows/publish-wiki-pages.yml`, with offline tests; called by every repository that publishes a wiki, and this repository's own wiki is in `docs/wiki/` (MIL-008, MIL-009) |
 | Shared quality checks (Python and shell) | Implemented as the reusable workflow `.gitea/workflows/quality-checks.yml`, with offline tests and a trial in a second organization; adopted in RepoFoundry ([guide](guides/quality-checks.md)) |
 | Shared quality checks (C and C++, C#) | Implemented as the reusable workflows `.gitea/workflows/quality-checks-cpp.yml` and `.gitea/workflows/quality-checks-csharp.yml` with exact tool versions and offline tests; not yet used in another repository (MIL-007) ([C and C++ guide](guides/quality-checks-cpp.md), [C# guide](guides/quality-checks-csharp.md)) |
+| Code metrics and coverage badges | Implemented and released in 2.1.0 as the reusable workflow `.gitea/workflows/code-metrics.yml` with a counter, a Cobertura reader, an SVG renderer and offline tests; tried in a throwaway repository, not yet used in a project repository (MIL-010) ([guide](guides/code-metrics.md)) |
+| English comments | Implemented as the reusable workflow `.gitea/workflows/english-comments.yml` with a comment extractor, a language detector measured on a corpus (ADR-0012), a pull request comment and offline tests; not yet run on the instance or required by any repository (MIL-013) ([guide](guides/english-comments.md)) |
 | Versioned release and publishing | Release process, changelog and upgrade guide defined; the release workflow exists and `v1.0.0` is released (MIL-004) ([guide](guides/upgrading.md)) |
 
 ## 📄 License

actions/connect-tailscale/action.yml

@@ -0,0 +1,82 @@
+name: Connect Tailscale
+description: >-
+  Joins a Tailscale network (tailnet) from a Gitea Actions runner, so the next
+  steps of the job (a deployment) can reach hosts on the tailnet. Written for
+  Gitea Actions; it replaces the GitHub marketplace action tailscale/github-action,
+  which is not verified on Gitea. Run it again with action "down" in a last step
+  with if always().
+
+inputs:
+  action:
+    description: "up joins the tailnet; down logs the node out and stops tailscaled"
+    required: false
+    default: "up"
+  authkey:
+    description: "A Tailscale auth key (a secret). Use an ephemeral, tagged, pre-authorized key. Give authkey or oauth-secret, not both"
+    required: false
+    default: ""
+  oauth-secret:
+    description: "The secret of a Tailscale OAuth client with the scope auth_keys (a secret). Needs tags"
+    required: false
+    default: ""
+  tags:
+    description: "ACL tags of the node, comma separated, e.g. tag:ci. Required with oauth-secret"
+    required: false
+    default: ""
+  hostname:
+    description: "Name of the node in the tailnet. Empty uses the runner name"
+    required: false
+    default: ""
+  version:
+    description: "Exact Tailscale version to install when tailscale is not on the runner, e.g. 1.80.2. Empty uses the installed tailscale and fails when there is none"
+    required: false
+    default: ""
+  sha256:
+    description: "Optional SHA-256 of the downloaded archive tailscale_<version>_<arch>.tgz; the install fails when it differs"
+    required: false
+    default: ""
+  userspace-networking:
+    description: >-
+      true runs tailscaled without a TUN device (no NET_ADMIN needed); tailnet
+      hosts are then reached through the SOCKS5 proxy localhost:1055, e.g. ssh -o
+      ProxyCommand="nc -X 5 -x localhost:1055 %h %p". false creates a TUN device.
+    required: false
+    default: "false"
+  args:
+    description: "Extra arguments for tailscale up, e.g. --accept-routes. Never put a secret here"
+    required: false
+    default: ""
+  timeout:
+    description: "Seconds to wait for the node to come up"
+    required: false
+    default: "60"
+  health-check-host:
+    description: "Optional tailnet host that must answer a Tailscale ping, else the step fails"
+    required: false
+    default: ""
+
+runs:
+  using: composite
+  steps:
+    - name: Mask the secrets
+      shell: bash
+      env:
+        TS_AUTHKEY: ${{ inputs.authkey }}
+        TS_OAUTH_SECRET: ${{ inputs.oauth-secret }}
+      run: bash "${{ gitea.action_path }}/connect-tailscale.sh" mask
+
+    - name: Run the Tailscale step
+      shell: bash
+      env:
+        TS_ACTION: ${{ inputs.action }}
+        TS_AUTHKEY: ${{ inputs.authkey }}
+        TS_OAUTH_SECRET: ${{ inputs.oauth-secret }}
+        TS_TAGS: ${{ inputs.tags }}
+        TS_HOSTNAME: ${{ inputs.hostname }}
+        TS_VERSION: ${{ inputs.version }}
+        TS_SHA256: ${{ inputs.sha256 }}
+        TS_USERSPACE: ${{ inputs.userspace-networking }}
+        TS_ARGS: ${{ inputs.args }}
+        TS_TIMEOUT: ${{ inputs.timeout }}
+        TS_HEALTH_CHECK_HOST: ${{ inputs.health-check-host }}
+      run: bash "${{ gitea.action_path }}/connect-tailscale.sh" "$TS_ACTION"

actions/connect-tailscale/connect-tailscale.sh

@@ -0,0 +1,196 @@
+#!/usr/bin/env bash
+# Steps of the composite action actions/connect-tailscale/action.yml.
+#
+#   connect-tailscale.sh mask   print ::add-mask:: for every secret input
+#   connect-tailscale.sh up     install tailscale if needed, start tailscaled and join the tailnet
+#   connect-tailscale.sh down   log the node out and stop tailscaled
+#
+# Settings come from the environment, never from interpolated expressions:
+#   TS_AUTHKEY, TS_OAUTH_SECRET, TS_TAGS, TS_HOSTNAME, TS_VERSION, TS_USERSPACE,
+#   TS_SHA256, TS_ARGS, TS_TIMEOUT, TS_HEALTH_CHECK_HOST. TS_TAILSCALE,
+#   TS_TAILSCALED, TS_SUDO, TS_STATE_DIR, TS_START_WAIT (tries) and
+#   TS_WAIT_INTERVAL (seconds) name the commands, the work folder and the waits,
+#   for the tests.
+# The auth key is passed to tailscale in a file of mode 600, never on a command
+# line. Every failure is printed as ::error::[category] message.
+
+TS_TAILSCALE="${TS_TAILSCALE:-tailscale}"
+TS_TAILSCALED="${TS_TAILSCALED:-tailscaled}"
+# sudo is used only when the job is not root: a job container runs as root and
+# often has no sudo. TS_SUDO overrides it (empty for none).
+if [ -n "${TS_SUDO+x}" ]; then
+  SUDO="$TS_SUDO"
+elif [ "$(id -u)" = "0" ]; then
+  SUDO=""
+else
+  SUDO="sudo"
+fi
+STATE_DIR="${TS_STATE_DIR:-${RUNNER_TEMP:-/tmp}/tailscale}"
+
+fail() {
+  echo "::error::[$1] $2"
+  exit 1
+}
+
+mask_secrets() {
+  local value
+  for value in "${TS_AUTHKEY:-}" "${TS_OAUTH_SECRET:-}"; do
+    [ -n "$value" ] && echo "::add-mask::$value"
+  done
+  return 0
+}
+
+validate_inputs() {
+  if [ -n "${TS_AUTHKEY:-}" ] && [ -n "${TS_OAUTH_SECRET:-}" ]; then
+    fail configuration "give authkey or oauth-secret, not both."
+  fi
+  if [ -z "${TS_AUTHKEY:-}" ] && [ -z "${TS_OAUTH_SECRET:-}" ]; then
+    fail configuration "give authkey or oauth-secret."
+  fi
+  if [ -n "${TS_OAUTH_SECRET:-}" ] && [ -z "${TS_TAGS:-}" ]; then
+    fail configuration "tags is required with oauth-secret (for example tag:ci)."
+  fi
+  if [ -n "${TS_TAGS:-}" ]; then
+    [[ "$TS_TAGS" =~ ^tag:[a-zA-Z0-9-]+(,tag:[a-zA-Z0-9-]+)*$ ]] ||
+      fail configuration "tags must look like tag:ci or tag:ci,tag:deploy."
+  fi
+  [[ "$TS_TIMEOUT" =~ ^[0-9]+$ ]] ||
+    fail configuration "timeout must be a number of seconds."
+  [[ "$TS_VERSION" =~ ^([0-9]+\.[0-9]+\.[0-9]+)?$ ]] ||
+    fail configuration "version must be an exact version like 1.80.2."
+  [[ "${TS_SHA256:-}" =~ ^([0-9a-fA-F]{64})?$ ]] ||
+    fail configuration "sha256 must be 64 hexadecimal digits."
+  case "$TS_USERSPACE" in
+    true | false) ;;
+    *) fail configuration "userspace-networking must be true or false." ;;
+  esac
+  [[ "${TS_HOSTNAME:-}" =~ ^[a-zA-Z0-9-]*$ ]] ||
+    fail configuration "hostname may hold letters, digits and hyphens only."
+}
+
+machine_arch() {
+  case "$(uname -m)" in
+    x86_64 | amd64) echo amd64 ;;
+    aarch64 | arm64) echo arm64 ;;
+    *) fail environment "no Tailscale build for $(uname -m)." ;;
+  esac
+}
+
+install_tools() {
+  command -v "$TS_TAILSCALE" >/dev/null 2>&1 && command -v "$TS_TAILSCALED" >/dev/null 2>&1 && return 0
+  [ -n "$TS_VERSION" ] ||
+    fail configuration "tailscale is not on the runner; set version (for example 1.80.2) so it can be installed."
+  local arch url tmp
+  arch="$(machine_arch)"
+  url="https://pkgs.tailscale.com/stable/tailscale_${TS_VERSION}_${arch}.tgz"
+  echo "Installing Tailscale $TS_VERSION"
+  tmp="$(mktemp -d)"
+  curl -fsSL "$url" -o "$tmp/tailscale.tgz" ||
+    fail environment "could not download $url."
+  if [ -n "${TS_SHA256:-}" ]; then
+    echo "${TS_SHA256}  $tmp/tailscale.tgz" | sha256sum -c --quiet - ||
+      fail environment "the downloaded archive does not match sha256."
+  fi
+  tar -xzf "$tmp/tailscale.tgz" -C "$tmp" --strip-components=1 ||
+    fail environment "could not unpack the Tailscale archive."
+  $SUDO install -m 755 "$tmp/tailscale" "$tmp/tailscaled" /usr/local/bin/ ||
+    fail environment "could not install tailscale (root or sudo is needed)."
+  rm -rf "$tmp"
+}
+
+daemon_answers() {
+  "$TS_TAILSCALE" version --daemon >/dev/null 2>&1
+}
+
+start_daemon() {
+  # a daemon that already runs belongs to the host; this action would log it out
+  if daemon_answers; then
+    fail environment "a tailscaled already runs on this runner; the action starts its own and must not take over the host's. Use it on a job container."
+  fi
+  local args=(--state=mem:)
+  if [ "$TS_USERSPACE" = "true" ]; then
+    args+=(--tun=userspace-networking --socks5-server=localhost:1055)
+  fi
+  mkdir -p "$STATE_DIR"
+  $SUDO nohup "$TS_TAILSCALED" "${args[@]}" >"$STATE_DIR/tailscaled.log" 2>&1 &
+  : >"$STATE_DIR/started-by-action"
+  wait_for_daemon
+}
+
+# wait_for_daemon: tailscaled needs a moment to create its socket
+wait_for_daemon() {
+  local tries="${TS_START_WAIT:-30}" i
+  for ((i = 0; i < tries; i++)); do
+    daemon_answers && return 0
+    sleep "${TS_WAIT_INTERVAL:-1}"
+  done
+  fail connection "tailscaled did not answer in $tries tries; the last lines of its log: $(tail -n 5 "$STATE_DIR/tailscaled.log" 2>/dev/null | tr '
+' ' ')"
+}
+
+# write_key_file: the auth key in a file of mode 600; prints its path
+write_key_file() {
+  local file="$STATE_DIR/authkey" key
+  if [ -n "${TS_OAUTH_SECRET:-}" ]; then
+    key="${TS_OAUTH_SECRET}?ephemeral=true&preauthorized=true"
+  else
+    key="$TS_AUTHKEY"
+  fi
+  mkdir -p "$STATE_DIR"
+  (umask 077 && printf '%s' "$key" >"$file")
+  echo "$file"
+}
+
+tailnet_up() {
+  validate_inputs
+  install_tools
+  start_daemon
+  local keyfile up_args extra
+  keyfile="$(write_key_file)"
+  up_args=("--auth-key=file:$keyfile" "--timeout=${TS_TIMEOUT}s")
+  [ -z "${TS_HOSTNAME:-}" ] || up_args+=("--hostname=$TS_HOSTNAME")
+  [ -z "${TS_TAGS:-}" ] || up_args+=("--advertise-tags=$TS_TAGS")
+  # TS_ARGS is split on spaces on purpose: it holds flags, never a secret
+  # shellcheck disable=SC2206
+  extra=(${TS_ARGS:-})
+  if ! $SUDO "$TS_TAILSCALE" up "${up_args[@]}" "${extra[@]}"; then
+    rm -f "$keyfile"
+    fail connection "tailscale up failed; the last lines of tailscaled: $(tail -n 5 "$STATE_DIR/tailscaled.log" 2>/dev/null | tr '\n' ' ')"
+  fi
+  rm -f "$keyfile"
+  if [ -n "${TS_HEALTH_CHECK_HOST:-}" ]; then
+    "$TS_TAILSCALE" ping --c 3 --timeout 10s "$TS_HEALTH_CHECK_HOST" >/dev/null 2>&1 ||
+      fail connection "health-check-host '$TS_HEALTH_CHECK_HOST' does not answer on the tailnet."
+  fi
+  echo "Tailscale is up."
+}
+
+tailnet_down() {
+  # only a daemon this action started is logged out and stopped
+  if [ ! -f "$STATE_DIR/started-by-action" ]; then
+    echo "This action did not start tailscaled on this runner; nothing to do."
+    return 0
+  fi
+  $SUDO "$TS_TAILSCALE" logout 2>/dev/null || echo "The node was not logged in."
+  $SUDO "$TS_TAILSCALE" down 2>/dev/null || true
+  $SUDO pkill -x "$(basename "$TS_TAILSCALED")" 2>/dev/null || true
+  rm -rf "$STATE_DIR"
+  echo "Tailscale is down."
+}
+
+main() {
+  set -uo pipefail
+  TS_USERSPACE="${TS_USERSPACE:-false}"
+  TS_TIMEOUT="${TS_TIMEOUT:-60}"
+  TS_VERSION="${TS_VERSION:-}"
+  case "${1:-}" in
+    mask) mask_secrets ;;
+    up) tailnet_up ;;
+    down) tailnet_down ;;
+    *) fail configuration "unknown command '${1:-}'; use mask, up or down." ;;
+  esac
+}
+
+if [ "${BASH_SOURCE[0]}" = "$0" ]; then
+  main "$@"
+fi

actions/connect-wireguard/action.yml

@@ -0,0 +1,85 @@
+name: Connect WireGuard
+description: >-
+  Brings up a WireGuard tunnel on a Gitea Actions runner, so the next steps of
+  the job (a deployment) can reach hosts on a private network. Run it again
+  with action "down" in a last step with if always().
+
+inputs:
+  action:
+    description: "up brings the tunnel up; down takes it down and removes the configuration"
+    required: false
+    default: "up"
+  config:
+    description: >-
+      A complete wg-quick configuration, stored as a Gitea secret. When set, the
+      individual inputs below are ignored.
+    required: false
+    default: ""
+  private-key:
+    description: "Private key of this runner (a secret)"
+    required: false
+    default: ""
+  address:
+    description: "Address of this runner inside the tunnel, e.g. 10.8.0.2/32"
+    required: false
+    default: ""
+  peer-public-key:
+    description: "Public key of the WireGuard server"
+    required: false
+    default: ""
+  endpoint:
+    description: "Address of the WireGuard server as host:port"
+    required: false
+    default: ""
+  allowed-ips:
+    description: "Networks routed through the tunnel, comma separated. Never 0.0.0.0/0 unless the deployment needs it"
+    required: false
+    default: ""
+  preshared-key:
+    description: "Optional preshared key (a secret)"
+    required: false
+    default: ""
+  dns:
+    description: "Optional DNS server for the tunnel"
+    required: false
+    default: ""
+  persistent-keepalive:
+    description: "Seconds between keepalive packets, 0 turns them off"
+    required: false
+    default: "25"
+  interface:
+    description: "Name of the interface"
+    required: false
+    default: "wg0"
+  health-check-host:
+    description: "Optional host behind the tunnel that must answer a ping, else the step fails"
+    required: false
+    default: ""
+
+runs:
+  using: composite
+  steps:
+    - name: Mask the secrets
+      shell: bash
+      env:
+        WG_CONFIG: ${{ inputs.config }}
+        WG_PRIVATE_KEY: ${{ inputs.private-key }}
+        WG_PRESHARED_KEY: ${{ inputs.preshared-key }}
+      run: bash "${{ gitea.action_path }}/connect-wireguard.sh" mask
+
+    - name: Run the WireGuard step
+      shell: bash
+      env:
+        WG_ACTION: ${{ inputs.action }}
+        WG_CONFIG: ${{ inputs.config }}
+        WG_PRIVATE_KEY: ${{ inputs.private-key }}
+        WG_ADDRESS: ${{ inputs.address }}
+        WG_PEER_PUBLIC_KEY: ${{ inputs.peer-public-key }}
+        WG_ENDPOINT: ${{ inputs.endpoint }}
+        WG_ALLOWED_IPS: ${{ inputs.allowed-ips }}
+        WG_PRESHARED_KEY: ${{ inputs.preshared-key }}
+        WG_DNS: ${{ inputs.dns }}
+        WG_KEEPALIVE: ${{ inputs.persistent-keepalive }}
+        WG_INTERFACE: ${{ inputs.interface }}
+        WG_HEALTH_CHECK_HOST: ${{ inputs.health-check-host }}
+      run: bash "${{ gitea.action_path }}/connect-wireguard.sh" "$WG_ACTION"

actions/connect-wireguard/connect-wireguard.sh

@@ -0,0 +1,160 @@
+#!/usr/bin/env bash
+# Steps of the composite action actions/connect-wireguard/action.yml.
+#
+#   connect-wireguard.sh mask   print ::add-mask:: for every secret input
+#   connect-wireguard.sh up     write the configuration and bring the tunnel up
+#   connect-wireguard.sh down   take the tunnel down and delete the configuration
+#
+# Settings come from the environment, never from interpolated expressions:
+#   WG_CONFIG, WG_PRIVATE_KEY, WG_ADDRESS, WG_PEER_PUBLIC_KEY, WG_ENDPOINT,
+#   WG_ALLOWED_IPS, WG_PRESHARED_KEY, WG_DNS, WG_KEEPALIVE, WG_INTERFACE,
+#   WG_HEALTH_CHECK_HOST. WG_DIR is the configuration directory (/etc/wireguard
+#   by default); WG_QUICK, WG_SUDO and WG_PING name the commands, for the tests.
+# Every failure is printed as ::error::[category] message. A key is never printed.
+
+WG_DIR="${WG_DIR:-/etc/wireguard}"
+WG_QUICK="${WG_QUICK:-wg-quick}"
+WG_PING="${WG_PING:-ping}"
+# sudo is used only when the job is not root: a job container runs as root and
+# often has no sudo. WG_SUDO overrides it (empty for none).
+if [ -n "${WG_SUDO+x}" ]; then
+  SUDO="$WG_SUDO"
+elif [ "$(id -u)" = "0" ]; then
+  SUDO=""
+else
+  SUDO="sudo"
+fi
+# variables that must reach wg-quick through sudo, which resets the environment
+WG_QUICK_ENV=()
+
+fail() {
+  echo "::error::[$1] $2"
+  exit 1
+}
+
+mask_secrets() {
+  local value line key
+  for value in "${WG_PRIVATE_KEY:-}" "${WG_PRESHARED_KEY:-}"; do
+    [ -n "$value" ] && echo "::add-mask::$value"
+  done
+  # a full configuration: mask the value of every PrivateKey and PresharedKey
+  # line, and nothing else, so the rest of the log stays readable
+  while IFS= read -r line; do
+    line="${line//$'␍'/}"
+    key="${line%%=*}"
+    key="${key//[[:space:]]/}"
+    case "${key,,}" in
+      privatekey | presharedkey)
+        value="${line#*=}"
+        value="${value#"${value%%[![:space:]]*}"}"
+        value="${value%"${value##*[![:space:]]}"}"
+        [ -n "$value" ] && echo "::add-mask::$value"
+        ;;
+    esac
+  done <<<"${WG_CONFIG:-}"
+  return 0
+}
+
+check_interface() {
+  [[ "$WG_INTERFACE" =~ ^[a-zA-Z0-9_=+.-]{1,15}$ ]] ||
+    fail configuration "interface '$WG_INTERFACE' is not a valid interface name."
+}
+
+# render_config: the wg-quick configuration on stdout
+render_config() {
+  if [ -n "${WG_CONFIG:-}" ]; then
+    printf '%s\n' "$WG_CONFIG"
+    return 0
+  fi
+  local name
+  for name in WG_PRIVATE_KEY WG_ADDRESS WG_PEER_PUBLIC_KEY WG_ENDPOINT WG_ALLOWED_IPS; do
+    [ -n "${!name:-}" ] ||
+      fail configuration "set config, or all of private-key, address, peer-public-key, endpoint and allowed-ips ($name is empty)."
+  done
+  for name in WG_PRIVATE_KEY WG_ADDRESS WG_PEER_PUBLIC_KEY WG_ENDPOINT WG_ALLOWED_IPS WG_PRESHARED_KEY WG_DNS; do
+    # a line break would add directives (PostUp runs as root) to the file
+    [[ "${!name:-}" != *[[:cntrl:]]* ]] ||
+      fail configuration "$name must be one line without control characters."
+  done
+  [[ "$WG_KEEPALIVE" =~ ^[0-9]+$ ]] ||
+    fail configuration "persistent-keepalive must be a number of seconds."
+  printf '[Interface]\nPrivateKey = %s\nAddress = %s\n' "$WG_PRIVATE_KEY" "$WG_ADDRESS"
+  [ -z "${WG_DNS:-}" ] || printf 'DNS = %s\n' "$WG_DNS"
+  printf '\n[Peer]\nPublicKey = %s\nEndpoint = %s\nAllowedIPs = %s\nPersistentKeepalive = %s\n' \
+    "$WG_PEER_PUBLIC_KEY" "$WG_ENDPOINT" "$WG_ALLOWED_IPS" "$WG_KEEPALIVE"
+  [ -z "${WG_PRESHARED_KEY:-}" ] || printf 'PresharedKey = %s\n' "$WG_PRESHARED_KEY"
+}
+
+install_tools() {
+  command -v "$WG_QUICK" >/dev/null 2>&1 && return 0
+  echo "Installing wireguard-tools"
+  if ! { $SUDO apt-get update -qq &&
+    $SUDO apt-get install -y -qq wireguard-tools resolvconf iproute2 iputils-ping; }; then
+    fail environment "wireguard-tools is not installed and could not be installed (a Debian or Ubuntu runner with root is needed)."
+  fi
+}
+
+# Use the user-space implementation when the kernel has no WireGuard module,
+# which is the usual case in a Gitea runner container.
+choose_implementation() {
+  if $SUDO ip link add dev "wgprobe$$" type wireguard 2>/dev/null; then
+    $SUDO ip link delete dev "wgprobe$$" 2>/dev/null || true
+    return 0
+  fi
+  if command -v wireguard-go >/dev/null 2>&1 || $SUDO apt-get install -y -qq wireguard-go 2>/dev/null; then
+    WG_QUICK_ENV=(WG_QUICK_USERSPACE_IMPLEMENTATION=wireguard-go)
+    echo "No kernel WireGuard module; using wireguard-go."
+  else
+    fail environment "the runner has no WireGuard kernel module and wireguard-go could not be installed; the runner container needs NET_ADMIN and /dev/net/tun (see guides/vpn-wireguard.md)."
+  fi
+}
+
+tunnel_up() {
+  check_interface
+  local conf="$WG_DIR/$WG_INTERFACE.conf" rendered
+  # on failure the captured output is the ::error:: line, which must be shown
+  rendered="$(render_config)" || {
+    echo "$rendered"
+    exit 1
+  }
+  install_tools
+  choose_implementation
+  $SUDO install -d -m 700 "$WG_DIR"
+  (umask 077 && printf '%s\n' "$rendered" | $SUDO tee "$conf" >/dev/null)
+  $SUDO chmod 600 "$conf"
+  # env keeps the userspace variable through sudo; the file holds the key, so
+  # it is removed when the interface does not come up
+  if ! $SUDO env ${WG_QUICK_ENV[@]+"${WG_QUICK_ENV[@]}"} "$WG_QUICK" up "$WG_INTERFACE"; then
+    $SUDO rm -f "$conf"
+    fail connection "wg-quick could not bring $WG_INTERFACE up."
+  fi
+  if [ -n "${WG_HEALTH_CHECK_HOST:-}" ]; then
+    "$WG_PING" -c 3 -W 5 "$WG_HEALTH_CHECK_HOST" >/dev/null 2>&1 ||
+      fail connection "health-check-host '$WG_HEALTH_CHECK_HOST' does not answer through the tunnel."
+  fi
+  echo "WireGuard interface $WG_INTERFACE is up."
+}
+
+tunnel_down() {
+  check_interface
+  local conf="$WG_DIR/$WG_INTERFACE.conf"
+  $SUDO "$WG_QUICK" down "$WG_INTERFACE" 2>/dev/null || echo "Interface $WG_INTERFACE was not up."
+  $SUDO rm -f "$conf"
+  echo "WireGuard interface $WG_INTERFACE is down."
+}
+
+main() {
+  set -uo pipefail
+  WG_INTERFACE="${WG_INTERFACE:-wg0}"
+  WG_KEEPALIVE="${WG_KEEPALIVE:-25}"
+  case "${1:-}" in
+    mask) mask_secrets ;;
+    up) tunnel_up ;;
+    down) tunnel_down ;;
+    *) fail configuration "unknown command '${1:-}'; use mask, up or down." ;;
+  esac
+}
+
+if [ "${BASH_SOURCE[0]}" = "$0" ]; then
+  main "$@"
+fi

docs/adr/adr-0004-shared-wiki-publishing-opt-in.md

@@ -4,13 +4,13 @@
 | Key | Value |
 | --- | --- |
 | ID | ADR-0004 |
-| CrossReference | [MIL-006], [ADR-0003], [ADR-0002] |
+| CrossReference | [MIL-006], [ADR-0003], [ADR-0002], [ADR-0009] |
 
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
-| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Initial version | [b22a2cd] |
-| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Reviewed (RC-018): the `prune` variant added to the evaluated options | [b22a2cd] |
+| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Reviewed (RC-018): the `prune` variant added to the evaluated options | [b22a2cd] |
+| 2026-10-14 | Superseded by ADR-0009 | Jens Tirsvad Nielsen | AI as stand-in for S01 | The scoped delivery and the `wiki/.publish` marker are replaced by the reusable workflow of ADR-0009 and removed (MIL-009); the token and the empty-folder rules stand and are carried by ADR-0009; reviewed (RC-065) | [22fc323] |
 
 Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`.
 
@@ -108,10 +108,13 @@ The rules that follow from it:
 - [ADR-0003] — its fallback to `TOKEN_FOR_GITEA` no longer applies to the
   shared workflow.
 - [ADR-0002] — the stand-in rule applies to the review of this ADR.
+- [ADR-0009] — the successor: the reusable workflow replaces the scoped delivery and the marker.
 
 ---
 
 [MIL-006]: ../milestones/mil-006-shared-wiki-publishing.md
 [ADR-0003]: ./adr-0003-wiki-publish-token.md
 [ADR-0002]: ./adr-0002-s01-approves-as-stand-in.md
+[ADR-0009]: ./adr-0009-wiki-publishing-reusable-workflow.md
 [b22a2cd]: https://git.tirsystem.com/TirSystem/github-action/commit/b22a2cd59235078656c4440b945b787f88fbd345
+[22fc323]: https://git.tirsystem.com/TirSystem/github-action/commit/22fc323b41074ee0029ea2f07445a8e329e15d15

docs/adr/adr-0005-quality-check-contract.md

@@ -9,8 +9,8 @@
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
-| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Reviewed (RC-038): the security impact of installing the tools from PyPI named | [385d2fb] |
 | 2026-10-11 | Accepted | Jens Tirsvad Nielsen | S01 | Added the input tools-ref: the shell steps moved to a script file fetched at that ref (RC-051) | [670f0ac] |
+| 2026-10-14 | Proposed | Jens Tirsvad Nielsen | S01 | Amendment: the default `tools-ref` is the current major tag (MIL-011) | [eaa0e30] |
 
 Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`.
 
@@ -118,6 +118,14 @@ The rules that follow from it:
 - [ADR-0004] — the same pattern of a shared scoped or reusable workflow with an
   explicit gate; this ADR does not change it.
 
+
+## Amendment (MIL-011)
+
+The default of the input `tools-ref` in the quality-check contract is the current major tag, defined once in the file
+`MAJOR_TAG` of this repository (`v2` from release 2.1.1), and no longer `v1`. A default must
+name a tag that holds the script the workflow runs; a test checks it. Callers at `@v1` are
+not affected: the `v1` tag keeps the `v1` workflow files.
+
 ---
 
 [MIL-003]: ../milestones/mil-003-quality-checks.md
@@ -126,3 +134,4 @@ The rules that follow from it:
 [ADR-0004]: ./adr-0004-shared-wiki-publishing-opt-in.md
 [385d2fb]: https://git.tirsystem.com/TirSystem/github-action/commit/385d2fb7cb9be1fdc8fd3503d0af624fa38eafc7
 [670f0ac]: https://git.tirsystem.com/TirSystem/github-action/commit/670f0ac469043bb166c84290c0dbf62b4908e3cc
+[eaa0e30]: https://git.tirsystem.com/TirSystem/github-action/commit/eaa0e30beaa097dfeb1c07c814a71d02a6987060

docs/adr/adr-0008-cpp-csharp-quality-check-contract.md

@@ -9,8 +9,8 @@
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
-| 2026-10-11 | Deprecated | Jens Tirsvad Nielsen | S01 | Initial version | [11cba35] |
 | 2026-10-11 | Accepted | Jens Tirsvad Nielsen | S01 | Reviewed (RC-054): abbreviations expanded at first use and the security impact of downloading tools named | [9e7aedd] |
+| 2026-10-14 | Proposed | Jens Tirsvad Nielsen | S01 | Amendment: the default `tools-ref` is the current major tag (MIL-011) | [eaa0e30] |
 
 Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`.
 
@@ -134,6 +134,14 @@ The rules that follow from it:
 - [ADR-0005] — the contract that this decision extends, unchanged.
 - [ADR-0006] — raising a default tool version is breaking.
 
+
+## Amendment (MIL-011)
+
+The default of the input `tools-ref` in the C++ and C# quality-check contract is the current major tag, defined once in the file
+`MAJOR_TAG` of this repository (`v2` from release 2.1.1), and no longer `v1`. A default must
+name a tag that holds the script the workflow runs; a test checks it. Callers at `@v1` are
+not affected: the `v1` tag keeps the `v1` workflow files.
+
 ---
 
 [MIL-007]: ../milestones/mil-007-cpp-csharp-quality-checks.md
@@ -143,3 +151,4 @@ The rules that follow from it:
 [ADR-0006]: ./adr-0006-release-process-and-version-pinning.md
 [11cba35]: https://git.tirsystem.com/TirSystem/github-action/commit/11cba358b83cb7b6624f6b0956ae7b0c112d3692
 [9e7aedd]: https://git.tirsystem.com/TirSystem/github-action/commit/9e7aeddb11c2b41ac893d9f7893d663a53fbe470
+[eaa0e30]: https://git.tirsystem.com/TirSystem/github-action/commit/eaa0e30beaa097dfeb1c07c814a71d02a6987060

docs/adr/adr-0009-wiki-publishing-reusable-workflow.md

@@ -9,7 +9,8 @@
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
-| 2026-10-13 | Proposed | Jens Tirsvad Nielsen | S01 | Initial version | [01b9c29] |
+| 2026-10-13 | Accepted | Jens Tirsvad Nielsen | S01 | Review findings fixed (RC-063): the product owner's language is spelled out, the security consequence is named, and the secret passing is recorded as verified | [8c2c52e] |
+| 2026-10-14 | Proposed | Jens Tirsvad Nielsen | S01 | Amendment: the default `tools-ref` is the current major tag (MIL-011) | [eaa0e30] |
 
 Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`.
 
@@ -22,7 +23,8 @@ repository of an organisation, and a marker file `wiki/.publish` is the opt-in.
 That avoids a copy of the workflow, but it runs where nobody asked for it and
 needs a safety gate for that reason; its trigger path (`wiki/**`) and the
 version of the script (`v1`) are fixed centrally. The framework now prescribes
-the wiki in `docs/wiki/` with English and the PO language as a minimum, and
+the wiki in `docs/wiki/` with English and the product owner's language as a
+minimum, and
 repositories need to say where their wiki is.
 
 Options:
@@ -61,6 +63,9 @@ The rules that follow from it:
   to `docs/wiki/` one repository at a time.
 - Opting in is a file in the repository, reviewed in a pull request, and a
   repository without a caller is never written to.
+- Security: the token is passed explicitly by the caller and is never
+  inherited or taken from a fallback, so a repository that does not pass it
+  cannot write a wiki.
 - One call convention for every shared workflow of this repository.
 
 **Negative:**
@@ -74,8 +79,13 @@ The rules that follow from it:
   their migrations.
 - The owner chose a patch release (1.2.2) for this change although a new
   workflow is a minor one under [ADR-0006]; the changelog states the deviation.
-- Passing a declared secret through `workflow_call` is not yet verified on this
-  Gitea instance; it is checked by the first call, in this repository.
+- Anyone who can change the caller file of a repository can change the folder
+  and `prune`, and so what the token deletes in that repository's wiki; this is
+  the same exposure as the marker had, and it is reviewed through the pull
+  request that changes the caller.
+- Passing a declared secret through `workflow_call`, and a local `uses:` call,
+  were verified on this Gitea instance by run 316 of this repository on
+  2026-10-13.
 
 ## Affected Artifacts
 
@@ -83,6 +93,14 @@ The rules that follow from it:
 - [ADR-0004] — its scoped delivery and marker parts are replaced once the
   scoped workflow is removed; its token and safety rules stand.
 
+
+## Amendment (MIL-011)
+
+The default of the input `tools-ref` in the wiki publishing contract is the current major tag, defined once in the file
+`MAJOR_TAG` of this repository (`v2` from release 2.1.1), and no longer `v1`. A default must
+name a tag that holds the script the workflow runs; a test checks it. Callers at `@v1` are
+not affected: the `v1` tag keeps the `v1` workflow files.
+
 ---
 
 [MIL-008]: ../milestones/mil-008-wiki-reusable-workflow.md
@@ -91,3 +109,5 @@ The rules that follow from it:
 [ADR-0006]: ./adr-0006-release-process-and-version-pinning.md
 [ADR-0005]: ./adr-0005-quality-check-contract.md
 [01b9c29]: https://git.tirsystem.com/TirSystem/github-action/commit/01b9c2972b4317bcc590540010aea0eaf7f30014
+[8c2c52e]: https://git.tirsystem.com/TirSystem/github-action/commit/8c2c52ebd2a27e4d0edb4008c31c002718d280fb
+[eaa0e30]: https://git.tirsystem.com/TirSystem/github-action/commit/eaa0e30beaa097dfeb1c07c814a71d02a6987060

docs/adr/adr-0010-code-metrics-badges-contract.md

@@ -0,0 +1,226 @@
+# ADR-0010: Contract of the code metrics and coverage badges workflow
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | ADR-0010 |
+| CrossReference | [MIL-010], [UC-008], [US-001], [ADR-0005], [ADR-0006] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | The report reaches the workflow as an artifact of the caller's run (input `coverage-artifact`), because a called workflow runs in its own job; reviewed (RC-073) | [0dc5132] |
+| 2026-10-14 | Proposed | Jens Tirsvad Nielsen | S01 | Amendment: the default `tools-ref` is the current major tag (MIL-011) | [eaa0e30] |
+
+Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`.
+
+---
+
+## Context
+
+MIL-010 adds a reusable workflow that shows the size of a repository's code
+and its test coverage as badges (UC-008, US-001.18 to US-001.20). ADR-0005
+defines the contract of the quality-check workflow: inputs with working
+defaults, a pinned version per tool, a failure that names the cause, and a
+script file of this repository, fetched at `tools-ref`, that the workflow runs.
+Decisions the user took in chat on 2026-10-14 bound this one: the counter is a
+Python script of this repository with no dependency outside the standard
+library, the delivery is a reusable workflow, the badges are committed to a
+`badges` branch, there are three badges (code files, lines of code, coverage),
+and the coverage report is read in the Cobertura XML format.
+
+Options for the counter:
+
+1. **Wrap `cloc`, `tokei` or `scc`.** Many languages, mature rules, but a tool
+   to install and pin on every run and a download from outside the instance.
+2. **A Python script of this repository.** No install, fully tested offline,
+   and the rules are ours; fewer languages and simple scanning rules.
+
+Options for the delivery of the badges: a run artifact (disappears and has no
+stable URL), a file on the default branch (a commit per change on the branch
+that protects the code), or a dedicated branch (stable raw URL, no effect on
+the default branch).
+
+Facts: the job of a reusable workflow runs on `ubuntu-latest` with `python3`
+3.12; a push made with the token of a run does not start another run; a
+workflow checks the shared scripts out into the workspace (`shared-scripts`),
+so the counter must not count them.
+
+## Decision
+
+A reusable workflow `code-metrics.yml` runs three script files of this
+repository, fetched at its input `tools-ref` (default `v1`): `tools/count_loc.py`
+counts the code, `tools/badges.py` reads the coverage report and writes the
+badges, and `tools/code-metrics.sh` validates the inputs, calls both and
+publishes the badge files to the `badges` branch of the calling repository
+with the token of the run (`contents: write`, no other permission).
+
+The rules that follow from it:
+
+- **Code file.** A file under `working-directory` whose extension is in the
+  language table below, that is not excluded, and that contains no NUL byte
+  (it is text; it is read as UTF-8 and invalid bytes are replaced). Its
+  language comes from the extension. A file with a code extension but no
+  line is still a code file.
+- **Languages and comments (first version).**
+
+  | Language | Extensions | Line comment | Block comment |
+  | --- | --- | --- | --- |
+  | Python | `.py` | `#` | none |
+  | Shell | `.sh`, `.bash` | `#` at the start of a word | none |
+  | PowerShell | `.ps1`, `.psm1` | `#` | `<#` ... `#>` |
+  | C | `.c`, `.h` | `//` | `/*` ... `*/` |
+  | C++ | `.cc`, `.cpp`, `.cxx`, `.hh`, `.hpp` | `//` | `/*` ... `*/` |
+  | C# | `.cs` | `//` | `/*` ... `*/` |
+  | Java | `.java` | `//` | `/*` ... `*/` |
+  | JavaScript | `.js`, `.mjs`, `.jsx` | `//` | `/*` ... `*/` |
+  | TypeScript | `.ts`, `.tsx` | `//` | `/*` ... `*/` |
+  | Go | `.go` | `//` | `/*` ... `*/` |
+  | Rust | `.rs` | `//` | `/*` ... `*/` |
+  | SQL | `.sql` | `--` | `/*` ... `*/` |
+
+  Markup, data and configuration files (Markdown, YAML, JSON, XML, HTML,
+  CSS) are not code files. A language is added by a minor release.
+- **Line classes.** Every physical line is exactly one of: *blank* (only
+  white space, also inside a block comment), *comment* (not blank, and only
+  comment text and white space), or *code* (anything else, including a line
+  with code and a trailing comment). A comment marker inside a string literal
+  is not a comment. String literals are the quoted forms of the language that
+  end on the same line, plus the Python triple-quoted string and the backtick
+  string of JavaScript, TypeScript and Go, which may span lines; a Python
+  docstring is a string and so counts as code.
+  Raw-string and verbatim forms that differ from these (Rust `r#"..."#`, C#
+  `@"..."` with doubled quotes, C++ raw strings) are scanned as ordinary
+  strings and can be mis-counted; this is a stated limit.
+- **Excluded by default.** Every directory whose name starts with `.`, and the
+  directories `node_modules`, `vendor`, `third_party`, `dist`, `build`, `out`,
+  `bin`, `obj`, `target`, `venv`, `__pycache__` and `shared-scripts`
+  (the checkout of the shared scripts); symbolic links are not followed. The
+  input `exclude` is a comma list of patterns that add to this: a pattern
+  without `/` matches a directory or file name anywhere, a pattern with `/`
+  matches the path relative to `working-directory` (`*` does not cross `/`).
+  The counter does not read `.gitignore` or generated-file markers; a caller
+  excludes generated code with `exclude`.
+- **Totals.** `files` is the number of code files and `lines` is the sum of
+  their code lines (comment and blank lines are not in it); the result also
+  holds `comment` and `blank` totals and the same four numbers per language,
+  sorted by language name, in `code-metrics.json`.
+- **Coverage report.** The input `coverage-report` is the path, relative to
+  the repository root, of a Cobertura XML file. The percentage is
+  `lines-covered / lines-valid` of the root `coverage` element, shown rounded
+  half up to a whole number; when a count is absent, `line-rate` is used.
+  A path that does not exist, a file that is not well-formed Cobertura XML,
+  and a report with no valid lines are failures with the category
+  `[configuration]` that names the file; no coverage badge is written. An
+  empty `coverage-report` means no coverage badge and a notice. The workflow
+  does not run tests. A called workflow runs in its own job, so it cannot see
+  the files of the caller's test job: the caller runs its tests in an earlier
+  job, uploads the report as an artifact and gives the artifact's name as the
+  input `coverage-artifact`. The workflow then downloads that artifact into
+  the directory `coverage-artifact` of its workspace and `coverage-report`
+  names the file inside the artifact. Without `coverage-artifact`,
+  `coverage-report` is a path in the checkout of the repository (a report the
+  repository commits). `coverage-artifact` without `coverage-report` is a
+  `[configuration]` failure.
+- **Badges.** Three flat SVG files with a label and a value, written to the
+  root of the `badges` branch with fixed names: `code-files.svg` (label
+  `code files`), `code-lines.svg` (label `lines of code`) and `coverage.svg`
+  (label `coverage`); the values are the whole number with `,` between groups
+  of three digits and, for coverage, `%`. The value colour of the first two is
+  blue `#007ec6`; coverage is red `#e05d44` below the input `coverage-warn`
+  (default `60`), yellow `#dfb317` from there to below `coverage-good`
+  (default `80`) and green `#44cc11` from `coverage-good`. Each file has
+  `role="img"`, a `<title>` and an `aria-label` with the same text, a width
+  computed from the number of characters (no font is measured) and no
+  timestamp, script or external reference, so the same numbers give the same
+  bytes.
+- **Publishing.** The `badges` branch holds only the three SVG files and
+  `code-metrics.json`; the script creates it as an orphan branch when it does
+  not exist. It writes the files, and when none differs from the branch it
+  commits nothing and says so; otherwise one commit, message
+  `Update code metrics badges [skip ci]`, changes only those files. The
+  commit is made with the token of the run, which does not start another run;
+  the guide tells a caller to start the workflow on pushes to its default
+  branch only.
+- **Inputs.** `working-directory` (default `.`), `exclude` (default empty),
+  `coverage-report` (default empty), `coverage-artifact` (default empty),
+  `coverage-warn` (default `60`),
+  `coverage-good` (default `80`), `badges-branch` (default `badges`) and
+  `tools-ref` (default `v1`; pin it to the same exact tag as the workflow).
+  There is no tool version input: the tools are files of this repository and
+  Python 3 of the runner.
+- **Pass, fail, empty.** The run passes when the badges were written or were
+  already current. It fails with a `[configuration]` message that names the
+  input and the value for an input that is invalid (a threshold that is not a
+  number from 0 to 100, `coverage-warn` above `coverage-good`, a
+  `working-directory` that is not a directory, a branch name that is not a
+  valid branch name) and for a coverage report as above. A repository with no
+  code file passes with a notice and badges that show `0`.
+- **Not in the first version:** a badge per language (the JSON holds the
+  numbers), lcov and other report formats, branch or function coverage, and
+  counting only tracked files.
+
+## Consequences
+
+**Positive:**
+
+- No tool is installed and nothing is downloaded: a run needs only the
+  checkout, Python 3 and the instance, so the counter and the renderer are
+  fully testable offline with fixtures.
+- The same input gives the same bytes, so an unchanged repository produces no
+  commit and the `badges` branch history is the history of the numbers.
+- The badges have stable URLs on the instance and on the mirror, and nothing
+  on the default branch changes.
+- A broken or missing report is a failure that names the file, never a
+  misleading `0%`.
+
+**Negative:**
+
+- The counter knows only the listed languages and simple scanning rules; some
+  string forms are mis-counted (stated above), and results will differ a
+  little from `cloc` or `tokei`.
+- The workflow needs `contents: write`, which is more than the
+  `contents: read` of the quality checks; a caller that grants less cannot use
+  it. The write is limited to the `badges` branch by the script, not by the
+  host.
+- A caller must run its tests and produce a Cobertura XML report in an
+  earlier job and upload it as an artifact; other formats need a conversion
+  until a later release adds them. The download needs the artifact service
+  of the instance to serve a called workflow, which task 8 of MIL-010
+  verifies.
+- A fixed set of thresholds and colours; a caller can move the two thresholds
+  only.
+- Security: the script runs with a token that can write to the repository.
+  The files are ours and no code is downloaded (the artifact is a report that
+  is parsed as XML with entity declarations refused), but a caller that pins
+  `tools-ref` to a moving ref takes later changes of the script; the guide
+  says to pin the exact tag. The script writes only the four named files, and
+  the branch name input is validated so that it cannot name the default branch
+  (`main`, `master`) or a branch of the caller's code.
+
+## Affected Artifacts
+
+- [MIL-010] — decides its criterion 2 and unlocks tasks 4 to 6.
+- [UC-008] — the use case this workflow serves.
+- [US-001] — US-001.18 to US-001.20 state their acceptance criteria.
+- [ADR-0005] — the contract style that this decision follows, unchanged.
+- [ADR-0006] — adding a language, or changing a colour or a default, is a
+  release under its rules; raising a default threshold is breaking.
+
+
+## Amendment (MIL-011)
+
+The default of the input `tools-ref` in the code metrics contract is the current major tag, defined once in the file
+`MAJOR_TAG` of this repository (`v2` from release 2.1.1), and no longer `v1`. A default must
+name a tag that holds the script the workflow runs; a test checks it. Callers at `@v1` are
+not affected: the `v1` tag keeps the `v1` workflow files.
+
+---
+
+[MIL-010]: ../milestones/mil-010-code-metrics-badges.md
+[UC-008]: ../uc-008/uc.md
+[US-001]: ../user-stories.md
+[ADR-0005]: ./adr-0005-quality-check-contract.md
+[ADR-0006]: ./adr-0006-release-process-and-version-pinning.md
+[0dc5132]: https://git.tirsystem.com/TirSystem/github-action/commit/0dc5132a2ea419ba05035ee3594cec63335c240b
+[eaa0e30]: https://git.tirsystem.com/TirSystem/github-action/commit/eaa0e30beaa097dfeb1c07c814a71d02a6987060

docs/adr/adr-0011-vpn-composite-actions.md

@@ -0,0 +1,68 @@
+# ADR-0011: A VPN for deployment is delivered as a composite action
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | ADR-0011 |
+| CrossReference | [MIL-012], [ADR-0005], [ADR-0006] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-19 | Proposed | Jens Tirsvad Nielsen | S01 | Initial version | [3325bea] |
+
+Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`.
+
+---
+
+## Context
+
+A deployment job often has to reach hosts that are not on the internet. [MIL-012] adds a way to bring a VPN up in the job, for WireGuard and for Tailscale. The GitHub marketplace has `tailscale/github-action` for Tailscale; it is written for GitHub Actions, has not been verified on Gitea Actions, and WireGuard has no such action. Every other shared automation of this repository is a reusable workflow ([ADR-0005], [ADR-0009], [ADR-0010]), so the question is whether a VPN is one too.
+
+Options:
+
+1. **A reusable workflow.** Consistent with the rest of the repository. But a called workflow runs as a separate job, on its own runner and network; a tunnel brought up there is gone when that job ends and is never seen by the caller's deployment job. It cannot work.
+2. **The marketplace action `tailscale/github-action`.** No code to maintain. Written for GitHub, not verified on Gitea, nothing for WireGuard, and an action from outside the instance that receives the VPN secret.
+3. **A composite action of this repository**, one for each VPN, in `actions/<name>/`, called as a step of the caller's own job with `uses:` and `gitea.action_path` for its script. It runs in the job, so the tunnel is there for the steps after it.
+
+Facts: a composite action in a subfolder of this repository resolves on the instance in both the short form (`TirSystem/github-action/actions/<name>@<ref>`) and with the full address, and `gitea.action_path` points at its folder (verified in [MIL-012] task 1, runs 417 and 418 of the instance). A key must not reach a log or a command line. A tunnel needs a network interface, so the runner container needs `NET_ADMIN` and `/dev/net/tun`, which this repository cannot give.
+
+## Decision
+
+A VPN for deployment is delivered as **a composite action of this repository**, one per VPN: `actions/connect-wireguard` and `actions/connect-tailscale`.
+
+- Each action has a script file next to its `action.yml` that does the work. The `run:` lines only call it, and every input reaches the script as an environment variable, never as an interpolated expression ([ADR-0005]).
+- Each action has an `up` and a `down` mode. The caller runs `down` in a last step with `if: always()`.
+- Secrets are masked first, written only to a file of mode 600 where a file is needed, never printed and never put on a command line.
+- The scripts are linted (shellcheck and shfmt) and tested offline with stub commands on every pull request.
+- The actions are versioned with the repository ([ADR-0006]); a new action is a minor release, and callers pin the tag.
+- The runner is outside the scope of the action: the operator (S03) provides a runner whose container has `NET_ADMIN` and `/dev/net/tun`. The actions state the requirement and fail with a message that names it.
+
+## Consequences
+
+**Positive:**
+
+- The tunnel lives in the job that deploys, which a reusable workflow cannot do.
+- One implementation for Gitea, covered by offline tests; no GitHub-only action receives the VPN secret.
+- WireGuard and Tailscale share one contract (`up`, `down`, a health check, masked secrets, categorised errors).
+
+**Negative:**
+
+- Two scripts to maintain, and behaviour that stubs cannot show (daemon start-up, `sudo`, the runner's capabilities) is verified only by runs on a real runner ([MIL-012] tasks 3 and 4).
+- A composite action cannot declare a post step, so the caller must remember the `down` step; a cancelled job can leave a node or a key file behind until the runner cleans up.
+- The action needs a privileged runner, which widens the attack surface of that runner; the guides tell the operator to keep it to a dedicated label.
+
+## Affected Artifacts
+
+- [MIL-012] — the decision behind its deliverable and its tasks 3 and 4.
+- [ADR-0005] — the same contract style (script file, environment variables, categorised failures) is used for the actions.
+- [ADR-0006] — a new action is a minor release.
+
+---
+
+[MIL-012]: ../milestones/mil-012-vpn-actions-for-deployment.md
+[ADR-0005]: ./adr-0005-quality-check-contract.md
+[ADR-0006]: ./adr-0006-release-process-and-version-pinning.md
+[ADR-0009]: ./adr-0009-wiki-publishing-reusable-workflow.md
+[ADR-0010]: ./adr-0010-code-metrics-badges-contract.md
+[3325bea]: https://git.tirsystem.com/TirSystem/github-action/commit/3325bea772304b54e8dfffad592b4afadc3ec2b8

docs/adr/adr-0012-english-comment-detection.md

@@ -0,0 +1,89 @@
+# ADR-0012: How a comment is judged not to be English
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | ADR-0012 |
+| CrossReference | [MIL-013], [ADR-0005], [ADR-0010] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-19 | Proposed | Jens Tirsvad Nielsen | S01 | Initial version | pending |
+
+Allowed Status values: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded by ADR-NNNN`.
+
+---
+
+## Context
+
+[MIL-013] adds a check that fails a pull request when a comment in its source code is not written in English. A comment is short (most have three to twelve words), is full of identifiers, paths and option names, and Danish and Malay words are often close to English ones. The method has to be offline (no source text leaves the instance, criterion 6 of the milestone), small enough to install on every run, deterministic (the same comment gives the same answer on every run), and measured on a corpus, not chosen by taste (criterion 1: recall at least 90 % for Danish and Malay, at most one false positive per 200 English comments).
+
+**Corpus** (`tests/fixtures/comments/`): 300 English comments taken from this repository (`english.tsv`: comments and first docstring lines of `tools/`, `tests/`, `actions/` and the workflows, including fragments, paths and option names), and 138 comments in other languages written for the purpose (`foreign.tsv`): 45 Danish, 45 Bahasa Malaysia, and 12 each of German, Swedish, Norwegian and French. The foreign comments are written by the AI, not collected from real code (the TirSystem repositories have none) and not checked by a native reader. They are typical code comments of three to fifteen words, some with identifiers.
+
+**Methods compared** (`tests/fixtures/comments/compare_detectors.py`; Python 3.13):
+
+1. A rule-based one: letters outside English (`æ ø å ä ö ü ß é ...`) and word lists for English, Danish, Malay and others.
+2. `langdetect` 1.0.9, a port of Google's detector (random start unless the seed is fixed).
+3. `langid` 1.1.6, restricted to the candidate languages (`en da no sv de fr ms id nl`).
+4. `lingua-language-detector` 2.2.0, restricted to the same candidates.
+
+**Results** on the corpus, as the number of comments flagged as not English:
+
+| Method | Danish | Malay | Other (48) | English flagged (of 300) | Install size | Time per 438 comments |
+| --- | --- | --- | --- | --- | --- | --- |
+| Rule-based (word lists written after the corpus, so optimistic) | 42/45 | 26/45 | 39/48 | 0 | none | 0.01 s |
+| `langdetect`, probability at least 0.8 | 41/45 | 42/45 | 47/48 | 14 | 1 MB | 1.45 s |
+| `langid`, no threshold | 45/45 | 45/45 | 48/48 | 2 | 2 MB and `numpy` | 0.02 s |
+| `lingua`, confidence at least 0.5 | 29/45 | 41/45 | 47/48 | 0 | 170 MB wheel | 0.14 s |
+
+Lowering the `lingua` threshold trades one error for the other: at 0.4 it flags 36/45 Danish and 2 English, at 0.2 it flags all Danish and Malay and 14 English. Raising the `langid` threshold on its normalised probability does the same (`0.5`: one English comment flagged; `0.6`: none).
+
+The two English comments `langid` flagged without a threshold are lines that are mostly a script name and an option (`connect-tailscale.sh mask print ::add-mask:: for every secret input`). A pre-filter that removes tokens that are not words (paths, options, `::` tokens, tokens with digits or underscores, camelCase) and refuses to judge fewer than three words lowers the language signal of such lines, but it made the result worse at a threshold of 0.5 (three English comments flagged), so the threshold and the pre-filter go together:
+
+| `langid` with the pre-filter | Danish | Malay | Other (48) | English flagged | English not judged (under 3 words) |
+| --- | --- | --- | --- | --- | --- |
+| probability at least 0.5, 3 words | 45/45 | 45/45 | 48/48 | 3 | 35 of 300 |
+| probability at least 0.6, 3 words | 44/45 | 41/45 | 48/48 | 0 | 35 of 300 |
+
+## Decision
+
+A comment is judged **not English** when `langid` 1.1.6, restricted to `en da no sv de fr ms id nl`, with normalised probabilities, ranks a language other than English first with a probability of at least **0.6**, after this pre-filter, and only when the filter leaves **at least three words**:
+
+- drop every token that is not a word: a token with a code character (`/ \ { } [ ] " ` = < > | $ @ # % & + ^ ~ *`), an underscore, a digit or `::` (a path, a URL, a JSON key, an identifier); a token that starts with `-` (an option), contains `.` (a file name), is written in capitals (an acronym or a constant) or is camelCase; a leading label such as `Usage:` or `Note:`; and the words of the allowed-words file. Split what is left on `-`;
+- keep a token only if it is letters, with at most one inner apostrophe (letters include `æ ø å ä ö ü` and the other letters of Latin scripts);
+- a block of several consecutive comment lines is judged **line by line first**, each line only with at least four words and a probability of at least 0.7, so an English line cannot hide a Danish one next to it (the first version judged the joined block and missed exactly that case in the trial of [MIL-013] task 8); when no line is flagged, the joined block is judged with the values above, so a sentence cut over short lines is not missed. A single comment line is judged once, with the values above;
+- a comment with fewer than three words left is **not judged** (it passes), and so is a comment that holds only identifiers, URLs or numbers.
+
+On the corpus this gives 0 false positives in 300 English comments, Danish 44/45 (97.8 %), Malay 41/45 (91.1 %), and 48/48 for the other languages, meeting criterion 1 of [MIL-013]. The threshold, the minimum of three words and the candidate languages are inputs of the workflow with these values as defaults; the rates are a test that fails when the code changes them (task 7).
+
+The versions are pinned (`langid==1.1.6`, `numpy` at a pinned version) and installed in the job's virtual environment like the other tools ([ADR-0005]). Nothing is downloaded at run time and nothing is sent to a service.
+
+The rules of the pre-filter came from the build, not from the first measurement. A scan of this repository with the first version of the filter found two false positives that the corpus did not contain: a docstring with a JSON example (`{"files": 3, "lines": 120, ...}`, judged French with probability 1.0) and `Usage:` lines with options and a file name (judged French with 0.6 and 0.88). The code-character, option, file-name, acronym and label rules above remove them; the corpus rates stayed the same, and the repository (31 source files) now gives no finding. Tests of the check keep both cases (the JSON docstring and the `Usage:` lines), so a change to the filter is measured against them.
+
+## Consequences
+
+**Positive:**
+
+- Offline, deterministic, about 2 MB plus `numpy`, 0.06 s per 1 000 comments; no model download.
+- The cases that matter most for TirSystem (Danish and Malay) are caught at or above the milestone's bar, and the rule is explainable to an author: "these words look Danish".
+
+**Negative:**
+
+- **The rates are an estimate, not a guarantee.** The foreign comments were written by the AI and are not checked by a native reader, the threshold and the filter were chosen on the same corpus they are measured on, and the English comments come from one repository. Real Danish and Malay comments will differ; the corpus must grow with every miss or false positive found in use (the allowed-words file and the exception marker of the workflow are the answer to a false positive in the meantime).
+- Malay recall of 91.1 % leaves little margin over the bar of 90 %; short Malay comments and comments with many English technical terms are the cases it misses.
+- A short comment (under three words after the filter) is never judged, so a Danish "TODO: ret" passes. This is the price of a low false positive rate.
+- `langid` is not actively developed (its last release is 1.1.6). It is pinned, and `lingua` is the recorded alternative (better on long text, much larger, and weaker on short Danish at a comparable false positive rate).
+- The method judges the language of words, not the quality of English: a comment in poor English passes.
+
+## Affected Artifacts
+
+- [MIL-013] — the decision behind tasks 3, 4 and 7, and criterion 1.
+- [ADR-0005] — the tools are pinned and installed in the job's environment, like the quality-check tools.
+- [ADR-0010] — the comment scanner of the code counter is reused to extract the comments.
+
+---
+
+[MIL-013]: ../milestones/mil-013-english-comments-check.md
+[ADR-0005]: ./adr-0005-quality-check-contract.md
+[ADR-0010]: ./adr-0010-code-metrics-badges-contract.md

docs/artifact-registry.md

@@ -10,13 +10,13 @@ each document lives in *this* project and the next version to use.
 | BC | Business Case | docs/business-case.md | 002 |
 | SA | Stakeholder Analysis | docs/stakeholder-analysis.md | 002 |
 | PP | Project Plan | docs/project-plan.md | 002 |
-| MIL | Milestone / Gateway | docs/milestones/*.md | 009 |
-| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 062 |
+| MIL | Milestone / Gateway | docs/milestones/*.md | 014 |
+| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 086 |
 | TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 |
-| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0010 |
+| ADR | Architecture Decision Record | docs/adr/adr-NNNN-*.md | 0013 |
 | UCD | Use Case Diagram | docs/use-case-diagram.md | 002 |
 | US | User Story | docs/user-stories.md | 002 |
-| UC | Use Case | docs/uc-NNN/uc.md | 008 |
+| UC | Use Case | docs/uc-NNN/uc.md | 009 |
 
 ## Languages
 

docs/business-case.md

@@ -9,8 +9,8 @@
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
-| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | A mirrored repository has at most one GitHub push mirror; repositories without one are skipped | [0c06789] |
-| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Scope: wiki pages in English, Danish and Bahasa Malaysia | [08ef26a] |
+| 2026-10-19 | Deprecated | Jens Tirsvad Nielsen | S01 | Objective O6, scope item, assumption, constraint and success criterion 6: shared actions that bring a VPN up for a deployment job (MIL-012); reviewed (RC-081), accepted by the author in chat as stand-in for S01 | [c5d5941] |
+| 2026-10-19 | Accepted | Jens Tirsvad Nielsen | S01 | Objective O7, scope item, assumption, constraint and success criterion 7: a shared workflow that checks that the comments in source code are in English (MIL-013); reviewed (RC-084), accepted by the author in chat as stand-in for S01 | [e35b1c5] |
 
 ---
 
@@ -59,6 +59,15 @@ made once.
   diagnosis for every workflow.
 - **O4:** Offer shared quality-check and release workflows, versioned so
   consumers can adopt changes deliberately.
+- **O5:** Offer a shared workflow that counts the code files and the lines of
+  code (without comment and blank lines) of a repository, reads its coverage
+  report and publishes the three results as SVG badges.
+- **O6:** Offer shared, versioned actions that bring a VPN (WireGuard or
+  Tailscale) up for a deployment job on a Gitea runner, so the job can reach a
+  private network.
+- **O7:** Offer a shared workflow that checks that the comments in the source
+  code of a pull request are written in English, blocks the pull request when
+  they are not, and tells its author which comment and why.
 
 ## Scope
 
@@ -68,6 +77,9 @@ made once.
 - Documentation for DevOps professionals and software engineers.
 - A Gitea wiki with the same documentation in English, Danish and Bahasa Malaysia (MIL-005).
 - Validation of workflow files and their documentation.
+- A shared workflow for code metrics and coverage badges (MIL-010).
+- Shared composite actions that connect a deployment job to a private network through WireGuard or Tailscale (MIL-012).
+- A shared workflow that checks that comments in source code are in English and tells the author (MIL-013).
 
 ### Out of Scope
 
@@ -104,6 +116,9 @@ accepted plans.
 | 2 | Canonical copies per workflow | 1 | Count of files per workflow name |
 | 3 | Documented use cases that are implemented or marked planned | 100% | README capability table against workflows present |
 | 4 | Repositories consuming a shared workflow | At least 1 besides this one by MIL-002 | Consumer list in README |
+| 5 | Repositories that show the code metrics and coverage badges from the shared workflow | At least 1 besides this one by MIL-010 | README of the consuming repository |
+| 6 | VPN actions that connect a deployment job on the instance, with no secret in the run log | 2 (WireGuard and Tailscale) by MIL-012 | Recorded runs of MIL-012 tasks 3 to 5 |
+| 7 | Comments in source code that are not in English and reach the default branch of a repository that calls the check | 0 after MIL-013 | The check's run on the default branch; a throwaway pull request with a finding that cannot be merged |
 
 ## Risks
 
@@ -119,11 +134,15 @@ accepted plans.
 - The Gitea instance has Actions enabled and an `ubuntu-latest` runner with `python3`.
 - A mirrored repository has at most one GitHub push mirror. Repositories without a GitHub mirror are skipped successfully.
 - S01 (Product Owner) and S05 (DevOps owner and security authority) are both maintainers.
+- For the VPN actions (MIL-012), S03 provides a runner whose container has the capability `NET_ADMIN` and the device `/dev/net/tun`, and the test peers; the actions do not configure the runner.
+- For the English-comments check (MIL-013), S03 provides a Gitea token that may comment on pull requests, as an organization secret, and S01 or S03 decide which repositories mark the check as required; the workflow does not change branch protection.
 
 ## Constraints
 
 - Workflows use only tools available on the runner; the current workflow uses the Python standard library only.
 - Secrets are supplied as repository or organization secrets, never committed.
+- A VPN key or token never appears in a log, an artifact or a command line (MIL-012).
+- The English-comments check (MIL-013) runs without sending source text to a service outside the instance, and its token never appears in a log.
 - Nothing is written under `src/` or `tests/` before the matching milestone is accepted.
 
 ## Cost–Benefit Assessment
@@ -149,5 +168,5 @@ Proceed — the first milestone fixes a known defect in the only existing workfl
 ---
 
 [SA-001]: ./stakeholder-analysis.md
-[0c06789]: https://git.tirsystem.com/TirSystem/github-action/commit/0c06789a2779382672712cd483f4964b28a0ebe9
-[08ef26a]: https://git.tirsystem.com/TirSystem/github-action/commit/08ef26a6d3eb98c066b45634c2271e578e6c0a0b
+[c5d5941]: https://git.tirsystem.com/TirSystem/github-action/commit/c5d59418698316866807388bf61dcb6166d9fa8b
+[e35b1c5]: https://git.tirsystem.com/TirSystem/github-action/commit/e35b1c56748a50430503f5518602469f93262357

docs/milestones/mil-009-migrate-wiki-callers-and-remove-scoped-workflow.md

@@ -0,0 +1,109 @@
+# MIL-009: Migrate the wiki callers and remove the scoped workflow
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | MIL-009 |
+| CrossReference | [BC-001], [MIL-008], [ADR-0004], [ADR-0006], [ADR-0009] , [RC-066] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-14 | Deprecated | Jens Tirsvad Nielsen | AI as stand-in for S01 | Plan accepted in chat with the defaults: target date 2026-11-30 confirmed, `027-sandbox` and `028-pomodoro` do not publish, framework release 0.7.0; reviewed (RC-064) | [2f267df] |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Verification results recorded for tasks 1 to 8; outcome reviewed (RC-066) | [95abc18] |
+
+---
+
+## Purpose
+
+Decide whether the scoped `publish-wiki.yml` can be removed: every repository
+that publishes its wiki through it has moved to `docs/wiki/` and calls the
+reusable workflow `publish-wiki-pages.yml`, and ADR-0004 is superseded by
+ADR-0009. MIL-008 deprecated the scoped workflow and kept it because seven
+repositories still depended on it (checked on 2026-10-13).
+
+## Deliverable
+
+A released framework with the caller template; each of the seven repositories
+publishing its wiki from `docs/wiki/` through a caller, with its marker removed;
+the scoped workflow, its marker code path, its tests and every mention of the
+marker as an opt-in removed; ADR-0004 marked superseded; and the major release
+2.0.0 with the tag `v2`.
+
+## Go / No-Go Criteria
+
+| # | Criterion (objectively checkable) | Go | No-Go |
+| --- | --- | --- | --- |
+| 1 | The framework is released as 0.7.0 with `templates/ci/publish-wiki.yml` and `process/wiki.md`, as a tag | The tag exists and each migrating repository pins it | No tag, or a repository pins an unmerged commit |
+| 2 | Each of the seven repositories publishes from `docs/wiki/` through a caller of `publish-wiki-pages.yml`, and has no `wiki/.publish` | A scan of the instance lists the seven with a caller and no marker | Any marker or missing caller remains |
+| 3 | The wiki of each of the seven equals its `docs/wiki/` after the first run | 0 differences read back through the API for each | A difference, or a failed run |
+| 4 | A scan of every repository of the four organisations finds no `wiki/.publish` and no run of the scoped workflow that wrote | None found | Any found |
+| 5 | The scoped `publish-wiki.yml`, the marker code path of `tools/publish_wiki.py`, their tests and the marker text of the guides, README and wiki pages are removed | Offline tests pass; a search finds no `wiki/.publish` outside the changelog and ADRs | A mention remains, or a test fails |
+| 6 | ADR-0004 is `Superseded by ADR-0009` with a review record, and ADR-0009 links back | Both rows and RC present | Missing |
+| 7 | Release 2.0.0 is published with a Breaking entry, `v2` points to it, and `v1` still points to 1.2.2 | Tags read back through the API | `v1` moved, or no Breaking entry |
+
+## Dependencies
+
+| Depends on | Reason |
+| --- | --- |
+| MIL-008 | Provides the reusable workflow, the deprecation and the list of repositories |
+| `TirSystem/sqa-qc-framework` release | The caller template and `process/wiki.md` must be a tag before a repository pins them |
+
+## Traceability
+
+| Business Case objective / KPI / user story | Reference |
+| --- | --- |
+| O2, O3 | [BC-001] |
+
+## Ownership
+
+| Role | Stakeholder ID (SA) |
+| --- | --- |
+| Owner | S05 |
+| Approving reviewer | S01 |
+
+## Target Date
+
+2026-11-30 — confirmed on 2026-10-14 by S01 in chat; the Business Case sets no deadline.
+
+## Tasks
+
+| # | Task | Summary | Needs its own Use Case/User Story? | Reference |
+| --- | --- | --- | --- | --- |
+| 1 | Release the framework | `TirSystem/sqa-qc-framework` has the caller template and `process/wiki.md` merged (pull request 45). Add the changelog entry, tag the release and record the tag. Needed before any repository pins the template. | No | |
+| 2 | Migrate the three TirSystem projects | `sqa-and-qc`, `sqa-qc-framework` and `sqa-qc-checklists`: move `wiki/` to `docs/wiki/`, copy the caller from `templates/ci/publish-wiki.yml`, remove `wiki/.publish`, fix the paths in their generators and documents, move the framework pin to the released tag, one pull request each. Confirm the organisation secret `TOKEN_FOR_GITEA_WIKI` is present. | No | |
+| 3 | Migrate `repo-foundry` | Same steps for `TirSystem-BashScript/repo-foundry` (21 wiki files); the organisation `TirSystem-BashScript` needs its own `TOKEN_FOR_GITEA_WIKI` secret (S03). | No | |
+| 4 | Migrate the three Udemy repositories | Same steps for `021-snake-game`, `024-snake` and `025-weather` of `Tirsvad-Udemy-100-days-of-code` (5 wiki files each). `027-sandbox` and `028-pomodoro`, which have `docs/wiki/` and no marker, do not publish (decided by S01 on 2026-10-14). | No | |
+| 5 | Verify the migration | After each first run read the wiki back and compare it with `docs/wiki/`; then scan the four organisations for `wiki/.publish` and for repositories still publishing through the scoped workflow. Record the results in this milestone. | No | |
+| 6 | Remove the scoped workflow | Delete `.gitea/scoped_workflows/publish-wiki.yml`, the marker path of `tools/publish_wiki.py` (the `WIKI_PRUNE` input becomes required), the tests that cover it and the marker text in the guides, the README and the three wiki languages. Keep the drift test for the remaining scoped workflow. | No | |
+| 7 | Supersede ADR-0004 | Mark ADR-0004 `Superseded by ADR-0009` for the delivery and marker parts (new version row, review record), and make ADR-0009 link back. | No | |
+| 8 | Release 2.0.0 | Breaking entry (a removed workflow and marker); upgrade guide for callers; release through the release workflow; `v2` is created and `v1` stays at 1.2.2. Move the examples in the guides to `@v2` where the guide describes the new major. | No | |
+
+---
+
+## Verification results
+
+Recorded on 2026-10-14 by the autonomous run.
+
+| # | Criterion | Result |
+| --- | --- | --- |
+| 1 | The framework is released as 0.7.0 with the template and `process/wiki.md`, and each repository pins it | Go: tag `v0.7.0` on `70fc558`. `sqa-and-qc`, `repo-foundry`, `021-snake-game`, `024-snake` and `025-weather` pin it; `sqa-qc-framework` and `sqa-qc-checklists` have no `framework/` submodule to pin |
+| 2 | Each of the seven repositories publishes from `docs/wiki/` through a caller and has no `wiki/.publish` | Go: `sqa-and-qc` #168, `sqa-qc-framework` #47, `sqa-qc-checklists` #17, `repo-foundry` #96, `021-snake-game` #29, `024-snake` #46, `025-weather` #31 |
+| 3 | The wiki of each equals its `docs/wiki/` after the first run | Go: 0 differences read back through the API (10, 16, 13, 19, 4, 4 and 4 pages); each first run succeeded |
+| 4 | A scan of every repository of the four organisations finds no `wiki/.publish` | Go: 48 repositories scanned, none found |
+| 5 | The scoped workflow, the marker path, their tests and the marker text are removed | Go with a note: pull request #151; `wiki/.publish` remains only in the changelog, the ADRs, the milestone and review records and the sentence of the upgrading guide that explains the removal |
+| 6 | ADR-0004 is `Superseded by ADR-0009` with a review record, and ADR-0009 links back | Go: RC-065 |
+| 7 | Release 2.0.0 is published with a Breaking entry, `v2` points to it, and `v1` still points to 1.2.2 | Go: `v2.0.0` and `v2` on `6e8e548`, `v1` and `v1.2.2` on `9bf0a2b`; the release page shows the Breaking group |
+
+Things that did not go as planned: the three Udemy pull requests were opened through a script that hit a network timeout once and was repeated; the `repo-foundry` test suite fails two tests on `main` and on the branch alike (pre-existing, not caused by this milestone).
+
+---
+
+[BC-001]: ../business-case.md
+[RC-066]: ../sqa/reviews/rc-066-mil-009-outcome.md
+[MIL-008]: ./mil-008-wiki-reusable-workflow.md
+[ADR-0004]: ../adr/adr-0004-shared-wiki-publishing-opt-in.md
+[ADR-0009]: ../adr/adr-0009-wiki-publishing-reusable-workflow.md
+[ADR-0006]: ../adr/adr-0006-release-process-and-version-pinning.md
+[2f267df]: https://git.tirsystem.com/TirSystem/github-action/commit/2f267df2a270087cb7dc482af4ce4f4341e97b03
+[95abc18]: https://git.tirsystem.com/TirSystem/github-action/commit/95abc18a95d70c065b979123b8f8de22173af90c

docs/milestones/mil-010-code-metrics-badges.md

@@ -0,0 +1,198 @@
+# MIL-010: Code metrics and coverage badges
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | MIL-010 |
+| CrossReference | [BC-001], [US-001], [MIL-003], [MIL-004], [ADR-0005], [ADR-0006] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-14 | Deprecated | Jens Tirsvad Nielsen | AI as stand-in for S01 | Results of tasks 3, 6 and 8 added: the report as an artifact of the caller (ADR-0010), adoption in a throwaway repository with seeded change and failure; reviewed (RC-074) | [5c5a1d1] |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Task 9 results added: released as 2.1.0; outcome reviewed (RC-075) | [aa20e56] |
+
+---
+
+## Purpose
+
+Decide whether a repository can show, as SVG badges, how many code files and
+how many lines of code (without comment and blank lines) it holds and how
+much of that code its tests cover, produced by one shared workflow of this
+repository, without a service outside the instance.
+
+## Deliverable
+
+A reusable workflow `code-metrics.yml` with a script file of this repository
+behind it, which counts the code files and the lines of code, reads the
+coverage report the caller supplies, writes the badges "code files", "lines
+of code" and "coverage" as SVG files and commits them to a `badges` branch of
+the calling repository. It comes with a documented set of inputs, a guide and
+wiki pages in English, Danish and Bahasa Malaysia, a use in at least one other
+repository, and a release that makes it available at the major tag. The
+existing workflows keep their names and contracts.
+
+Decisions taken by the user in chat on 2026-10-14, which the contract of task 2
+records and does not reopen:
+
+- The counter is a Python script of this repository with no dependency outside
+  the standard library (not `cloc`, `tokei` or `scc`).
+- The delivery is a reusable workflow (`workflow_call`), as the quality-check
+  workflows are.
+- The badges are committed to a `badges` branch, so a README can link to
+  them; they are not only a run artifact.
+- Three badges: code files, lines of code and coverage. A badge per language
+  is optional and is decided in the ADR of task 2.
+- The coverage report is read in the Cobertura XML format, which `coverage.py`,
+  `gcovr` and `coverlet` all write; the counter does not run tests itself, so a
+  caller that wants a coverage badge runs its tests first and passes the path
+  of the report.
+
+## Go / No-Go Criteria
+
+| # | Criterion (objectively checkable) | Go | No-Go |
+| --- | --- | --- | --- |
+| 1 | A job on the runner of the instance can push a commit to a `badges` branch of its own repository with the token the run provides, and the SVG renders as an image in a README on the instance and on the GitHub mirror, verified and recorded | Both render | The push needs a token with more than the contents of its own repository, or the image does not render |
+| 2 | The contract (what a code file is, what a comment and a blank line are for each language, excluded paths, generated and vendored files, the coverage report format, the badge colours and text) is decided in an ADR | ADR accepted | Open |
+| 3 | The counter gives the hand-counted numbers (files, code, comment, blank) for a fixture of each supported language, including a block comment, a trailing comment, a comment marker inside a string and a file with no final newline | Equal for every fixture | Any difference |
+| 4 | The coverage reader gives the percentage of the fixture reports, and a missing or malformed report is a failure that names the file, never a badge showing 0% | Verified | A bad report produces a badge |
+| 5 | The badges are valid SVG, carry a title and a text alternative, have a fixed width per text, and are byte-identical for the same input | Verified | Not valid or not stable |
+| 6 | The workflow commits nothing when no badge changed, does not start itself again from its own push, and asks for the least permission that writes to its own repository | Verified in a run | A loop, or a wider permission |
+| 7 | One other repository runs the workflow and its README shows the three badges, with a seeded change that moves the coverage badge to another colour | Shown | Does not run or does not change |
+| 8 | The workflow embeds no script: it runs a file of this repository, and the offline tests exercise the file | Count of embedded scripts is 0 | Embedded script remains |
+| 9 | A release (a minor version) makes it available, and the changelog, the README workflow table and the wiki name it | Released | Unreleased |
+
+## Dependencies
+
+| Depends on | Reason |
+| --- | --- |
+| MIL-003 | The reusable workflow mechanism, the `tools-ref` input and the guide for reading results |
+| MIL-004 | The release process and the release workflow publish the result |
+
+## Traceability
+
+| Business Case objective / KPI / user story | Reference |
+| --- | --- |
+| O5 (added to the Business Case in the same change as this milestone) | [BC-001] |
+| New stories of task 1, to be written in US-001 | [US-001] |
+
+## Ownership
+
+| Role | Stakeholder ID (SA) |
+| --- | --- |
+| Owner | S05 |
+| Approving reviewer | S01 |
+
+## Target Date
+
+2027-01-30 — it follows the last decision of the plan, 2027-01-16, with two
+weeks from 2027-01-18; proposed by the AI and accepted by the user in chat on
+2026-10-14, recorded by the AI as stand-in for S05 (ADR-0002). The Business
+Case sets no deadline.
+
+## Tasks
+
+| # | Task | Summary | Needs its own Use Case/User Story? | Reference |
+| --- | --- | --- | --- | --- |
+| 1 | Write the use case and stories for the metrics badges | Add a use case "Show code metrics and coverage badges" for the software engineer, add it to the use case diagram, and add stories to US-001: the badges appear after a push, a coverage report that is missing or malformed fails with the file named, and nothing is committed when the numbers are unchanged. Each story has a pass and a fail acceptance criterion. Review them with the checklists of the `artifact` skill. | Yes | US-001 |
+| 2 | Decide the contract | Write an ADR with the definitions the counter needs (code file, comment, blank line, per language), the default includes and excludes, the languages of the first version, the Cobertura XML coverage input, the badge texts and colour thresholds, the inputs of the workflow, the name and content of the `badges` branch, and what a pass, a failure and a run without files mean, in the style of ADR-0005. Record the decisions of the Deliverable. | No | |
+| 3 | Verify the delivery on the instance | On a throwaway branch, run a job that commits an SVG to a `badges` branch with the token of the run, then check that the raw URL serves it as an image on the instance, that a README shows it, and that it also shows on the GitHub mirror. Record the result in this milestone like MIL-007 task 2, together with the permission that was needed. | No | |
+| 4 | Implement the counter | Add `tools/count_loc.py` and tests with a fixture per language under `tests/`: file and line counts split into code, comment and blank, an exclude list, and a machine-readable result on standard output. Standard library only, as the rules of the repository for tools say. | No | |
+| 5 | Implement the coverage reader and the badge renderer | Add the reader of the Cobertura XML report and the SVG renderer, with the failure cases of Go/No-Go criterion 4 and a stable output (criterion 5), each with offline tests. | No | |
+| 6 | Implement the workflow | Add the reusable workflow `code-metrics.yml` and its script file, which calls the counter, the reader and the renderer and commits to the `badges` branch as the contract of task 2 says, with least-privilege permissions and offline tests as `quality-checks.yml` has. | No | |
+| 7 | Write the guides and the wiki pages | A guide in `guides/` with the call, the inputs, how to produce a coverage report for Python, C++ and C#, and the Markdown line that shows the badges; the wiki pages in `docs/wiki` in English, Danish and Bahasa Malaysia; the README table and diagram and the wiki Home workflow list (a test requires every workflow to be listed). | No | |
+| 8 | Adopt the workflow in one other repository | Onboard a real repository, or a throwaway one when none fits, show the badges in its README and verify a seeded change that moves the coverage badge. Fix the gaps in the guide that appear. | No | |
+| 9 | Release | Add the changelog entry (a new workflow is a minor change, ADR-0006) and run the Release workflow; record the results in this milestone and review it. | No | |
+
+## Verification results
+
+Task 3 was run on 2026-10-14 with a throwaway branch, `verify-badges-delivery`,
+in `TirSystem/github-action` (run 1418, success). One job on `ubuntu-latest`
+with `permissions: contents: write` checked the repository out, created an
+orphan branch `badges-verify` with one SVG file and a commit message ending in
+`[skip ci]`, and pushed it with the token of the run (the credential that
+`actions/checkout` stores); it then requested the raw URL.
+
+| Fact | Result |
+| --- | --- |
+| Push with the token of the run | Accepted: `git push origin HEAD:refs/heads/badges-verify` created the branch; no secret and no personal access token was needed |
+| Raw URL on the instance | `https://git.tirsystem.com/TirSystem/github-action/raw/branch/badges-verify/code-files.svg` answers `200`, `Content-Type: image/svg+xml`, `Content-Security-Policy: default-src 'none'; style-src 'unsafe-inline'; sandbox`, `Cache-Control: public, max-age=21600` (six hours) |
+| The branch on the GitHub mirror | The push mirror (`sync_on_commit`, every 8 h otherwise) copied the branch within seconds; `https://raw.githubusercontent.com/TirSystem/github-action/badges-verify/code-files.svg` answers `200`, `Content-Type: image/svg+xml`, `Cache-Control: max-age=300` |
+| Repository visibility | Public; a README image on GitHub reads the raw URL, which needs no token |
+
+The SVG is served as an image on both hosts, so it renders in a README on the
+instance and on the mirror; the content security policy rules out script and
+external references inside the file, as ADR-0010 requires. The six-hour
+cache on the instance means a changed badge can show the old number for up to
+six hours there; the guide says so. Not covered by this task: a private
+repository (the raw URL then needs a login, so a badge does not render for an
+anonymous reader), and the rendering inside a Gitea README, which is the same
+`<img>` request. The throwaway branches `verify-badges-delivery` and
+`badges-verify` are left in place because deleting a branch is an action the
+run stops on; they are listed in the summary for the user to delete.
+
+Task 6 changed the contract once while it was implemented. A called workflow
+runs in its own job, so it cannot read a report that the caller's test job
+wrote in its workspace; a report the repository commits is the only file it can
+see. ADR-0010 was amended (RC-073): the caller uploads the report as an
+artifact and names it in the new input `coverage-artifact`; the workflow
+downloads it with `actions/download-artifact` into the directory
+`coverage-artifact` and `coverage-report` names the file inside it. The scope
+and the three badges did not change.
+
+Task 8 was run on 2026-10-14 in a throwaway private repository of the
+organisation, `TirSystem/code-metrics-adoption` (no repository of a project
+fits, and the user's plan allows a throwaway). It holds a two-file Python
+module with tests and a workflow of two jobs: the tests with `pytest-cov`
+upload `coverage.xml` as the artifact `coverage`, and the second job calls
+`code-metrics.yml` and `tools-ref` of the branch `mil-010-implementation` of
+this repository, before its merge.
+
+| Step | Result |
+| --- | --- |
+| Baseline (run 1423) | All steps pass, including `Download the coverage report` with `actions/download-artifact@v4.1.8` on Gitea 1.27.3; the `badges` branch is created with one commit by `code-metrics` and the message `Update code metrics badges [skip ci]`; `code-files.svg` shows 2, `code-lines.svg` 28 (the hand count of the two files), `coverage.svg` 100% in green `#44cc11` |
+| The push of the badges | No run was started by it: the runs of the repository are the two of the push to `main` (the metrics workflow and the scoped sync) |
+| Seeded change (run 1425): two tests removed | The coverage badge reads 60% in yellow `#dfb317`; one new commit on `badges` that changes the badge files; the files and the lines badges changed with the tests |
+| Seeded failure (run 1429): `coverage-report` names a file that does not exist | The job `code-metrics` fails: `::error::[configuration] coverage-report 'coverage-artifact/nope.xml' does not exist.`; `badges` is unchanged (two commits) |
+| README | Its three Markdown images render as `<img>` of the raw URLs of the `badges` branch (checked with the markdown API of the instance); the raw URLs answer `image/svg+xml` as in task 3 |
+
+Not covered: a run that changes nothing (the unchanged case is covered by the
+offline tests, not by a run), two runs that write the branch at the same time
+(covered by an offline test with a rejecting remote, not on the instance), the
+rendering for a reader who is not signed in to a private repository, and a
+repository of a project with a real coverage report. The throwaway repository
+`TirSystem/code-metrics-adoption` is left in place because deleting a
+repository is an action the run stops on; it is listed in the summary for the
+user to delete.
+
+Task 9 was run on 2026-10-14. The implementation was merged in pull request
+164 after its checks were green; the user merged it, because the host refused
+the merge through the API with a required check `Publish wiki / *` that the
+branch protection API does not list and that nothing in this repository
+reports. The Release workflow was run for 2.1.0 on the merge commit
+`16faffa`: a dry run (run 1462) and then the release (run 1463), both green.
+
+| Check | Result |
+| --- | --- |
+| Tag | `v2.1.0` and the moved major tag `v2` both point at `16faffa` |
+| Release page | `v2.1.0`, not a draft, with the changelog entry as its text (`Added`: the workflow `code-metrics.yml`) |
+| Callable at the major tag | `.gitea/workflows/code-metrics.yml` and `tools/count_loc.py` are served at `v2` and `v2.1.0` |
+| Checks on `main` after the merge | validation, milestone publishing, wiki publishing and the metadata sync all green (runs 1458 to 1461) |
+
+Go/No-Go criteria of this milestone at its close: 1 to 8 as in the results
+above; 9 (a release makes it available, and the changelog, the README table and
+the wiki name it) is met by the release of 2.1.0. Success criterion 5 of the
+Business Case (a repository besides this one shows the badges) is met in a
+throwaway repository only; a project repository has not adopted it yet.
+
+---
+
+[BC-001]: ../business-case.md
+[US-001]: ../user-stories.md
+[MIL-003]: ./mil-003-quality-checks.md
+[MIL-004]: ./mil-004-versioned-release.md
+[ADR-0005]: ../adr/adr-0005-quality-check-contract.md
+[ADR-0006]: ../adr/adr-0006-release-process-and-version-pinning.md
+[5002450]: https://git.tirsystem.com/TirSystem/github-action/commit/50024505fe788b1c5e3021c0d1fc3d079590070e
+[5c5a1d1]: https://git.tirsystem.com/TirSystem/github-action/commit/5c5a1d19d96a6979b4f6141e736957174ba686a9
+[aa20e56]: https://git.tirsystem.com/TirSystem/github-action/commit/aa20e56110f4c2fab91a8432ba008ee8300926a2

docs/milestones/mil-011-code-metrics-default-tools-ref.md

@@ -0,0 +1,127 @@
+# MIL-011: Fix the defaults of the code metrics workflow
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | MIL-011 |
+| CrossReference | [BC-001], [US-001], [MIL-010], [ADR-0010], [ADR-0006] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-14 | Deprecated | Jens Tirsvad Nielsen | S01 | Added the results of task 1 (reproduction and the defaults of the five workflows); reviewed (RC-077), accepted by the AI as stand-in for S01 in autonomous mode | [e11c43f] |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | S01 | Added the results of tasks 2 to 5 (the fix, the test, the guides, the run on the instance); reviewed in RC-078, the release follows; outcome reviewed (RC-079), accepted by the AI as stand-in for S01 in autonomous mode | [a6892c3] |
+
+---
+
+## Purpose
+
+Decide whether the released code metrics workflow can be called with its documented defaults, and correct it if it cannot.
+
+Release 2.1.0 ([MIL-010]) added `code-metrics.yml`. Its guide, its header comment and the default of its `tools-ref` input name `v1`, but the workflow and its scripts (`tools/code-metrics.sh`, `tools/count_loc.py`, `tools/badges.py`) exist only from `v2.1.0`. A caller who follows the guide (`@v1`) cannot resolve the workflow, and a caller at `@v2` that leaves `tools-ref` at its default fetches the scripts from `v1`, where they are absent, so the run fails. The offline tests of [MIL-010] did not see it, because they run the scripts from the checkout and never resolve a ref. The framework wiki page `Badges` works around it by telling callers to set `tools-ref: v2`.
+
+The other four reusable workflows also default `tools-ref` to `v1`; their scripts exist at `v1`, but a default that follows an old major is the same kind of error, so this milestone checks them too.
+
+## Deliverable
+
+A patch release (`2.1.1`, [ADR-0006]) in which: the default `tools-ref` of every reusable workflow names a tag that holds the scripts it runs; the guide, the header comment of `code-metrics.yml`, the upgrading guide, the README and the wiki pages in English, Danish and Bahasa Malaysia call the workflow at `@v2`; a test fails when a default `tools-ref` names a tag without the script; and the changelog has a `Fixed` entry. In `TirSystem/sqa-qc-framework`: the `Badges` wiki page without the `tools-ref` workaround.
+
+## Go / No-Go Criteria
+
+| # | Criterion (objectively checkable) | Go | No-Go |
+| --- | --- | --- | --- |
+| 1 | The defect is reproduced before the fix: a call at the major tag with the defaults fails, and the failure names the missing script, recorded in this milestone | Reproduced and recorded | Not reproduced, or not recorded |
+| 2 | Every reusable workflow's default `tools-ref` names a tag that contains the script file the workflow runs, listed per workflow in this milestone | All five checked and listed | A default names a tag without its script |
+| 3 | The default is derived, not copied: one place gives the current major, and a test fails when a workflow default differs from it or names a tag without the script | Test fails on a seeded wrong default and passes on the fix | No such test |
+| 4 | No guide, comment, README or wiki page tells a caller to use `@v1` for `code-metrics.yml`; a search of `guides/`, `README.md`, `docs/wiki/` and `.gitea/workflows/` finds none | Count is 0 | A page still says `@v1` for it |
+| 5 | A call with the documented defaults runs on the instance and commits the badges to a `badges` branch, verified on a throwaway branch and recorded | Run succeeds | Fails or is not run |
+| 6 | The release is a patch (`2.1.1`): the changelog has a `Fixed` entry, the major tag `v2` moves to it, and `v1` is not touched | Released | Released as another level, or `v1` moved |
+| 7 | The framework `Badges` page no longer tells a caller to set `tools-ref`, in all three languages, and still calls the workflow at `@v2` | Page merged | The workaround remains |
+| 8 | Reviewed | A review record (`RC-*`) for this milestone and the changed workflow, tests and guides, each with a verdict of Go | An instance without a record |
+
+## Dependencies
+
+| Depends on | Reason |
+| --- | --- |
+| [MIL-010] | The workflow and its guide are its deliverables; the defect is in release 2.1.0 |
+| [ADR-0006] | The release process: a fix is a patch release, and a moving major tag follows it |
+
+## Traceability
+
+| Business Case objective / KPI / user story | Reference |
+| --- | --- |
+| Business Case objective O5: a shared workflow that counts the code files and lines of code, reads the coverage report and publishes the three results as SVG badges; the workflow cannot be called as documented until this milestone is done | [BC-001] |
+| User stories | [US-001] (no new story: the tasks below are technical, and the story of [MIL-010] for the badges stays as written) |
+
+## Ownership
+
+| Role | Stakeholder ID (SA) |
+| --- | --- |
+| Owner | S05 |
+| Approving reviewer | S01 |
+
+## Target Date
+
+2026-10-23 (Friday), one week of work: the fix is small and a caller cannot use the workflow until it is released. This precedes the planned decision date of [MIL-010] (2027-01-30) because that milestone was released on 2026-10-14, ahead of its date; the schedule row of [MIL-010] is not changed here. The Business Case sets no deadline.
+
+## Tasks
+
+| # | Task | Summary | Needs its own Use Case/User Story? | Reference |
+| --- | --- | --- | --- | --- |
+| 1 | Reproduce the defect and list the defaults | On a throwaway branch, call `code-metrics.yml` at `@v2` with the defaults and at `@v1`, and record both failures and the message. List, for each of the five reusable workflows, the default `tools-ref` and whether the script it runs exists at that tag. Record the result in this milestone. | No | [MIL-010] |
+| 2 | Fix the defaults | Give the repository one definition of the current major (a file the workflows' tests and the release workflow read), set the default `tools-ref` of every reusable workflow from it, and change the header comment of `code-metrics.yml` to `@v2`. A workflow whose script is at the previous major keeps that tag only with a comment that says why. | No | [ADR-0006] |
+| 3 | Add the test | An offline test that reads every workflow in `.gitea/workflows/`, takes the default `tools-ref` and the script it runs, and fails when the default differs from the current major or the script is not in that tag (checked with `git cat-file` against the tags of the checkout). Show it fails on a seeded wrong default and passes on the fix. | No | [MIL-010] |
+| 4 | Correct the guides, README and wiki | Change `@v1` to `@v2` for `code-metrics.yml` in `guides/code-metrics.md`, `guides/upgrading.md`, `README.md` and `docs/wiki/CodeMetrics.md`, `.da.md` and `.ms.md`; say in the guide that `tools-ref` defaults to the current major. Search the repository for the remaining `@v1`. | No | |
+| 5 | Verify on the instance | On a throwaway branch of a repository, call the fixed workflow at the branch with the defaults, and check that the `badges` branch gets the SVG files. Record the run. | No | [MIL-010] |
+| 6 | Release 2.1.1 | Add the `Fixed` entry to the changelog (ADR-0006: a patch), run the Release workflow, and check that `v2` points at `v2.1.1` and `v1` at `v1.2.2`. | No | [ADR-0006] |
+| 7 | Remove the workaround from the framework page | In `TirSystem/sqa-qc-framework`, remove the `tools-ref: v2` line and the two bullets about it from `docs/wiki/Badges.md`, `Badges-da.md` and `Badges-ms.md`, and add a changelog line. This is a change in another repository, made after release 2.1.1 and in its own pull request. | No | |
+| 8 | Add MIL-011 to the Project Plan | Add the schedule row, the Gantt bar, the scope entry and the dependency to [PP-001], and its review to the traceability matrix. | No | |
+| 9 | Review | Record `RC-*` for this milestone, the workflow and tests, and the guides, each with a verdict. | No | |
+
+## Verification results
+
+Task 1 was run on 2026-10-14 with the throwaway branch `verify-code-metrics-defaults` of `TirSystem/github-action`. It calls `code-metrics.yml` at the two refs a caller could use, with every input at its default.
+
+| Call | Result | Evidence |
+| --- | --- | --- |
+| `...code-metrics.yml@v2`, defaults | Fails in the step "Validate the inputs": `bash: shared-scripts/tools/code-metrics.sh: No such file or directory`, exit code 127. The input `tools-ref` is `v1`, so the scripts are fetched from `v1`. | run 1499, job 1638 |
+| `...code-metrics.yml@v1`, defaults | No run is created at all, and no error is shown: two pushes of a workflow that calls it (once with the `@v2` job beside it, once alone) made no run in over a minute, while the push of the `@v2` call alone made one | commits `5654905` and `46e752d` (no run), `9a17868` (run 1499) |
+
+The defaults of the five reusable workflows at `v2.1.0` (`v1` is `1.2.2`, `v2` is `2.1.0`):
+
+| Workflow | Default `tools-ref` | Script it runs | At the default | At `v2` |
+| --- | --- | --- | --- | --- |
+| `code-metrics.yml` | `v1` | `tools/code-metrics.sh` | **absent** | present |
+| `quality-checks.yml` | `v1` | `tools/quality-checks.sh` | present | present |
+| `quality-checks-cpp.yml` | `v1` | `tools/quality-checks-cpp.sh` | present | present |
+| `quality-checks-csharp.yml` | `v1` | `tools/quality-checks-csharp.sh` | present | present |
+| `publish-wiki-pages.yml` | `v1` | `tools/publish_wiki.py` | present | present |
+
+Only `code-metrics.yml` is broken. The other four resolve, but a caller at `@v2` runs their scripts from `1.2.2` and not from `2.1.0`; `tools/publish_wiki.py` changed in `2.0.0` (it requires `WIKI_PRUNE` and no longer reads a marker). Whether that is a defect is decided in task 2.
+
+
+Tasks 2 to 5 were done on 2026-10-14 on the branch `mil-011-fix`:
+
+- **Fix (task 2):** the file `MAJOR_TAG` holds the current major (`v2`); the default `tools-ref` of the five reusable workflows is `v2`, and the header comment of `code-metrics.yml` calls it at `@v2`. The four workflows other than `code-metrics.yml` followed the older major only by default and changed no behaviour for a caller at `@v1`; for a caller at `@v2` the scripts now come from the same major as the workflow.
+- **Test (task 3):** `tests/test_tools_ref.py` ties `MAJOR_TAG` to the highest major of the changelog and checks every reusable workflow's default and script. With `default: "v1"` seeded in `code-metrics.yml` three tests failed; restored, they pass. The suite passes (540 tests).
+- **Guides (task 4):** `guides/code-metrics.md`, `guides/upgrading.md`, the three quality-check guides, `README.md` and the wiki pages in English, Danish and Bahasa Malaysia; the amendments of ADR-0005, ADR-0008, ADR-0009 and ADR-0010. A search for `code-metrics.yml@v1` finds none.
+- **Instance (task 5):** the workflow at `@mil-011-fix` with every input at its default except `badges-branch` ran as run 1509 (job 1649): `tools-ref` resolved to `v2`, the scripts were fetched, and the badges were committed to `badges-verify` (commit `041d991`).
+
+
+Tasks 6 and 7 were done on 2026-10-14:
+
+- **Release (task 6):** the Release workflow ran in dry-run mode (run 1524) and then for real (run 1525); `v2.1.1` and `v2` are `3023461`, `v1` is unchanged at `9bf0a2b` (1.2.2), and the release page has the changelog entry. A call at `@v2` with the defaults ran after the release (run 1526, job 1670): `tools-ref` resolved to `v2`, the scripts were fetched at `3023461`, and the badges were published.
+- **Framework page (task 7):** `TirSystem/sqa-qc-framework` pull request 57 removed the `tools-ref` workaround from the `Badges` pages in three languages; the wiki is published.
+- **Outcome:** [RC-079], Go, all eight criteria pass.
+
+---
+
+[BC-001]: ../business-case.md
+[US-001]: ../user-stories.md
+[MIL-010]: ./mil-010-code-metrics-badges.md
+[ADR-0010]: ../adr/adr-0010-code-metrics-badges-contract.md
+[ADR-0006]: ../adr/adr-0006-release-process-and-version-pinning.md
+[PP-001]: ../project-plan.md
+[RC-079]: ../sqa/reviews/rc-079-mil-011-outcome.md
+[e11c43f]: https://git.tirsystem.com/TirSystem/github-action/commit/e11c43f0a41e7dd9647f7804947d6e464407a597
+[a6892c3]: https://git.tirsystem.com/TirSystem/github-action/commit/a6892c372aca9f2e12826a4c3b260290a0656ecb

docs/milestones/mil-012-vpn-actions-for-deployment.md

@@ -0,0 +1,129 @@
+# MIL-012: VPN actions for deployment (WireGuard and Tailscale)
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | MIL-012 |
+| CrossReference | [BC-001], [US-001], [MIL-004], [MIL-011], [ADR-0006], [ADR-0011] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-19 | Deprecated | Jens Tirsvad Nielsen | S01 | Initial version; reviewed (RC-080), accepted by the author in chat as stand-in for S01 with target date 2026-11-06 | [c5d5941] |
+| 2026-10-19 | Accepted | Jens Tirsvad Nielsen | S01 | Added the results of tasks 1, 6 and 9 and the fixes from the review of the first pull request; reviewed (RC-082), accepted by the author in chat as stand-in for S01 | [3325bea] |
+
+---
+
+## Purpose
+
+Decide whether a deployment job on a Gitea runner can reach a private network through a shared, versioned action, and release it if it can.
+
+A deployment often has to reach hosts that are not on the internet. The GitHub marketplace has the action `tailscale/github-action` for a Tailscale network; it is written for GitHub Actions and has not been verified on Gitea Actions. WireGuard has no equivalent action at all. Two experimental composite actions for Gitea Actions already exist on the unreleased branch `wireguard-vpn-action` (`actions/connect-wireguard`, `actions/connect-tailscale`), with guides and offline tests (574 tests pass), but neither has run on a real runner, and the one question that decides whether the Tailscale action works is open: whether `tailscaled`, started in the background of one step, is still alive in the next step of the job.
+
+This milestone runs both on a real runner of the instance, fixes what that shows, and releases them. It adds a capability, so it is a minor release ([ADR-0006]).
+
+## Deliverable
+
+Release `2.2.0` of this repository with two composite actions, `actions/connect-wireguard` and `actions/connect-tailscale`, each with a guide, a README section, wiki pages in English, Danish and Bahasa Malaysia, a changelog entry under `Added`, and an offline test. A record of one successful deployment-shaped job per action on the instance. An ADR for the decision to deliver a VPN as a composite action. In `TirSystem/sqa-qc-framework`: the templates `deploy-wireguard.yml` and `deploy-tailscale.yml` pinned to the release tag instead of the branch, in a pull request of their own.
+
+## Go / No-Go Criteria
+
+| # | Criterion (objectively checkable) | Go | No-Go |
+| --- | --- | --- | --- |
+| 1 | A `uses:` of a composite action in a subfolder of this repository (`TirSystem/github-action/actions/<name>@<ref>`) resolves on the instance; the form that works (short, or the full address) is recorded | A run starts and executes the action; the form is recorded | No form resolves |
+| 2 | `connect-wireguard` brings a tunnel up on a runner of the instance, a following step reaches a host behind the tunnel, and the `down` step removes the interface and the file | Recorded run; `wg show` and the file are absent afterwards | The tunnel is not up in the following step, or anything remains |
+| 3 | `connect-tailscale` joins a tailnet on a runner of the instance in TUN mode and in userspace mode, a following step reaches a tailnet host, and `down` leaves no node in the tailnet | Recorded run for both modes; the node list shows no node afterwards | `tailscaled` does not survive to the next step, or a node remains |
+| 4 | No secret appears in any log of the runs above (auth key, OAuth secret, WireGuard keys), checked by a search of the run logs for the secret values | Count is 0 | A secret value appears in a log |
+| 5 | The runner requirements are recorded as verified: the container options, the label, and whether `wireguard-go` or the kernel module was used | Recorded in both guides | A requirement is only assumed |
+| 6 | The scripts of the actions are linted (shellcheck, shfmt) and their tests run on every pull request in `validate-workflows.yml`; a seeded error fails the run | Fails on a seeded error, passes on the fix | Not part of the validation |
+| 7 | The README, both guides and the wiki pages (English, Danish, Bahasa Malaysia) describe the actions at `@v2` and no longer call them experimental; a search of `guides/`, `README.md` and `docs/wiki/` finds no `@wireguard-vpn-action` | Count is 0 | A page still names the branch |
+| 8 | The release is a minor (`2.2.0`): the changelog has an `Added` entry, the major tag `v2` moves to it, and `v1` is not touched | Released | Another level, or `v1` moved |
+| 9 | The framework templates name the release tag, not the branch, in a pull request of `TirSystem/sqa-qc-framework` opened after release 2.2.0 | Pull request open with the tag | A template names the branch |
+| 10 | Reviewed | A review record (`RC-*`) for this milestone, the actions, the tests and the guides, each with a verdict of Go | An instance without a record |
+
+## Dependencies
+
+| Depends on | Reason |
+| --- | --- |
+| [MIL-004] | The release process and the Release workflow that publish `2.2.0` |
+| [MIL-011] | The default `tools-ref` and the `MAJOR_TAG` file; the release is the first after the fix |
+| [ADR-0006] | A new capability is a minor release, and a moving major tag follows it |
+| A runner with `NET_ADMIN`, `/dev/net/tun` and a label of its own (S03) | Both actions need a network interface; outside this repository, set up by the runner's operator |
+| A WireGuard peer and a Tailscale tag with an OAuth client (S03) | Test peers for criteria 2 and 3; secrets held by the operator, never in this repository |
+| `TirSystem/sqa-qc-framework`, branch `ssdf-workflow-selection-vpn` | Holds the templates and the rules that call the actions; criterion 9 changes it in its own pull request |
+
+## Traceability
+
+| Business Case objective / KPI / user story | Reference |
+| --- | --- |
+| Business Case objective O6: a shared, versioned action that brings a VPN up for a deployment job on a Gitea runner | [BC-001] |
+| User stories | [US-001] (no new story: the tasks below are technical; the actions are used by deployment jobs, not by a person) |
+
+## Ownership
+
+| Role | Stakeholder ID (SA) |
+| --- | --- |
+| Owner | S05 |
+| Approving reviewer | S01 |
+
+## Target Date
+
+2026-11-06 (Friday), proposed: two weeks of work from 2026-10-26, because the trials need a runner with extra privileges and test peers that the operator must set up. It overlaps [MIL-002] (2026-10-19 to 2026-10-31), which is documentation and does not touch the runners' network. The Business Case sets no deadline. S01 confirmed the date when accepting this milestone, in chat on 2026-10-19.
+
+## Tasks
+
+| # | Task | Summary | Needs its own Use Case/User Story? | Reference |
+| --- | --- | --- | --- | --- |
+| 1 | Check that a subfolder action resolves | On a throwaway branch of a repository, call `actions/connect-wireguard` and `actions/connect-tailscale` with the short form and with the full address, at the branch. Record which form starts a run and the message when one does not. | No | |
+| 2 | Prepare the trial runner | With the operator: a runner labelled `vpn` whose container has `NET_ADMIN` and `/dev/net/tun`; a WireGuard peer and a host behind it; a Tailscale tag, an OAuth client and a host in the tailnet. Secrets are stored as organization secrets and are not recorded here. | No | |
+| 3 | Verify `connect-wireguard` | Run a deployment-shaped job (connect, reach the host over the tunnel, disconnect with `if: always()`) with a kernel module and with `wireguard-go`. Record the runs and what remains on the runner. Fix the script where it fails and extend the tests. | No | [MIL-012] |
+| 4 | Verify `connect-tailscale` | Run the same job in TUN and in userspace mode. Decide whether `tailscaled` survives to the next step; if it does not, change how it is started (for example `setsid`, or a post step) and test it. Record the node list after the run. | No | [MIL-012] |
+| 5 | Search the logs for secrets | Search every run log of tasks 3 and 4 for the secret values and for the key file path; fix any leak. | No | |
+| 6 | Lint and test the action scripts in CI | Add shellcheck and shfmt for `actions/**/*.sh` and the two test files to `validate-workflows.yml`; show a seeded error fails the run. | No | [MIL-001] |
+| 7 | Remove the experimental notices | Update both guides with the verified runner requirements, change `@wireguard-vpn-action` to `@v2` everywhere, and add the README section for the actions. | No | |
+| 8 | Wiki pages | Add pages for the two actions in English, Danish and Bahasa Malaysia, following the wiki rules of [MIL-005], and register them in the wiki index. | No | [MIL-005] |
+| 9 | Record the decision and the objective | Write an ADR: a VPN is delivered as a composite action, not as a reusable workflow (a called workflow runs as a separate job), and not through the marketplace action (written for GitHub). Objective O6, its scope item and success criterion 6 are already in [BC-001], and the schedule row, Gantt bar, scope entry, dependency and risk are in [PP-001] (added at acceptance, [RC-080], [RC-081]); this task writes the ADR only. | No | [ADR-0006] |
+| 10 | Release 2.2.0 | Add the `Added` entry to the changelog, run the Release workflow (dry run first), and check that `v2` points at `v2.2.0` and `v1` is unchanged. | No | [ADR-0006] |
+| 11 | Pin the framework templates | In `TirSystem/sqa-qc-framework`, change `@wireguard-vpn-action` to `@v2` in the two templates and the branch guide, remove the "experimental" notes that the release resolves, and open the pull request after release 2.2.0. This is a change in another repository, in its own pull request. | No | |
+| 12 | Review | Record `RC-*` for this milestone, the actions with their tests, and the guides, each with a verdict. | No | |
+
+
+## Verification results
+
+Task 1 was run on 2026-10-19 with the throwaway branch `verify-subfolder-action`, which calls both actions in the short form (`TirSystem/github-action/actions/<name>@<ref>`) and with the full address (`https://git.tirsystem.com/TirSystem/github-action/actions/<name>@<ref>`), with every input empty, so that a resolved action fails with its own `[configuration]` message.
+
+| Call | Result | Evidence |
+| --- | --- | --- |
+| Either form at `@wireguard-vpn-action` | Fails before the step: `Unable to resolve wireguard-vpn-action: reference not found`. The branch had been deleted when its pull request merged, so the ref did not exist; this is not a defect of the form. | run 417 (`2424`) |
+| Short form at `@main`, both actions | Resolves and runs: the log shows `Run Pre ...@main`, the action's `mask` step and its main step, which fails with `[configuration] set config, or all of private-key, ... (WG_PRIVATE_KEY is empty)` and `[configuration] give authkey or oauth-secret` | run 418 (`2425`), jobs `wg-short`, `ts-short` |
+| Full address at `@main`, both actions | The same result as the short form | run 418, jobs `wg-full`, `ts-full` |
+
+Both forms resolve. The short form is the one the guides show; the full address stays in the guides as the fallback. `gitea.action_path` is set (the script path in the log is under `/var/run/act/actions/<id>/actions/<name>/`). A `uses:` of a branch that no longer exists fails with "reference not found", so a caller of an experimental ref breaks when its branch is deleted.
+
+Tasks 6 and 9 were done on 2026-10-19 on the branch `mil-012-review-fixes-and-docs`:
+
+- **Lint (task 6):** `tools/lint-action-scripts.sh` runs shellcheck and shfmt on `actions/**/*.sh`; `validate-workflows.yml` runs it with pinned tools (`shellcheck-py==0.10.0.1`, `shfmt-py==3.11.0.2`, from `tests/requirements.txt`), and `.editorconfig` sets the shell format (two spaces, indented case labels, as the shell conventions say). `tests/test_lint_action_scripts.py` seeds a shellcheck problem and a badly formatted script and shows both fail, and shows the scripts of the actions pass.
+- **Decision (task 9):** [ADR-0011] (Proposed). Objective O6 and the Project Plan entries were added at the acceptance of this milestone ([RC-080], [RC-081]).
+
+The review of pull request 194 (ten findings) is answered in the same branch: `tailscaled` is waited for before `tailscale up`; the `wireguard-go` choice survives `sudo`; `sudo` is used only when the job is not root; a `tailscaled` that already runs on the runner is not taken over and `down` leaves a daemon it did not start; the Tailscale install needs an exact `version`, with an optional `sha256`; a configuration field with a line break is refused; only the key values are masked; the key file is removed when `wg-quick` fails; and the guides call `@main` until the release. These are offline-tested with stubs; tasks 3 and 4 still have to show them on a runner.
+
+Tasks 2, 3, 4, 5, 7, 8, 10, 11 and 12 are open: they need the trial runner (task 2), which is the operator's, or follow the verified guides (tasks 7 and 8) or the release (tasks 10 and 11).
+
+---
+
+[BC-001]: ../business-case.md
+[US-001]: ../user-stories.md
+[MIL-001]: ./mil-001-stabilise-metadata-sync.md
+[MIL-002]: ./mil-002-onboarding-and-operations.md
+[MIL-004]: ./mil-004-versioned-release.md
+[MIL-005]: ./mil-005-wiki-and-translations.md
+[MIL-011]: ./mil-011-code-metrics-default-tools-ref.md
+[MIL-012]: ./mil-012-vpn-actions-for-deployment.md
+[RC-080]: ../sqa/reviews/rc-080-mil-012-plan.md
+[RC-081]: ../sqa/reviews/rc-081-bc-001-o6.md
+[RC-082]: ../sqa/reviews/rc-082-mil-012-results.md
+[ADR-0006]: ../adr/adr-0006-release-process-and-version-pinning.md
+[ADR-0011]: ../adr/adr-0011-vpn-composite-actions.md
+[PP-001]: ../project-plan.md
+[c5d5941]: https://git.tirsystem.com/TirSystem/github-action/commit/c5d59418698316866807388bf61dcb6166d9fa8b
+[3325bea]: https://git.tirsystem.com/TirSystem/github-action/commit/3325bea772304b54e8dfffad592b4afadc3ec2b8

docs/milestones/mil-013-english-comments-check.md

@@ -0,0 +1,135 @@
+# MIL-013: Source code comments are in English
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | MIL-013 |
+| CrossReference | [BC-001], [US-001], [MIL-004], [MIL-010], [MIL-011], [ADR-0005], [ADR-0006], [ADR-0010], [ADR-0012] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-19 | Deprecated | Jens Tirsvad Nielsen | S01 | Initial version; reviewed (RC-083), accepted by the author in chat as stand-in for S01 with target date 2026-11-20 | [e35b1c5] |
+| 2026-10-21 | Accepted | Jens Tirsvad Nielsen | S01 | Added the results of tasks 1 to 8, 10 and 13 and the three defects found in the trial; reviewed (RC-085), accepted by the author in chat as stand-in for S01 | [88f852a] |
+
+---
+
+## Purpose
+
+Decide whether a pull request can be stopped automatically when a comment in its source code is not written in English, and the author told why.
+
+TirSystem code is read by people who speak Danish, Bahasa Malaysia and English, so the comments of source code are in English only (the shared language of the repositories, and the register the project's coding conventions already ask for). Today nothing enforces it: a Danish or Malay comment is found, if at all, by a human reviewer. This milestone adds a check that finds them on the pull request, fails the check run so the pull request is blocked, and writes a message to the author with the file, the line and the reason.
+
+The hard part is the detection, not the workflow. A comment is short, full of identifiers, and often a few words; Danish and Malay words are often close to English ones or are names. The first task therefore decides the method on a measured corpus and records it in an ADR; the rest follows from it.
+
+## Deliverable
+
+Release `2.3.0` of this repository ([ADR-0006]: a new capability is a minor release) with a reusable workflow `english-comments.yml` that other repositories call with `uses:`, its script files under `tools/` (comment extraction, detection, reporting), a guide, a README section, wiki pages in English, Danish and Bahasa Malaysia, a changelog entry under `Added`, and offline tests. An ADR for the detection method and its error rate. The workflow runs on the pull requests of this repository too. A review record. In the other repositories, in their own pull requests: the rule in the `coding-conventions` skill of `TirSystem/sqa-qc-framework`, and a proposed criterion for the checklist repository.
+
+## Go / No-Go Criteria
+
+| # | Criterion (objectively checkable) | Go | No-Go |
+| --- | --- | --- | --- |
+| 1 | The detection method is chosen on a corpus recorded in the repository: at least 40 comments each in Danish and in Bahasa Malaysia, at least 40 in other languages (German, Swedish, Norwegian, French), and at least 200 English comments, among them comments with identifiers, paths and abbreviations. The ADR gives recall and false positives per language | Recall at least 90 % for Danish and Malay, and at most 1 false positive per 200 English comments | A lower rate, or no corpus |
+| 2 | The check reads comments and docstrings, not code or string values, in every language of [ADR-0010], and a comment line holding only identifiers, URLs, numbers or code is not judged | Fixtures for each language pass | A string value or a code-only comment is reported |
+| 3 | The workflow checks the files a pull request changes (all tracked files when asked), reports each finding as `file:line`, the language found and the text, and fails the run when there is one | A pull request with one Danish comment fails; one without passes | The run passes with a finding, or fails without one |
+| 4 | An author can mark an exception on the line (a quotation, a name) and list allowed words in a file of the repository; both are logged | The marked line is not reported | No way to mark an exception |
+| 5 | On failure the workflow writes one comment on the pull request that mentions the author and lists the findings; a re-run updates that comment instead of adding another, and a passing run marks it resolved | Verified on a throwaway pull request, with the Gitea mention reaching the author | Two comments, no mention, or a comment on a passing run |
+| 6 | The comment is written with a token that holds the smallest scope that works; it is a CI secret and appears in no log, and no source text is sent to a service outside the instance | A search of the run logs for the token finds none; the detector needs no network | A token in a log, or an external call |
+| 7 | The failing check blocks the merge: the workflow's check is listed as required, and a pull request with a finding cannot be merged. Setting branch protection is the repository owner's action; this milestone documents it and verifies it with the owner | Verified with S01 or S03 on a throwaway branch | The pull request can still be merged |
+| 8 | This repository calls the workflow on its own pull requests, and passes | The caller run is green on `main` | Not called, or red |
+| 9 | The guide, README and wiki pages (English, Danish, Bahasa Malaysia) describe the workflow at `@v2`, and the changelog has an `Added` entry; the release is a minor (`2.3.0`), `v2` moves to it and `v1` is not touched | Released | Another level, or `v1` moved |
+| 10 | The framework rule and the checklist criterion are open as pull requests of their own repositories after release 2.3.0 | Both open | Missing |
+| 11 | Reviewed | A review record (`RC-*`) for this milestone, the workflow, the scripts, the tests and the guides, each with a verdict of Go | An instance without a record |
+
+## Dependencies
+
+| Depends on | Reason |
+| --- | --- |
+| [MIL-010] | The code counter that already tells comment lines from code lines for the languages of [ADR-0010]; the extractor builds on its scanner |
+| [MIL-004] | The release process and the Release workflow that publish `2.3.0` |
+| [MIL-011] | `MAJOR_TAG` and the `tools-ref` default that a new reusable workflow must follow |
+| [ADR-0005] | The contract of a shared check: inputs with working defaults, pinned tools, a script file, a failure that names the cause |
+| An organization secret with a Gitea token that may comment on pull requests (S03) | Criterion 5; created by the operator, never recorded in this repository |
+| Branch protection of the repositories that adopt the check (S01 or S03) | Criterion 7; changing it is the owner's decision, not made by the workflow |
+| `TirSystem/sqa-qc-framework` and `TirSystem/SQA-QC-Checklists` | Task 12 changes them in their own pull requests, after the release |
+
+## Traceability
+
+| Business Case objective / KPI / user story | Reference |
+| --- | --- |
+| Business Case objective O7: a shared workflow that checks that the comments in source code are written in English, blocks the pull request when they are not, and tells the author | [BC-001] |
+| User stories | [US-001] (no new story: the tasks below are technical; the check is used by the authors of pull requests) |
+
+## Ownership
+
+| Role | Stakeholder ID (SA) |
+| --- | --- |
+| Owner | S05 |
+| Approving reviewer | S01 |
+
+## Target Date
+
+2026-11-20 (Friday), proposed: two weeks from 2026-11-09, after [MIL-012] (2026-11-06) so that the two milestones do not compete for the one runner and the one reviewer. The Business Case sets no deadline. S01 confirmed the date when accepting this milestone, in chat on 2026-10-19.
+
+## Tasks
+
+| # | Task | Summary | Needs its own Use Case/User Story? | Reference |
+| --- | --- | --- | --- | --- |
+| 1 | Build the corpus | Collect and label the comments of criterion 1 in `tests/fixtures/` (real comments from the TirSystem repositories where they exist, written ones otherwise), with the language of each. English comments come from this repository and others that are known to be English. Record the source of each part. | No | |
+| 2 | Choose the detection method (ADR) | Compare at least two methods on the corpus: a rule-based one (letters outside English, word lists for Danish and Malay) and a language-identification library restricted to the candidate languages, run offline. Measure recall and false positives per language, the install size and the time on a repository of 1 000 files. Write the ADR with the numbers and the choice. | No | [ADR-0005] |
+| 3 | Extract comments | Add a script that returns the text, file and line of every comment and docstring for the languages of [ADR-0010], reusing the scanner of `tools/count_loc.py` (it classifies lines today but does not return the text). Skip string values, code and comment lines that hold only identifiers, URLs, numbers or code. | No | [MIL-010] |
+| 4 | Detect the language | Implement the method of task 2 as a script with a fixed interface (comment in, language and confidence out), the exception marker on the line and the allowed-words file of criterion 4. | No | |
+| 5 | Report and tell the author | A script that prints each finding as `::error file=...,line=...` and `file:line`, fails the run, and writes or updates one pull request comment that mentions the author, through the Gitea API with the smallest token scope; a passing run marks the comment resolved. A fake API in the tests. | No | |
+| 6 | Write the reusable workflow | `english-comments.yml` with `workflow_call`, inputs with working defaults (changed files only, languages, allowed-words file, exclude), a pinned `tools-ref` that follows `MAJOR_TAG`, the token as a secret, and explicit job permissions. The `run:` lines only call the script files. | No | [ADR-0005] |
+| 7 | Offline tests | Tests for the extractor, the detector against the corpus (the rates of criterion 1 as a test that fails below them), the reporting against the fake API, and the workflow definition; the coverage limit of `tools/` holds. | No | |
+| 8 | Trial on the instance | On a throwaway pull request with one Danish comment, one Malay comment and one marked exception: record the failing run, the comment with the mention, the update on a re-run and the green run after the fix. Search the logs for the token. | No | |
+| 9 | Block the merge | With S01 or S03, mark the check as required for `main` of this repository and show that a pull request with a finding cannot be merged. Document the setting for other repositories. This task changes branch protection, so it is done by the owner, not by the AI. | No | |
+| 10 | Guides, README and wiki | Guide, README section, and wiki pages in English, Danish and Bahasa Malaysia, following [MIL-005]; the sidebar. | No | [MIL-005] |
+| 11 | Call it in this repository, then release | A caller workflow for the pull requests of this repository; the changelog entry; the Release workflow (dry run first); check that `v2` points at `v2.3.0` and `v1` is unchanged. | No | [ADR-0006] |
+| 12 | The rule in the framework and the checklists | In `TirSystem/sqa-qc-framework`, add the English-comments rule to the `coding-conventions` skill and the call of the workflow to its CI template; in `TirSystem/SQA-QC-Checklists`, propose a criterion. Each in its own pull request, after release 2.3.0. | No | |
+| 13 | Add MIL-013 to the Business Case and the Project Plan | Objective O7, the scope item and a success criterion in [BC-001]; the schedule row, Gantt bar, scope entry, dependency and a plan risk (false positives on short comments) in [PP-001]; the traceability rows. | No | |
+| 14 | Review | Record `RC-*` for this milestone, the workflow, the scripts, the tests and the guides, each with a verdict. | No | |
+
+
+## Verification results
+
+**Tasks 1 to 7, 10 and 13** were done on 2026-10-19 to 2026-10-21 and merged in pull request 211 (and 196 for task 13): the corpus (300 English, 45 Danish, 45 Malay, 48 other), [ADR-0012] (`Proposed`, not yet reviewed), the extractor and detector, the report script, the reusable workflow `english-comments.yml`, 673 offline tests with 98 % coverage of `tools/`, and the guide, README and wiki in three languages. The detector flags 0 of 300 English comments, 44 of 45 Danish and 41 of 45 Malay comments and all 48 of the others; the Danish and Malay comments were written for the test and not checked by a native reader.
+
+**Task 8 (trial on the instance)** was run on 2026-10-21 with the throwaway branch `verify-english-comments` and its pull request 213 (closed, not merged). The sample file holds an English comment, a Danish comment directly under it, a Malay comment, and a Danish comment marked `english-comments: ignore`.
+
+| Run | What was called | Result |
+| --- | --- | --- |
+| 433 (id 2478), first call at `@main` | the workflow of pull request 211 | Fetched the shared scripts, installed `langid` and `numpy` on the runner, found only the Malay comment (line 9, `id` 0.66); the Danish line next to the English one was **missed** (defect 1). The step "Tell the author" was **skipped**, so no comment was written (defect 2). The run failed. |
+| 435 and 437 (ids 2480, 2482), a debug workflow | the contexts of a called workflow | `gitea.event_name` is `workflow_call`; `gitea.event.pull_request.number` (213), the author login and `gitea.base_ref` (`main`) are set. The conditions `always()`, `always() && ...pull_request.number != ''`, `... && ...pull_request.number`, `... && ...pull_request` and `... && gitea.base_ref != ''` ran the step; `gitea.event_name == 'pull_request'` and `github.event_name == 'pull_request'` did not. |
+| 440 (id 2485), the fix branch | `english-comments.yml@mil-013-judge-each-line` | Both the Danish line (6, `da` 1.0) and the Malay line (9) were found, the marked line was not reported, the run failed, and the Actions bot (`gitea-actions`) wrote **one** comment (id 8715) that mentions `@Tirsvad` and lists the two findings. |
+| 443 (id 2488) | the same, with another Danish comment | "Updated the comment of the check": still one comment (id 8715), with the new text. |
+| 445 (id 2490) | both comments rewritten in English | The run passed, the failing step was skipped, and the comment was marked resolved (a "passes" text, no mention). |
+| 447 (id 2492) | a Malay comment again | The comment updated; its link `.../actions/runs/2492` equals the `html_url` of the run (defect 3 fixed: the first version linked the run number 440). |
+
+The three defects are fixed in pull request 212 (open at the time of writing): (1) a block of several lines is judged line by line first (at least four words, probability 0.7), then as a whole; (2) the author step asks for `gitea.event.pull_request.number != ''` instead of the event name; (3) the comment links the run by its id. Each has a test.
+
+**Secrets:** the four `english-comments` jobs of runs 440, 443, 445 and 447 were searched for `token <20 or more characters>`, `basic <base64>`, `bearer` and for the value of the token used from this machine; nothing was found. `REPORT_TOKEN` is printed as `***` and the clone header as `AUTHORIZATION: basic ***`. The detector made no network call; the only calls were to the Gitea API of the instance.
+
+**Not shown by the trial:** a call at `@main` of the corrected workflow (it follows the merge of pull request 212); a pull request from a fork (read-only token); a custom `REPORT_TOKEN` secret; the check as a required status that blocks the merge (task 9); and the call of the workflow by this repository (task 11). Tasks 9, 11, 12 and 14 are open.
+
+---
+
+[BC-001]: ../business-case.md
+[US-001]: ../user-stories.md
+[MIL-004]: ./mil-004-versioned-release.md
+[MIL-005]: ./mil-005-wiki-and-translations.md
+[MIL-010]: ./mil-010-code-metrics-badges.md
+[MIL-011]: ./mil-011-code-metrics-default-tools-ref.md
+[MIL-012]: ./mil-012-vpn-actions-for-deployment.md
+[MIL-013]: ./mil-013-english-comments-check.md
+[ADR-0005]: ../adr/adr-0005-quality-check-contract.md
+[ADR-0006]: ../adr/adr-0006-release-process-and-version-pinning.md
+[ADR-0010]: ../adr/adr-0010-code-metrics-badges-contract.md
+[PP-001]: ../project-plan.md
+[RC-083]: ../sqa/reviews/rc-083-mil-013-plan.md
+[RC-084]: ../sqa/reviews/rc-084-bc-001-o7.md
+[RC-085]: ../sqa/reviews/rc-085-mil-013-results.md
+[ADR-0012]: ../adr/adr-0012-english-comment-detection.md
+[e35b1c5]: https://git.tirsystem.com/TirSystem/github-action/commit/e35b1c56748a50430503f5518602469f93262357
+[88f852a]: https://git.tirsystem.com/TirSystem/github-action/commit/88f852af9398468b91e88fe0190ce5c35dcf0fa2

docs/project-plan.md

@@ -4,25 +4,27 @@
 | Key | Value |
 | --- | --- |
 | ID | PP-001 |
-| CrossReference | [BC-001], [SA-001], [ADR-0002], [US-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007] |
+| CrossReference | [BC-001], [SA-001], [ADR-0002], [US-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [MIL-008], [MIL-009], [MIL-010], [MIL-011], [MIL-012], [MIL-013] |
 
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
-| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Dates confirmed by S01 (stand-in for S05); the confirmation item is removed from Open Issues | [ea06eaa] |
-| 2026-10-11 | Accepted | Jens Tirsvad Nielsen | S01 | Added MIL-007 (quality checks for C++ and C#); reviewed (RC-053) | [e3ad1fa] |
+| 2026-10-19 | Deprecated | Jens Tirsvad Nielsen | S01 | Added MIL-012 (VPN actions for deployment); reviewed (RC-080), accepted by the author in chat as stand-in for S01 | [c5d5941] |
+| 2026-10-19 | Accepted | Jens Tirsvad Nielsen | S01 | Added MIL-013 (source code comments are in English); reviewed (RC-083), accepted by the author in chat as stand-in for S01 | [e35b1c5] |
 
 ---
 
 ## Purpose
 
-This plan schedules seven milestones that move the repository from one
+This plan schedules thirteen milestones that move the repository from one
 workflow with known defects to a documented, versioned collection of shared
 workflows. The Business Case sets no deadline, so the dates are the plan's own; they were confirmed on 2026-10-10 by S01, standing in for S05 (ADR-0002).
 
 ## Planning Assumptions
 
-- Week 1 starts 2026-10-05; phases are two weeks long; the last decision is 2026-12-26; MIL-007 follows in January 2027 (2027-01-04 to 2027-01-16, confirmed on 2026-10-11 by S01).
+- Week 1 starts 2026-10-05; phases are two weeks long; the last decision is 2026-12-26; MIL-007 follows in January 2027 (2027-01-04 to 2027-01-16, confirmed on 2026-10-11 by S01). MIL-008 amends the shared wiki publishing of MIL-006 and runs in parallel with the October and November windows: its work started on 2026-10-13 and its decision date is its own Target Date, 2026-11-15. MIL-009 follows MIL-008 and runs from 2026-11-16 to its proposed Target Date, 2026-11-30, confirmed by S01 in chat on 2026-10-14. MIL-010 (code metrics and coverage badges) follows MIL-007 in January 2027, from 2027-01-18 to its Target Date, 2027-01-30, accepted by the user in chat on 2026-10-14.
+- MIL-012 (VPN actions for deployment) runs from 2026-10-26 to its Target Date, 2026-11-06, proposed by the author and accepted by S01 in chat on 2026-10-19; it overlaps MIL-002 and MIL-003, which do not touch the runners' network.
+- MIL-013 (source code comments are in English) runs from 2026-11-09 to its Target Date, 2026-11-20, proposed by the author and accepted by S01 in chat on 2026-10-19; it overlaps MIL-009, whose work is on wiki callers and does not touch the runners or the reviewer of the check.
 - Work on a milestone starts only after its `MIL-*` document is `Accepted`.
 - Dates were confirmed on 2026-10-10 by S01, standing in for S05 (ADR-0002).
 
@@ -37,6 +39,12 @@ workflows. The Business Case sets no deadline, so the dates are the plan's own;
 | Wiki and translations | [MIL-005] | 2026-11-30 to 2026-12-12 | 2026-12-12 | S05 | None yet | Wiki pages in English, Danish and Bahasa Malaysia, kept current by every pull request | [Milestone MIL-005] |
 | Shared wiki publishing | [MIL-006] | 2026-12-14 to 2026-12-26 | 2026-12-26 | S05 | None yet | Scoped publish-wiki workflow with opt-in, piloted in one other repository | [Milestone MIL-006] |
 | Quality checks for C++ and C# | [MIL-007] | 2027-01-04 to 2027-01-16 | 2027-01-16 | S05 | US-001.09, US-001.10 (to extend) | Reusable quality-check workflows for C++ and C#, released | [Milestone MIL-007] |
+| Wiki publishing as a reusable workflow | [MIL-008] | 2026-10-13 to 2026-11-15 | 2026-11-15 | S05 | None yet | Reusable publish-wiki-pages workflow, wiki in docs/wiki, scoped workflow deprecated, released as 1.2.2 | [Milestone MIL-008] |
+| Migrate the wiki callers and remove the scoped workflow | [MIL-009] | 2026-11-16 to 2026-11-30 | 2026-11-30 | S05 | None yet | Seven repositories publish through a caller, scoped workflow removed, ADR-0004 superseded, released as 2.0.0 | Not created yet (the sync creates it when MIL-009 is Accepted) |
+| Code metrics and coverage badges | [MIL-010] | 2027-01-18 to 2027-01-30 | 2027-01-30 | S05 | None yet (task 1 writes them) | Reusable workflow that counts code files and lines of code, reads coverage and commits SVG badges, released | Not created yet (the sync creates it when MIL-010 is Accepted) |
+| Fix the defaults of the code metrics workflow | [MIL-011] | 2026-10-14 to 2026-10-23 | 2026-10-23 | S05 | None (technical tasks) | Patch release 2.1.1: the default `tools-ref` of every reusable workflow names a tag that holds its scripts, a test for it, guides and wiki at `@v2`, the framework Badges page without the workaround | Not created yet (the sync creates it when MIL-011 is Accepted) |
+| VPN actions for deployment | [MIL-012] | 2026-10-26 to 2026-11-06 | 2026-11-06 | S05 | None (technical tasks) | Release 2.2.0: composite actions `connect-wireguard` and `connect-tailscale` verified on a runner of the instance, with guides, wiki in three languages and the framework templates pinned to the release | Not created yet (the sync creates it when MIL-012 is Accepted) |
+| Source code comments are in English | [MIL-013] | 2026-11-09 to 2026-11-20 | 2026-11-20 | S05 | None (technical tasks) | Release 2.3.0: reusable workflow `english-comments.yml` that fails a pull request with a non-English comment and tells the author, with its ADR, tests, guides and wiki, and the rule proposed in the framework | Not created yet (the sync creates it when MIL-013 is Accepted) |
 
 ```plantuml
 @startgantt
@@ -55,6 +63,18 @@ Project starts 2026-10-05
 [MIL-006 Go/No-Go] happens 2026-12-26
 [MIL-007 C++ and C#] starts 2027-01-04 and ends 2027-01-16
 [MIL-007 Go/No-Go] happens 2027-01-16
+[MIL-008 Reusable wiki workflow] starts 2026-10-13 and ends 2026-11-15
+[MIL-008 Go/No-Go] happens 2026-11-15
+[MIL-009 Migrate and remove] starts 2026-11-16 and ends 2026-11-30
+[MIL-009 Go/No-Go] happens 2026-11-30
+[MIL-010 Badges] starts 2027-01-18 and ends 2027-01-30
+[MIL-010 Go/No-Go] happens 2027-01-30
+[MIL-011 Defaults fix] starts 2026-10-14 and ends 2026-10-23
+[MIL-011 Go/No-Go] happens 2026-10-23
+[MIL-012 VPN actions] starts 2026-10-26 and ends 2026-11-06
+[MIL-012 Go/No-Go] happens 2026-11-06
+[MIL-013 English comments] starts 2026-11-09 and ends 2026-11-20
+[MIL-013 Go/No-Go] happens 2026-11-20
 @endgantt
 ```
 
@@ -69,6 +89,11 @@ Project starts 2026-10-05
 | Wiki pages in English, Danish and Bahasa Malaysia | [MIL-005] |
 | The wiki publisher shared with other repositories through scoped delivery | [MIL-006] |
 | Gitea Actions workflows for software engineers (quality checks for C++ and C#) | [MIL-007] |
+| The wiki publisher as a workflow that repositories call, from docs/wiki | [MIL-008] |
+| Moving every publishing repository to the called workflow and removing the scoped one | [MIL-009] |
+| A shared workflow for code metrics and coverage badges | [MIL-010], [MIL-011] |
+| Shared composite actions that connect a deployment job to a private network through WireGuard or Tailscale | [MIL-012] |
+| A shared workflow that checks that comments in source code are in English and tells the author | [MIL-013] |
 
 ## Dependencies
 
@@ -76,6 +101,10 @@ Project starts 2026-10-05
 MIL-001 → MIL-002 → MIL-003 → MIL-004
             MIL-002 → MIL-005 → MIL-006
    MIL-003 + MIL-004 → MIL-007
+                      MIL-006 → MIL-008 → MIL-009
+   MIL-003 + MIL-004 → MIL-010 → MIL-011
+   MIL-004 + MIL-011 → MIL-012
+   MIL-004 + MIL-010 + MIL-011 → MIL-013
 ```
 
 A No-Go moves every later window by the rework time of the failed milestone.
@@ -86,6 +115,11 @@ A No-Go moves every later window by the rework time of the failed milestone.
 | --- | --- | --- |
 | The runner cannot provide the C++ or C# tools (MIL-007) | The workflows need a custom runner image or a longer install | MIL-007 task 2 verifies it first; the ADR of task 3 says what a build-dependent check needs from the caller. |
 | Reusable workflow support is missing on the instance | MIL-003 and MIL-004 change shape | Verify first in each milestone (MIL-002 task 2, MIL-003 task 1); fall back to copied templates. |
+| Eight repositories still publish through the scoped workflow that MIL-008 deprecates (MIL-008 task 5) | Removing it would stop their wikis | It is deprecated and kept; a follow-up milestone migrates them and removes it in a major release (RC-061). |
+| An organisation has no `TOKEN_FOR_GITEA_WIKI` secret, or a repository fails its first run (MIL-009 tasks 3 and 4) | The wiki of that repository stops updating | MIL-009 task 5 reads each wiki back after the first run; the scoped workflow is removed only after every repository passes. |
+| The token of a run cannot push to a `badges` branch, or the SVG does not render on the mirror (MIL-010) | The delivery of the badges changes shape | MIL-010 task 3 verifies it first; fall back to a badge file in a path of the default branch or to a run artifact. |
+| The runner cannot give a job `NET_ADMIN` and `/dev/net/tun`, or `tailscaled` does not survive to the next step (MIL-012) | The actions need another shape (a different start of the daemon, or userspace mode only) | MIL-012 tasks 2 to 4 verify it first on a runner of the instance; the release waits for criteria 2 and 3. |
+| The check calls a correct comment non-English, or misses a Danish or Malay one (MIL-013) | Authors lose trust in the check, or it is turned off | MIL-013 tasks 1 and 2 measure the method on a corpus before anything is built, and the exception marker and the allowed-words file (criterion 4) take care of the rest. |
 | Security review by S05 is a bottleneck | Milestone decisions slip | Keep milestones small and plan review time before each decision date. |
 
 ## Open Issues
@@ -258,6 +292,12 @@ no tests, no release process.
 [MIL-005]: ./milestones/mil-005-wiki-and-translations.md
 [MIL-006]: ./milestones/mil-006-shared-wiki-publishing.md
 [MIL-007]: ./milestones/mil-007-cpp-csharp-quality-checks.md
+[MIL-008]: ./milestones/mil-008-wiki-reusable-workflow.md
+[MIL-009]: ./milestones/mil-009-migrate-wiki-callers-and-remove-scoped-workflow.md
+[MIL-010]: ./milestones/mil-010-code-metrics-badges.md
+[MIL-011]: ./milestones/mil-011-code-metrics-default-tools-ref.md
+[MIL-012]: ./milestones/mil-012-vpn-actions-for-deployment.md
+[MIL-013]: ./milestones/mil-013-english-comments-check.md
 [Milestone MIL-001]: https://git.tirsystem.com/TirSystem/github-action/milestone/18
 [Milestone MIL-002]: https://git.tirsystem.com/TirSystem/github-action/milestone/19
 [Milestone MIL-003]: https://git.tirsystem.com/TirSystem/github-action/milestone/20
@@ -265,6 +305,6 @@ no tests, no release process.
 [Milestone MIL-005]: https://git.tirsystem.com/TirSystem/github-action/milestone/93
 [Milestone MIL-006]: https://git.tirsystem.com/TirSystem/github-action/milestone/94
 [Milestone MIL-007]: https://git.tirsystem.com/TirSystem/github-action/milestone/95
-[ea06eaa]: https://git.tirsystem.com/TirSystem/github-action/commit/ea06eaaa698247d20e4a8e2694d7acbb1de58b63
-[b74ee0e]: https://git.tirsystem.com/TirSystem/github-action/commit/b74ee0e5cfd04f25ba5f2c1addc80699147c479a
-[e3ad1fa]: https://git.tirsystem.com/TirSystem/github-action/commit/e3ad1fa7e7eef57a6793a479edb41ac6fd2db688
+[Milestone MIL-008]: https://git.tirsystem.com/TirSystem/github-action/milestone/152
+[c5d5941]: https://git.tirsystem.com/TirSystem/github-action/commit/c5d59418698316866807388bf61dcb6166d9fa8b
+[e35b1c5]: https://git.tirsystem.com/TirSystem/github-action/commit/e35b1c56748a50430503f5518602469f93262357

docs/sqa/reviews/rc-062-pp-001-mil-008.md

@@ -0,0 +1,54 @@
+# Review Record: PP-001 Project Plan (MIL-008)
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-062 |
+| CrossReference | [PP-001], [BC-001], [MIL-008] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-13 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | [9aeb74e] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [PP-001]
+- Checklist used: none: the Project Plan has no QC checklist. Validated against the Business Case [BC-001] and the Go / No-Go criteria of each listed milestone, as `PP.md` prescribes.
+- Scope: delta re-review for the added MIL-008 row, Gantt entries, Scope Coverage, Dependencies, one Plan Risk and the counts; the earlier record is RC-053
+- Language and domain: n/a (technical type)
+- Mode: supervised (the AI prepared the record; S01, the user, gave the Go in chat on 2026-10-13)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | Every milestone in the plan has a `MIL-*` document and the plan's dates equal that document's target date | Pass | MIL-001 to MIL-008 exist; the MIL-008 decision date 2026-11-15 equals its Target Date. |
+| 2 | Every Business Case scope item is covered by a gateway | Pass | The wiki publisher shared with other repositories is covered by MIL-006 and MIL-008 (O2, O3). |
+| 3 | The schedule respects the Business Case constraints | Pass | The Business Case sets no deadline; the MIL-008 window overlaps the October and November windows and says so under Planning Assumptions. |
+| 4 | Dependencies between milestones are stated | Pass | MIL-006 to MIL-008 is in the Dependencies diagram and in MIL-008's own document. |
+| 5 | Every gateway has an owner who is a stakeholder ID | Pass | MIL-008 is owned by S05. |
+| 6 | Plan content is internally consistent | Pass | "Eight milestones", the Planning Assumptions, the Gantt entries, the Gateway Schedule and the Scope Coverage agree. |
+| 7 | Open Issues are current | Pass | Unchanged items remain open; a plan risk was added for the repositories that still use the scoped workflow. |
+
+## Overall Verdict
+
+Go - all seven criteria pass; no findings. S01 gave the Go in chat on 2026-10-13, after the change was merged as pull request 137 with the plan row `Proposed`; this record and the plan row are set to `Accepted` in the follow-up.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| Set PP-001 and this record to `Accepted` (done in the follow-up that follows pull request 137) | S05 | 2026-10-13 |
+| Review ADR-0009 (still without a review record) | S01 | after the plan |
+
+---
+
+---
+
+[PP-001]: ../../project-plan.md
+[BC-001]: ../../business-case.md
+[MIL-008]: ../../milestones/mil-008-wiki-reusable-workflow.md
+[9aeb74e]: https://git.tirsystem.com/TirSystem/github-action/commit/9aeb74e8b09bb7882847e9bd5d569dbc9856fc03

docs/sqa/reviews/rc-063-adr-0009.md

@@ -0,0 +1,56 @@
+# Review Record: ADR-0009 Wiki publishing as a reusable workflow
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-063 |
+| CrossReference | [ADR-0009], [QC-ADR-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-13 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | [8c2c52e] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [ADR-0009]
+- Checklist used: [QC-ADR-001]
+- Scope: full review
+- Language and domain: n/a (technical type)
+- Mode: supervised (the AI prepared the record; S01, the user, gave the Go in chat on 2026-10-13)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | The ID (`ADR-NNNN`, 4-digit) matches the filename number and is unique and sequential | Pass | ADR-0009 in `adr-0009-wiki-publishing-reusable-workflow.md`; follows ADR-0008. |
+| 2 | Context states the problem, the forces (cost, risk, constraints) and the options evaluated | Pass | Names the scoped delivery, its gate, the fixed trigger path and version, and the new folder rule. |
+| 3 | At least two options were considered, or the absence of alternatives is justified | Pass | Two options: keep the scoped workflow and read both folders, or a reusable workflow. |
+| 4 | Decision is stated in one or two unhedged sentences and matches one of the evaluated options | Pass | Two sentences; matches option 2. The rules below it add detail only. |
+| 5 | Consequences list both Positive and Negative outcomes | Pass | Finding fixed during this review: the consequence "passing a declared secret is not yet verified" was out of date, because run 316 verified it on 2026-10-13. It now says so. Four positive and four negative outcomes. |
+| 6 | Quality-attribute impacts (performance, security, portability, etc.) are named where the decision affects them | Pass | Finding fixed during this review: the security impact was implicit. A positive bullet (explicit secret, no fallback) and a negative bullet (whoever changes the caller changes the folder and `prune`) were added. |
+| 7 | Affected Artifacts are listed as links, and each is also in CrossReference | Pass | MIL-008 and ADR-0004 are linked and cited. |
+| 8 | Status changes are recorded as new Version History rows with a Change summary and Commit link; retained rows are never rewritten | Pass | The findings fix is a new row; the first row is kept unchanged. |
+| 9 | A superseded or deprecated ADR names its successor, and the successor links back | N-A | ADR-0004 is superseded only in part and stays in force until the scoped workflow is removed; see the action item. |
+| 10 | Written in business or technical language of the domain, with no unexplained abbreviations | Pass | Finding fixed during this review: "PO language" is now "the product owner's language". |
+| 11 | Status is one of `Proposed`, `Accepted`, `Rejected`, `Deprecated` or `Superseded by ADR-NNNN`, and every Version History row uses only these | Pass | `Proposed` only. |
+
+## Overall Verdict
+
+Go - all applicable criteria pass; the three findings (criteria 5, 6 and 10) were fixed during the review. S01 gave the Go in chat on 2026-10-13; there is no independent reader.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| When the scoped workflow is removed, mark ADR-0004 superseded by ADR-0009 for the delivery and marker parts (new version row and review record) | S01 | the follow-up milestone |
+
+---
+
+---
+
+[ADR-0009]: ../../adr/adr-0009-wiki-publishing-reusable-workflow.md
+[QC-ADR-001]: ../../../framework/qc/artifacts/qc-adr.md
+[8c2c52e]: https://git.tirsystem.com/TirSystem/github-action/commit/8c2c52ebd2a27e4d0edb4008c31c002718d280fb

docs/sqa/reviews/rc-064-mil-009-plan.md

@@ -0,0 +1,63 @@
+# Review Record: MIL-009 and PP-001 (MIL-009)
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-064 |
+| CrossReference | [MIL-009], [PP-001], [BC-001], [QC-MIL-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version; accepted | [86e69ce] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [MIL-009]; delta of [PP-001] for the added milestone
+- Checklist used: [QC-MIL-001] for the milestone; for the plan, the criteria of `PP.md` (no QC checklist exists for PP-001)
+- Scope: full review of MIL-009; delta re-review of PP-001, earlier record RC-062
+- Language and domain: n/a (technical type)
+- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`; the user accepted the plan in chat on 2026-10-14 with the defaults)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | A concrete deliverable is defined for every gate | Pass | MIL-009 lists the released framework, seven callers, the removals, the superseded ADR and 2.0.0. |
+| 2 | Explicit Go/No-Go criteria are stated for each gate | Pass | Seven criteria with checkable Go and No-Go (tag, callers, read-backs, scan, removal, ADR rows, tags). |
+| 3 | Dependencies on other milestones are explicitly mapped | Pass | MIL-008 and the framework release; in the plan's Dependencies diagram (`MIL-008 -> MIL-009`). |
+| 4 | Each milestone is traceable to a Business Case objective or KPI | Pass | O2, O3 of [BC-001]. |
+| 5 | Milestone owner and approving reviewer are identified | Pass | Owner S05, approving reviewer S01. |
+| 6 | Milestone has a defined target date consistent with project constraints | Pass | 2026-11-30 is proposed and equals the plan's decision date; the Business Case sets no deadline. S01 has not confirmed it, as MIL-009 and the plan say; this is an action item. |
+
+## Plan delta (PP-001)
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | Every milestone has a `MIL-*` document and the plan's dates equal that document's target date | Pass | MIL-001 to MIL-009 exist; the MIL-009 decision date equals its Target Date. |
+| 2 | Every Business Case scope item is covered by a gateway | Pass | Scope Coverage names MIL-009 for the removal of the scoped publisher. |
+| 3 | The schedule respects the Business Case constraints | Pass | No deadline in the Business Case; the window follows MIL-008. |
+| 4 | Dependencies between milestones are stated | Pass | `MIL-006 -> MIL-008 -> MIL-009`. |
+| 5 | Every gateway has an owner who is a stakeholder ID | Pass | S05. |
+| 6 | Plan content is internally consistent | Pass | "Nine milestones", the assumptions, the Gantt, the schedule and the coverage agree. |
+| 7 | Open Issues are current | Pass | A plan risk was added for missing organisation secrets and failed first runs. |
+
+## Overall Verdict
+
+Go - all criteria pass. The user switched to autonomous mode and accepted the plan in chat on 2026-10-14 with the defaults (target date 2026-11-30, no publishing for `027-sandbox` and `028-pomodoro`, framework release 0.7.0); the AI records the acceptance as stand-in for S01. There is no independent reader and the decision stays open to challenge in the run summary.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| Check that `TirSystem-BashScript` has its own `TOKEN_FOR_GITEA_WIKI` (S03); stop and report if it does not | S03 | MIL-009 task 3 |
+
+---
+
+[MIL-009]: ../../milestones/mil-009-migrate-wiki-callers-and-remove-scoped-workflow.md
+[PP-001]: ../../project-plan.md
+[BC-001]: ../../business-case.md
+[QC-MIL-001]: ../../../framework/qc/artifacts/qc-milestones-gateways.md
+[86e69ce]: https://git.tirsystem.com/TirSystem/github-action/commit/86e69ce85df72ea3caed40253e08231c73187fde

docs/sqa/reviews/rc-065-adr-0004-superseded.md

@@ -0,0 +1,56 @@
+# Review Record: ADR-0004 superseded by ADR-0009
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-065 |
+| CrossReference | [ADR-0004], [ADR-0009], [QC-ADR-001], [MIL-009] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | [22fc323] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [ADR-0004] after the status change to `Superseded by ADR-0009` on 2026-10-14
+- Checklist used: [QC-ADR-001]
+- Scope: delta re-review of the criteria the status change touches (7, 8, 9, 11); the earlier record is RC-018
+- Language and domain: n/a (technical type)
+- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`; the user accepted the plan [MIL-009] in chat on 2026-10-14)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | The ID matches the filename number and is unique and sequential | Pass | Unchanged. |
+| 2 | Context states the problem, the forces and the options evaluated | Pass | Unchanged. |
+| 3 | At least two options were considered | Pass | Unchanged. |
+| 4 | Decision is stated in one or two unhedged sentences and matches an evaluated option | Pass | Unchanged. |
+| 5 | Consequences list both Positive and Negative outcomes | Pass | Unchanged. |
+| 6 | Quality-attribute impacts are named where the decision affects them | Pass | Unchanged. |
+| 7 | Affected Artifacts are listed as links, and each is also in CrossReference | Pass | ADR-0009 is added to both. |
+| 8 | Status changes are recorded as new Version History rows with a Change summary and Commit link; retained rows are never rewritten | Pass | The change is a new row; the earlier `Accepted` row became `Deprecated` and its content is unchanged. |
+| 9 | A superseded or deprecated ADR names its successor, and the successor links back | Pass | The status names ADR-0009; ADR-0009 lists ADR-0004 under Affected Artifacts and in CrossReference. This closes the N-A of RC-018. |
+| 10 | Written in the language of the domain, with no unexplained abbreviations | Pass | Unchanged. |
+| 11 | Status is one of the allowed values and every row uses only these | Pass | `Deprecated` and `Superseded by ADR-0009`. |
+
+## Overall Verdict
+
+Go - all criteria pass. The scoped delivery and the marker are replaced and removed (MIL-009 tasks 2 to 6); the token and empty-folder rules of this ADR stand and are carried by ADR-0009. The AI records the acceptance as stand-in for S01; there is no independent reader, and the decision stays open to challenge in the run summary.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| None open | - | - |
+
+---
+
+[ADR-0004]: ../../adr/adr-0004-shared-wiki-publishing-opt-in.md
+[ADR-0009]: ../../adr/adr-0009-wiki-publishing-reusable-workflow.md
+[QC-ADR-001]: ../../../framework/qc/artifacts/qc-adr.md
+[MIL-009]: ../../milestones/mil-009-migrate-wiki-callers-and-remove-scoped-workflow.md
+[22fc323]: https://git.tirsystem.com/TirSystem/github-action/commit/22fc323b41074ee0029ea2f07445a8e329e15d15

docs/sqa/reviews/rc-066-mil-009-outcome.md

@@ -0,0 +1,52 @@
+# Review Record: MIL-009 outcome
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-066 |
+| CrossReference | [MIL-009], [QC-MIL-001], [RC-064], [ADR-0004] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version | [95abc18] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [MIL-009] after the verification results were recorded on 2026-10-14
+- Checklist used: [QC-MIL-001]
+- Scope: delta re-review of the Go / No-Go outcome; the earlier record is [RC-064]
+- Language and domain: n/a (technical type)
+- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`; the user accepted the plan in chat on 2026-10-14)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | A concrete deliverable is defined for every gate | Pass | Delivered: framework 0.7.0, seven callers, removals, ADR-0004 superseded, 2.0.0. |
+| 2 | Explicit Go/No-Go criteria are stated for each gate | Pass | All seven criteria have a recorded result, each with evidence. |
+| 3 | Dependencies on other milestones are explicitly mapped | Pass | MIL-008 and the framework release were met first. |
+| 4 | Each milestone is traceable to a Business Case objective or KPI | Pass | O2, O3, unchanged. |
+| 5 | Milestone owner and approving reviewer are identified | Pass | S05 and S01. |
+| 6 | Milestone has a defined target date consistent with project constraints | Pass | Target 2026-11-30; the gate was met on 2026-10-14. |
+
+## Overall Verdict
+
+Go - the gate is met: all seven criteria are Go (criterion 5 with a recorded note that the marker text remains in history records and the upgrade note). The AI records the outcome as stand-in for S01; there is no independent reader, and the decision stays open to challenge in the run summary.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| Fix the two failing tests of `repo-foundry` on `main` (the checklist layout of its test fixture); not part of this milestone | S05 | not planned |
+| Move the `framework` pin of `github-action` itself from `v0.6.2` to `v0.7.0` | S05 | not planned |
+
+---
+
+[MIL-009]: ../../milestones/mil-009-migrate-wiki-callers-and-remove-scoped-workflow.md
+[QC-MIL-001]: ../../../framework/qc/artifacts/qc-milestones-gateways.md
+[RC-064]: ./rc-064-mil-009-plan.md
+[ADR-0004]: ../../adr/adr-0004-shared-wiki-publishing-opt-in.md
+[95abc18]: https://git.tirsystem.com/TirSystem/github-action/commit/95abc18a95d70c065b979123b8f8de22173af90c

docs/sqa/reviews/rc-067-bc-001-o5.md

@@ -0,0 +1,52 @@
+# Review Record: BC-001 (objective O5, code metrics and coverage badges)
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-067 |
+| CrossReference | [BC-001], [QC-BC-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version; accepted | [5002450] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [BC-001]
+- Checklist used: [QC-BC-001]
+- Scope: delta re-review of criteria 3, 4 and 7 (the change adds objective O5, an In Scope bullet and success criterion 5); criteria 1, 2, 5, 6 and 8 are re-read and unchanged. Earlier record: RC-008
+- Language and domain: n/a for this delta (see the action item about the Language and Domain rows)
+- Language reviewer: none
+- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`; the user accepted the plan in chat on 2026-10-14)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | ROI/Cost-Benefit analysis is quantitative, or where qualitative, is explicitly justified | Pass | Unchanged; the Cost-Benefit Assessment labels its qualitative form. |
+| 2 | Risks are identified with documented impact and mitigation | Pass | Unchanged. The delivery risk of the badges is a plan risk in PP-001, with a mitigation. |
+| 3 | Success criteria are measurable, stating explicit targets rather than vague aspirations | Pass | Criterion 5: "At least 1 besides this one by MIL-010", measured in the README of the consuming repository. |
+| 4 | Scope explicitly separates In Scope vs Out of Scope | Pass | "A shared workflow for code metrics and coverage badges (MIL-010)" is a new In Scope bullet; Out of Scope is unchanged and does not contradict it ("application code of consuming repositories" is not read or changed by the counter). |
+| 5 | Stakeholders are cross-referenced to Stakeholder Analysis IDs rather than re-described inline | Pass | Unchanged; the stakeholders table uses S-IDs. |
+| 6 | Methodology and quality-standard foundation are stated explicitly (e.g. ISO/IEC 25010, Larman) | Pass | Unchanged. |
+| 7 | Assumptions and constraints are explicit and clearly distinguished from one another | Pass | Unchanged. The constraint "tools available on the runner" still holds: the counter uses the Python standard library. |
+| 8 | Document supports executive decision-making with a clear, unambiguous recommendation | Pass | Unchanged: Proceed. |
+
+## Overall Verdict
+
+Go - all eight criteria pass for the revision that adds objective O5, its scope item and success criterion 5. The user accepted the plan in chat on 2026-10-14; the AI records the acceptance as stand-in for S01. There is no independent reader and the decision stays open to challenge in the run summary.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| The Metadata table of BC-001 has no `Language` and `Domain` rows (QC-LANG-001 criterion 1); this predates this change, and no earlier record applies QC-LANG-001 to it. Add the rows or record in an ADR why they are not needed | S01 | Before the next material change to BC-001 |
+
+---
+
+[BC-001]: ../../business-case.md
+[QC-BC-001]: ../../../framework/qc/artifacts/qc-business-case.md
+[5002450]: https://git.tirsystem.com/TirSystem/github-action/commit/50024505fe788b1c5e3021c0d1fc3d079590070e

docs/sqa/reviews/rc-068-mil-010-plan.md

@@ -0,0 +1,63 @@
+# Review Record: MIL-010 and PP-001 (MIL-010)
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-068 |
+| CrossReference | [MIL-010], [PP-001], [BC-001], [QC-MIL-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version; accepted | [5002450] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [MIL-010]; delta of [PP-001] for the added milestone
+- Checklist used: [QC-MIL-001] for the milestone; for the plan, the criteria of `PP.md` (no QC checklist exists for PP-001)
+- Scope: full review of MIL-010; delta re-review of PP-001, earlier record RC-064
+- Language and domain: n/a (technical type)
+- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`; the user accepted the plan in chat on 2026-10-14)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | A concrete deliverable is defined for every gate | Pass | MIL-010 names the reusable workflow `code-metrics.yml`, the three SVG badges on a `badges` branch, the guide, three wiki languages, one adopter and a release. |
+| 2 | Explicit Go/No-Go criteria are stated for each gate | Pass | Nine criteria, each with a checkable Go and No-Go (push and render, ADR, fixture counts, bad report, valid stable SVG, no loop, adopter, no embedded script, release). |
+| 3 | Dependencies on other milestones are explicitly mapped | Pass | MIL-003 and MIL-004; in the plan's Dependencies diagram (`MIL-003 + MIL-004 -> MIL-010`). |
+| 4 | Each milestone is traceable to a Business Case objective or KPI | Pass | O5 of [BC-001], reviewed in RC-067. |
+| 5 | Milestone owner and approving reviewer are identified | Pass | Owner S05, approving reviewer S01. |
+| 6 | Milestone has a defined target date consistent with project constraints | Pass | 2027-01-30 follows MIL-007 (2027-01-16); the Business Case sets no deadline; the user accepted it in chat. |
+
+## Plan delta (PP-001)
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | Every milestone has a `MIL-*` document and the plan's dates equal that document's target date | Pass | MIL-001 to MIL-010 exist; the MIL-010 decision date equals its Target Date. |
+| 2 | Every Business Case scope item is covered by a gateway | Pass | Scope Coverage names MIL-010 for the new In Scope bullet. |
+| 3 | The schedule respects the Business Case constraints | Pass | No deadline in the Business Case; the window follows MIL-007. |
+| 4 | Dependencies between milestones are stated | Pass | `MIL-003 + MIL-004 -> MIL-010`. |
+| 5 | Every gateway has an owner who is a stakeholder ID | Pass | S05. |
+| 6 | Plan content is internally consistent | Pass | "Ten milestones", the assumptions, the Gantt, the schedule and the coverage agree. |
+| 7 | Open Issues are current | Pass | A plan risk was added for the push to the `badges` branch and the rendering on the mirror, with the fallback. |
+
+## Overall Verdict
+
+Go - all criteria pass. The user switched to autonomous mode and accepted the plan in chat on 2026-10-14 (Cobertura XML coverage input, target date 2027-01-30, three badges); the AI records the acceptance as stand-in for S01. There is no independent reader and the decision stays open to challenge in the run summary.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| None | - | - |
+
+---
+
+[MIL-010]: ../../milestones/mil-010-code-metrics-badges.md
+[PP-001]: ../../project-plan.md
+[BC-001]: ../../business-case.md
+[QC-MIL-001]: ../../../framework/qc/artifacts/qc-milestones-gateways.md
+[5002450]: https://git.tirsystem.com/TirSystem/github-action/commit/50024505fe788b1c5e3021c0d1fc3d079590070e

docs/sqa/reviews/rc-069-uc-008.md

@@ -0,0 +1,56 @@
+# Review Record: UC-008 (Show Code Metrics and Coverage Badges)
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-069 |
+| CrossReference | [UC-008], [QC-UC-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version; accepted | [9ca9673] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [UC-008]
+- Checklist used: [QC-UC-001]
+- Scope: full review (Brief format; MIL-010 task 1)
+- Language and domain: n/a (technical type)
+- Language reviewer: none
+- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`; the user accepted the plan in chat on 2026-10-14)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | Consists of a single, concise paragraph summarizing only the primary success scenario | Pass | One paragraph: push, count, read the report, publish three badges, README shows them. |
+| 2 | Written as an informal multi-paragraph narrative; may mention some alternate flows without formal structure | N-A | Format is Brief. |
+| 3 | All standard sections are present: actors, preconditions, postconditions, main success scenario, alternative/exception flows | N-A | Format is Brief; actor, stakeholders, pre- and postconditions and the paragraph are present. |
+| 4 | Preconditions and postconditions are explicitly defined | Pass | Both are stated; the postcondition says that only the badges change. |
+| 5 | Primary actor is explicitly stated | Pass | Software Engineer. |
+| 6 | Stakeholders and their interests are stated | Pass | S02 and S05 with an interest each. |
+| 7 | Main success scenario is written as clear, numbered steps | N-A | Format is Brief. |
+| 8 | Alternative/exception flows correctly reference `<<include>>`/`<<extend>>` use cases where relevant, per UML 2.5.1 | N-A | None in a Brief. |
+| 9 | Explicit business rules are captured per step where applicable, rather than embedded loosely in narrative text | N-A | No steps in a Brief. |
+| 10 | Naming of actors and use case title is consistent with the corresponding Use Case Diagram and User Stories | Pass | Title and actor equal UCD-001 (RC-071); the Stories line lists US-001.18 to US-001.20, which exist (RC-070). |
+| 11 | Scope/level (e.g. summary, user-goal, subfunction) is explicitly stated | Pass | Scope Reusable Workflow Collection, user-goal level. |
+| 12 | Use case is written from the actor's goal perspective, free of UI or implementation detail | Pass | Goal wording; no tool, file name or format of a report is named. |
+
+## Overall Verdict
+
+Go - all applicable criteria pass. The AI records the decision as stand-in for S01; there is no independent reader and the decision stays open to challenge in the run summary.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| None | - | - |
+
+---
+
+[UC-008]: ../../uc-008/uc.md
+[QC-UC-001]: ../../../framework/qc/artifacts/qc-use-case.md
+[9ca9673]: https://git.tirsystem.com/TirSystem/github-action/commit/9ca9673b00351cf913966f347c4da09890ed3f1f

docs/sqa/reviews/rc-070-us-001-metrics.md

@@ -0,0 +1,51 @@
+# Review Record: US-001 (stories US-001.18 to US-001.20)
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-070 |
+| CrossReference | [US-001], [QC-US-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version; accepted | [9ca9673] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [US-001]
+- Checklist used: [QC-US-001]
+- Scope: delta re-review of the added stories US-001.18 to US-001.20 and the Purpose and Scope and INVEST sections; earlier record RC-057 (US-001.01 to US-001.17 unchanged)
+- Language and domain: n/a (technical type)
+- Language reviewer: none
+- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`; the user accepted the plan in chat on 2026-10-14)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | Follows INVEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable) | Pass | US-001.18 to US-001.20 are independent of each other, each states one value and has checkable criteria; the INVEST section of US-001 now counts twenty stories. |
+| 2 | Written in "As a / I want / So that" form | Pass | All three stories. |
+| 3 | Clear, testable acceptance criteria are included | Pass | Each has Given/When/Then criteria with a pass and a fail case (a missing report, no files, unchanged numbers). |
+| 4 | Traceable to a use case or epic | Pass | Each traces to [UC-008] and [MIL-010]. |
+| 5 | Story is sized to fit within a single iteration | Pass | Each says: fits one iteration. |
+| 6 | Story statement avoids technical implementation detail | Pass | The statements name badges, files, lines and coverage; format and branch names are left to the contract. |
+| 7 | Role named in the story matches an actor defined in the Use Case Diagram | Pass | Software Engineer, an actor of UCD-001. |
+
+## Overall Verdict
+
+Go - all criteria pass. The AI records the decision as stand-in for S01; there is no independent reader and the decision stays open to challenge in the run summary.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| None | - | - |
+
+---
+
+[US-001]: ../../user-stories.md
+[QC-US-001]: ../../../framework/qc/artifacts/qc-user-story.md
+[9ca9673]: https://git.tirsystem.com/TirSystem/github-action/commit/9ca9673b00351cf913966f347c4da09890ed3f1f

docs/sqa/reviews/rc-071-ucd-001-metrics.md

@@ -0,0 +1,52 @@
+# Review Record: UCD-001 (Show Code Metrics and Coverage Badges)
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-071 |
+| CrossReference | [UCD-001], [QC-UCD-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version; accepted | [9ca9673] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [UCD-001]
+- Checklist used: [QC-UCD-001]
+- Scope: delta re-review of the added use case UC8, the actor and use case tables; earlier record RC-045
+- Language and domain: n/a (technical type)
+- Language reviewer: none
+- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`; the user accepted the plan in chat on 2026-10-14)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | Actors are defined with correct UML stereotypes (e.g. `<<System>>`, `<<Actor>>`) | Pass | Unchanged; no new actor. |
+| 2 | System boundary is clearly drawn and labeled | Pass | The new use case is inside the Reusable Workflow Collection rectangle. |
+| 3 | Include/extend relationships are used correctly per UML 2.5.1, not as generic "uses" arrows | Pass | The new use case has no include or extend; the existing two are unchanged. |
+| 4 | Every actor participates in at least one use case (no orphan actors) | Pass | Software Engineer is linked to UC5, UC7 and UC8. |
+| 5 | Diagram is traceable to a documented stakeholder need | Pass | S02 and S05 interests are in UC-008; the actor table lists S02. |
+| 6 | Use case names are verb phrases describing actor goals, not internal system operations | Pass | Show Code Metrics and Coverage Badges. |
+| 7 | Diagram is free of implementation detail (e.g. UI widgets, database tables) | Pass | None added. |
+| 8 | Actor and use case naming is consistent with corresponding Use Case and User Story documents | Pass | Equals the title of UC-008 and the role of US-001.18 to US-001.20. |
+
+## Overall Verdict
+
+Go - all criteria pass. The AI records the decision as stand-in for S01; there is no independent reader and the decision stays open to challenge in the run summary.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| None | - | - |
+
+---
+
+[UCD-001]: ../../use-case-diagram.md
+[QC-UCD-001]: ../../../framework/qc/artifacts/qc-use-case-diagram.md
+[9ca9673]: https://git.tirsystem.com/TirSystem/github-action/commit/9ca9673b00351cf913966f347c4da09890ed3f1f

docs/sqa/reviews/rc-072-adr-0010.md

@@ -0,0 +1,55 @@
+# Review Record: ADR-0010 (contract of the code metrics and coverage badges workflow)
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-072 |
+| CrossReference | [ADR-0010], [QC-ADR-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version; accepted | [aa4ca0f] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [ADR-0010]
+- Checklist used: [QC-ADR-001]
+- Scope: full review (MIL-010 task 2)
+- Language and domain: n/a (technical type)
+- Language reviewer: none
+- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`; the user accepted the plan in chat on 2026-10-14)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | The ID (`ADR-NNNN`, 4-digit) matches the filename number and is unique and sequential | Pass | ADR-0010 in `adr-0010-code-metrics-badges-contract.md`; the previous ADR is ADR-0009. |
+| 2 | Context states the problem, the forces (cost, risk, constraints) and the options evaluated | Pass | Problem, the decisions of the user, facts about the runner and the checkout directory, two counter options and three delivery options. |
+| 3 | At least two options were considered, or the absence of alternatives is justified | Pass | Wrap an existing counter or write one; run artifact, default branch or a branch. |
+| 4 | Decision is stated in one or two unhedged sentences and matches one of the evaluated options | Pass | A reusable workflow with three script files and a `badges` branch; the rules follow as a list. |
+| 5 | Consequences list both Positive and Negative outcomes | Pass | Four positive, five negative. |
+| 6 | Quality-attribute impacts (performance, security, portability, etc.) are named where the decision affects them | Pass | Security (a write token, a moving `tools-ref`, branch name validation), compatibility (report formats), maintainability (language table). |
+| 7 | Affected Artifacts are listed as links, and each is also in CrossReference | Pass | MIL-010, UC-008, US-001, ADR-0005, ADR-0006 in both. |
+| 8 | Status changes are recorded as new Version History rows with a Change summary and Commit link; retained rows are never rewritten | Pass | One row, Accepted, commit `pending` until the commit exists. |
+| 9 | A superseded or deprecated ADR names its successor, and the successor links back | N-A | Neither superseded nor deprecated. |
+| 10 | Written in business or technical language of the domain, with no unexplained abbreviations | Pass | SVG, XML and NUL are standard; Cobertura is named as a format. |
+| 11 | Status is one of `Proposed`, `Accepted`, `Rejected`, `Deprecated` or `Superseded by ADR-NNNN`, and every Version History row uses only these | Pass | Accepted. |
+
+## Overall Verdict
+
+Go - all applicable criteria pass; the decisions of the user of 2026-10-14 are recorded and not reopened. The AI records the decision as stand-in for S01; there is no independent reader and the decision stays open to challenge in the run summary.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| None | - | - |
+
+---
+
+[ADR-0010]: ../../adr/adr-0010-code-metrics-badges-contract.md
+[QC-ADR-001]: ../../../framework/qc/artifacts/qc-adr.md
+[aa4ca0f]: https://git.tirsystem.com/TirSystem/github-action/commit/aa4ca0f897b7ea20d90745aa4b7d7a215df123a8

docs/sqa/reviews/rc-073-adr-0010-artifact.md

@@ -0,0 +1,55 @@
+# Review Record: ADR-0010 (the coverage report as an artifact of the caller)
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-073 |
+| CrossReference | [ADR-0010], [QC-ADR-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version; accepted | [0dc5132] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [ADR-0010]
+- Checklist used: [QC-ADR-001]
+- Scope: delta re-review of the Coverage report and Inputs rules, the Consequences and the Version History after the implementation of MIL-010 task 6 showed that a called workflow cannot see the files of the caller's test job; earlier record RC-072
+- Language and domain: n/a (technical type)
+- Language reviewer: none
+- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`; the user accepted the plan in chat on 2026-10-14)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | The ID (`ADR-NNNN`, 4-digit) matches the filename number and is unique and sequential | Pass | Unchanged. |
+| 2 | Context states the problem, the forces (cost, risk, constraints) and the options evaluated | Pass | Unchanged; the new force (a called workflow runs in its own job) is stated in the Decision rule that it explains. |
+| 3 | At least two options were considered, or the absence of alternatives is justified | Pass | Unchanged. For the report: an artifact of the caller's run, or a file committed to the repository; both are supported. |
+| 4 | Decision is stated in one or two unhedged sentences and matches one of the evaluated options | Pass | The Decision sentence is unchanged; the coverage rule is a refinement of it. |
+| 5 | Consequences list both Positive and Negative outcomes | Pass | The negative consequence about the report now names the earlier job, the upload and the dependency on the artifact service, which task 8 verifies. |
+| 6 | Quality-attribute impacts (performance, security, portability, etc.) are named where the decision affects them | Pass | The security bullet says the artifact is parsed as XML with entity declarations refused. |
+| 7 | Affected Artifacts are listed as links, and each is also in CrossReference | Pass | Unchanged. |
+| 8 | Status changes are recorded as new Version History rows with a Change summary and Commit link; retained rows are never rewritten | Pass | A new row; the earlier Accepted row became Deprecated and was not rewritten otherwise. |
+| 9 | A superseded or deprecated ADR names its successor, and the successor links back | N-A | The ADR is amended, not superseded. |
+| 10 | Written in business or technical language of the domain, with no unexplained abbreviations | Pass | Artifact is the term of the Actions runtime. |
+| 11 | Status is one of `Proposed`, `Accepted`, `Rejected`, `Deprecated` or `Superseded by ADR-NNNN`, and every Version History row uses only these | Pass | Deprecated and Accepted. |
+
+## Overall Verdict
+
+Go - all applicable criteria pass; the amendment keeps the decisions of the user of 2026-10-14 and corrects a mechanism that cannot work as first written. The AI records the decision as stand-in for S01; there is no independent reader and the decision stays open to challenge in the run summary.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| None | - | - |
+
+---
+
+[ADR-0010]: ../../adr/adr-0010-code-metrics-badges-contract.md
+[QC-ADR-001]: ../../../framework/qc/artifacts/qc-adr.md
+[0dc5132]: https://git.tirsystem.com/TirSystem/github-action/commit/0dc5132a2ea419ba05035ee3594cec63335c240b

docs/sqa/reviews/rc-074-mil-010-results.md

@@ -0,0 +1,51 @@
+# Review Record: MIL-010 (results of tasks 3, 6 and 8)
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-074 |
+| CrossReference | [MIL-010], [QC-MIL-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version; accepted | [5c5a1d1] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [MIL-010]
+- Checklist used: [QC-MIL-001]
+- Scope: delta re-review of the Verification results section (tasks 3, 6 and 8) and the Version History; the Go/No-Go criteria, deliverable and tasks are unchanged since RC-068
+- Language and domain: n/a (technical type)
+- Language reviewer: none
+- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`; the user accepted the plan in chat on 2026-10-14)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | A concrete deliverable is defined for every gate | Pass | Unchanged; the results show the workflow, the three badges and a use in another repository. |
+| 2 | Explicit Go/No-Go criteria are stated for each gate | Pass | Unchanged. Evidence so far: criterion 1 (task 3: push with the token of the run, SVG served as image on the instance and the mirror), 2 (ADR-0010, RC-072, RC-073), 3 and 4 (offline fixtures and reports), 5 (valid, stable SVG, offline tests), 6 (no run from the badge push, no commit when unchanged in offline tests, `contents: write` only), 7 (throwaway repository: badges, colour change, named failure), 8 (the workflow runs three script files, no embedded script). Criterion 9 (release) follows in task 9. |
+| 3 | Dependencies on other milestones are explicitly mapped | Pass | Unchanged: MIL-003 and MIL-004. |
+| 4 | Each milestone is traceable to a Business Case objective or KPI | Pass | O5 and success criterion 5; criterion 5 is met in the throwaway repository and still wants a project repository. |
+| 5 | Milestone owner and approving reviewer are identified | Pass | Unchanged: S05 and S01. |
+| 6 | Milestone has a defined target date consistent with project constraints | Pass | Unchanged: 2027-01-30. |
+
+## Overall Verdict
+
+Go - the recorded results support the criteria 1 to 8; criterion 9 is decided after the release (task 9). The AI records the decision as stand-in for S01; there is no independent reader and the decision stays open to challenge in the run summary.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| Delete the throwaway repository `TirSystem/code-metrics-adoption` and the branches `verify-badges-delivery` and `badges-verify` of `TirSystem/github-action` (and their copies on the GitHub mirror); the run does not delete repositories or branches | S01 | after the review of the summary |
+| Adopt the workflow in a project repository so that success criterion 5 of the Business Case is met by a real project | S01 | next project that has tests |
+
+---
+
+[MIL-010]: ../../milestones/mil-010-code-metrics-badges.md
+[QC-MIL-001]: ../../../framework/qc/artifacts/qc-milestones-gateways.md
+[5c5a1d1]: https://git.tirsystem.com/TirSystem/github-action/commit/5c5a1d19d96a6979b4f6141e736957174ba686a9

docs/sqa/reviews/rc-075-mil-010-outcome.md

@@ -0,0 +1,52 @@
+# Review Record: MIL-010 (outcome: release 2.1.0)
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-075 |
+| CrossReference | [MIL-010], [QC-MIL-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version; accepted | [aa20e56] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [MIL-010]
+- Checklist used: [QC-MIL-001]
+- Scope: delta re-review of the results of task 9 and the closing statement of the milestone; earlier records RC-068 and RC-074
+- Language and domain: n/a (technical type)
+- Language reviewer: none
+- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`; the user accepted the plan in chat on 2026-10-14)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | A concrete deliverable is defined for every gate | Pass | Delivered: `code-metrics.yml` with its three script files, the guide, the wiki pages in three languages and the release 2.1.0 (tag `v2.1.0`, major tag `v2`, release page). |
+| 2 | Explicit Go/No-Go criteria are stated for each gate | Pass | All nine criteria are met: 1 to 8 in the results of RC-074, 9 by the release of 2.1.0 (runs 1462 and 1463, the tag and the release page read back through the API). |
+| 3 | Dependencies on other milestones are explicitly mapped | Pass | MIL-003 and MIL-004 were used: the reusable workflow mechanism, `tools-ref` and the release workflow. |
+| 4 | Each milestone is traceable to a Business Case objective or KPI | Pass | O5. Success criterion 5 is met only in a throwaway repository; a project repository still has to adopt it, recorded as an action item. |
+| 5 | Milestone owner and approving reviewer are identified | Pass | S05 and S01. |
+| 6 | Milestone has a defined target date consistent with project constraints | Pass | Target date 2027-01-30; the work was done on 2026-10-14, ahead of it. |
+
+## Overall Verdict
+
+Go - the milestone is complete: every Go/No-Go criterion is met and the workflow is released as 2.1.0. The AI records the decision as stand-in for S01; there is no independent reader and the decision stays open to challenge in the run summary.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| Adopt `code-metrics.yml` in a project repository, so that success criterion 5 is met by a real project | S01 | next project that has tests |
+| Delete the throwaway repository `TirSystem/code-metrics-adoption` and the branches `verify-badges-delivery` and `badges-verify` (and their copies on the GitHub mirror) | S01 | after the review of the summary |
+| Find where the required check `TirSystem/github-action: Publish wiki / *` comes from; it blocked the merge of pull request 164 through the API and is not in the branch protection of the repository | S03 | before the next pull request |
+
+---
+
+[MIL-010]: ../../milestones/mil-010-code-metrics-badges.md
+[QC-MIL-001]: ../../../framework/qc/artifacts/qc-milestones-gateways.md
+[aa20e56]: https://git.tirsystem.com/TirSystem/github-action/commit/aa20e56110f4c2fab91a8432ba008ee8300926a2

docs/sqa/reviews/rc-076-mil-011-plan.md

@@ -0,0 +1,67 @@
+# Review Record: MIL-011 and PP-001 (MIL-011)
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-076 |
+| CrossReference | [MIL-011], [PP-001], [BC-001], [QC-MIL-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version; accepted by the author in chat as stand-in for S01, after three corrections found in the first read | [3d7a9df] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [MIL-011]; delta of [PP-001] for the added milestone
+- Checklist used: [QC-MIL-001] for the milestone; for the plan, the criteria of `PP.md` (no QC checklist exists for PP-001)
+- Scope: full review of MIL-011; delta re-review of PP-001, earlier record [RC-068]
+- Language and domain: n/a (technical type)
+- Mode: supervised, not independent (the author, Jens Tirsvad Nielsen, asked in chat on 2026-10-14 for the review and the acceptance and stands in for S01; the AI prepared the evidence)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | A concrete deliverable is defined for every gate | Pass | `## Deliverable` names the patch release 2.1.1: the defaults, the test, the guides, README and three wiki languages at `@v2`, the changelog entry, and the framework `Badges` page without the workaround. |
+| 2 | Explicit Go/No-Go criteria are stated for each gate | Pass | Eight criteria, each with a checkable Go and No-Go: reproduction, a list per workflow, a test that fails on a seeded default, a search that finds no `@v1`, a run on the instance, the release level and tags, the framework page, the review record. |
+| 3 | Dependencies on other milestones are explicitly mapped | Pass | [MIL-010] (the workflow and its guide) and [ADR-0006] (the release process); in the plan's dependency diagram (`MIL-010 -> MIL-011`). |
+| 4 | Each milestone is traceable to a Business Case objective or KPI | Pass | O5 of [BC-001]; the first read found its wording paraphrased wrongly, now quoted from the Business Case. |
+| 5 | Milestone owner and approving reviewer are identified | Pass | Owner S05, approving reviewer S01; both are in [SA-001]. |
+| 6 | Milestone has a defined target date consistent with project constraints | Pass | 2026-10-23; the Business Case sets no deadline. The date precedes the planned decision date of [MIL-010] (2027-01-30) because that milestone was released on 2026-10-14; the milestone says so and does not change the MIL-010 row. |
+
+## Plan delta (PP-001)
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | Every milestone has a `MIL-*` document and the plan's dates equal that document's target date | Pass | MIL-001 to MIL-011 exist; the MIL-011 decision date (2026-10-23) equals its Target Date. |
+| 2 | Every Business Case scope item is covered by a gateway | Pass | The first read found a scope row that is not a Business Case item; it is removed and MIL-011 is listed beside MIL-010 for the badges item. |
+| 3 | The schedule respects the Business Case constraints | Pass | No deadline in the Business Case; the window is one week. |
+| 4 | Dependencies between milestones are stated | Pass | `MIL-003 + MIL-004 -> MIL-010 -> MIL-011`. |
+| 5 | Every gateway has an owner who is a stakeholder ID | Pass | S05. |
+| 6 | Plan content is internally consistent | Pass | The first read found "ten milestones" in the Purpose; it is now "eleven", and the Gantt, the schedule and the dependencies agree. |
+| 7 | Open Issues are current | Pass | No plan risk was added for a default that names an old major; the release process and the test of task 3 carry the rule. Observation, not a failure. |
+
+## Overall Verdict
+
+Go - all criteria pass after three corrections found in the first read (the O5 wording, "ten milestones", and a scope row that was not a Business Case item). The author confirmed the acceptance in chat on 2026-10-14 as stand-in for S01; this is not an independent review.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| Confirm this record by S01 when an independent reading is possible | S01 | 2026-10-30 |
+| Task 1: reproduce the failure and list the defaults before any change to the workflows | S05 | 2026-10-16 |
+
+---
+
+[MIL-011]: ../../milestones/mil-011-code-metrics-default-tools-ref.md
+[PP-001]: ../../project-plan.md
+[BC-001]: ../../business-case.md
+[SA-001]: ../../stakeholder-analysis.md
+[ADR-0006]: ../../adr/adr-0006-release-process-and-version-pinning.md
+[RC-068]: ./rc-068-mil-010-plan.md
+[QC-MIL-001]: ../../../framework/qc/artifacts/qc-milestones-gateways.md
+[3d7a9df]: https://git.tirsystem.com/TirSystem/github-action/commit/3d7a9df3a3a4712dcc5214a71b0569d90122bf4e

docs/sqa/reviews/rc-077-mil-011-task-1-results.md

@@ -0,0 +1,50 @@
+# Review Record: MIL-011 task 1 results (delta)
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-077 |
+| CrossReference | [MIL-011], [RC-076], [QC-MIL-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version; accepted | [eaa0e30] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [MIL-011], the Version History row and the section "Verification results" added in project pull request 177 (the results of task 1)
+- Checklist used: [QC-MIL-001] (criteria 1, 2 and 4 re-scored; 3, 5 and 6 not affected)
+- Scope: delta re-review, reason: the milestone changed in content after [RC-076]
+- Language and domain: n/a (technical type)
+- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`; the user chose autonomous mode in chat on 2026-10-14 and the accepted plan is [MIL-011])
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | A concrete deliverable is defined for every gate | Pass | `## Deliverable` is unchanged and task 1 has its record: the results name the run (1499, job 1638), the commits and the five workflows. |
+| 2 | Explicit Go/No-Go criteria are stated for each gate | Pass | Criterion 1 ("reproduced and recorded") and criterion 2 ("all five checked and listed") are met by the section; the evidence was read from the run's log (`bash: shared-scripts/tools/code-metrics.sh: No such file or directory`, exit code 127) and from `git cat-file` per tag. |
+| 3 | Dependencies on other milestones are explicitly mapped | N-A | Not affected. |
+| 4 | Each milestone is traceable to a Business Case objective or KPI | Pass | Unchanged (O5). |
+| 5 | Milestone owner and approving reviewer are identified | N-A | Not affected. |
+| 6 | Milestone has a defined target date consistent with project constraints | N-A | Not affected (2026-10-23). |
+
+## Overall Verdict
+
+Go - the results are true to the evidence: the failure at `@v2` is in the log of job 1638, and the absence of a run at `@v1` was observed on two pushes (`5654905`, `46e752d`) against a run for the `@v2` call alone (`9a17868`). The finding that the other four workflows resolve but follow the older major is stated as a question for task 2, not as a defect. The AI accepts the row as stand-in for S01; there is no independent reader and the decision stays open to challenge in the run summary.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| None | - | - |
+
+---
+
+[MIL-011]: ../../milestones/mil-011-code-metrics-default-tools-ref.md
+[RC-076]: ./rc-076-mil-011-plan.md
+[QC-MIL-001]: ../../../framework/qc/artifacts/qc-milestones-gateways.md
+[eaa0e30]: https://git.tirsystem.com/TirSystem/github-action/commit/eaa0e30beaa097dfeb1c07c814a71d02a6987060

docs/sqa/reviews/rc-078-mil-011-fix.md

@@ -0,0 +1,56 @@
+# Review Record: MIL-011 fix of the tools-ref defaults
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-078 |
+| CrossReference | [MIL-011], [RC-077] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-14 | Proposed | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version: Go for tasks 2 to 5, criteria 6 to 8 open until the release | [a6892c3] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: the deliverables of tasks 2 to 5 of [MIL-011], branch `mil-011-fix` at `eaa0e30` (the five workflows, `MAJOR_TAG`, `tests/test_tools_ref.py` and the three changed tests, the guides, README and wiki pages in three languages, the amended ADR-0005, ADR-0008, ADR-0009 and ADR-0010, the changelog)
+- Checklist used: the eight Go/No-Go criteria of [MIL-011]; for the workflow files and the tests, the review is the pass of the repository's own test suite and the validation workflow
+- Scope: full review of the deliverables before the release (task 6); the milestone itself was reviewed in [RC-076] and [RC-077]
+- Language and domain: n/a (technical deliverables)
+- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`)
+
+## Checklist Results
+
+Go/No-Go criteria of [MIL-011]:
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | The defect is reproduced before the fix | Pass | Run 1499 (job 1638): `bash: shared-scripts/tools/code-metrics.sh: No such file or directory`, exit code 127; a call at `@v1` creates no run. Recorded in [MIL-011], "Verification results". |
+| 2 | Every default `tools-ref` names a tag that holds the script | Pass | Listed per workflow in [MIL-011]. After the fix all five name `v2` (`MAJOR_TAG`), and the script of each is in `v2`; `test_default_tools_ref_is_the_current_major_and_holds_the_script` checks the tag with `git cat-file`. |
+| 3 | The default is derived and a test fails on a seeded wrong default | Pass | `MAJOR_TAG` is the one definition, and a test ties it to the highest major of the changelog. With `default: "v1"` seeded in `code-metrics.yml` three tests failed ("default tools-ref is 'v1', the current major is 'v2'"); restored, 13 passed. The full suite passes: 540 tests. |
+| 4 | No guide, comment, README or wiki page tells a caller to use `@v1` for `code-metrics.yml` | Pass | `grep -rn 'code-metrics.yml@v1' guides README.md docs/wiki .gitea` finds 0; no `default: "v1"` is left in `.gitea/workflows`. The accepted ADRs keep their original text and have an amendment; the body of ADR-0010 still reads "default `v1`" above the amendment, which is how amendments are read. |
+| 5 | A call with the documented defaults runs on the instance and commits the badges | Pass | Run 1509 (job 1649) of the throwaway branch `verify-code-metrics-defaults`: the workflow at `@mil-011-fix`, `tools-ref` resolved to `v2` (scripts fetched at `16faffa`), "Validate", "Count" and "Publish the badges" succeeded, branch `badges-verify` has the commit `041d991` "Update code metrics badges [skip ci]", and the raw SVG answers `200 image/svg+xml`. Only `badges-branch` was set, to keep the verification away from `badges`. |
+| 6 | The release is a patch (2.1.1); `v2` moves to it, `v1` is untouched | Open | Not released: task 6. Re-scored in the record after the release. |
+| 7 | The framework `Badges` page no longer tells a caller to set `tools-ref` | Open | Task 7, after the release. |
+| 8 | Reviewed | Open | This record covers criteria 1 to 5; the record after the release closes 6 to 8. |
+
+## Overall Verdict
+
+Go for the deliverables of tasks 2 to 5: criteria 1 to 5 pass on the evidence above. Criteria 6 to 8 are open only because the steps that satisfy them (the release and the framework page) come after this review; nothing in the deliverables is missing. The AI accepts the record as stand-in for S01 in autonomous mode; there is no independent reader and the decision stays open to challenge in the run summary.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| Release 2.1.1 and re-score criteria 6 and 8 | S05 | 2026-10-23 |
+| Remove the `tools-ref` workaround from the framework `Badges` page and re-score criterion 7 | S05 | 2026-10-23 |
+| Delete the throwaway branch `verify-code-metrics-defaults` after the results are merged | S05 | 2026-10-23 |
+
+---
+
+[MIL-011]: ../../milestones/mil-011-code-metrics-default-tools-ref.md
+[RC-076]: ./rc-076-mil-011-plan.md
+[RC-077]: ./rc-077-mil-011-task-1-results.md
+[a6892c3]: https://git.tirsystem.com/TirSystem/github-action/commit/a6892c372aca9f2e12826a4c3b260290a0656ecb

docs/sqa/reviews/rc-079-mil-011-outcome.md

@@ -0,0 +1,50 @@
+# Review Record: MIL-011 outcome (release 2.1.1)
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-079 |
+| CrossReference | [MIL-011], [RC-078] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version; Go; accepted by the AI as stand-in for S01 in autonomous mode, not independent | [4aa3fd3] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: the outcome of [MIL-011]: the release `v2.1.1` of this repository (tag on `3023461`, the release page, the moving major tag `v2`) and the framework `Badges` page (`TirSystem/sqa-qc-framework` pull request 57)
+- Checklist used: the eight Go/No-Go criteria of [MIL-011]; criteria 1 to 5 were scored in [RC-078] and are not repeated
+- Scope: re-score of criteria 6, 7 and 8, after the release
+- Language and domain: n/a (technical type)
+- Mode: autonomous, not independent (the reviewer is `AI as stand-in for S01`)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 to 5 | See [RC-078] | Pass | Reproduced (run 1499), every default checked, the default derived from `MAJOR_TAG` with a failing seeded test, no `@v1` for `code-metrics.yml`, a run on the instance (run 1509). |
+| 6 | The release is a patch (2.1.1); `v2` moves to it, `v1` is untouched | Pass | The Release workflow ran in dry-run mode (run 1524: "Checks passed for v2.1.1 on 3023461 ... would create the release page v2.1.1 and point v2 to it") and then for real (run 1525). `git ls-remote`: `v2.1.1` and `v2` (peeled) are `3023461`; `v1` is `1.2.2` (`9bf0a2b`), unchanged. The release page has the changelog entry as its text. After the release a call at `@v2` with the defaults ran on the instance (run 1526, job 1670): `tools-ref: v2`, the scripts fetched at `3023461`, badges published to `badges-verify`. |
+| 7 | The framework `Badges` page no longer tells a caller to set `tools-ref` | Pass | `TirSystem/sqa-qc-framework` pull request 57 is merged and the wiki is published: the three pages have no `tools-ref: v2` line and no bullet about it, call the workflow at `@v2`, and say to use 2.1.1 or later, not 2.1.0. |
+| 8 | Reviewed | Pass | [RC-076], [RC-077], [RC-078] and this record, each with a verdict of Go; [MIL-011] and its plan row are `Accepted`. |
+
+## Overall Verdict
+
+Go - all eight criteria pass. The defect is fixed in release 2.1.1: the default `tools-ref` of the five reusable workflows is the current major (`MAJOR_TAG`), a test keeps it so, and a call at `@v2` with the defaults runs. Two things stay as they are and are reported, not decided here: release `2.1.0` still has the defect (a release tag is never moved, ADR-0006) and callers are told to use 2.1.1 or later; and the other four workflows now fetch their scripts from the current major instead of `1.2.2`, which changes no behaviour for a caller at `@v1`. The AI accepts the record as stand-in for S01 in autonomous mode; there is no independent reader and the decision stays open to challenge in the run summary.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| Delete the throwaway branch `verify-code-metrics-defaults` when the evidence is no longer needed (a branch deletion is left to a person) | S05 | 2026-10-23 |
+| Decide whether the required status check `Sync GitHub mirror metadata / sync-metadata (push)` should stay required on pull requests, where it is only `skipped` and blocks a merge through the API | S05 | 2026-10-30 |
+
+---
+
+[MIL-011]: ../../milestones/mil-011-code-metrics-default-tools-ref.md
+[RC-078]: ./rc-078-mil-011-fix.md
+[RC-076]: ./rc-076-mil-011-plan.md
+[RC-077]: ./rc-077-mil-011-task-1-results.md
+[4aa3fd3]: https://git.tirsystem.com/TirSystem/github-action/commit/4aa3fd38f97c26a5d52abc566e958759583ccb85

docs/sqa/reviews/rc-080-mil-012-plan.md

@@ -0,0 +1,73 @@
+# Review Record: MIL-012 and PP-001 (MIL-012)
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-080 |
+| CrossReference | [MIL-012], [PP-001], [BC-001], [QC-MIL-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-19 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version; accepted by the author in chat as stand-in for S01, after three corrections found in the first read | [c5d5941] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [MIL-012]; delta of [PP-001] for the added milestone
+- Checklist used: [QC-MIL-001] for the milestone; for the plan, the criteria of `PP.md` (no QC checklist exists for PP-001)
+- Scope: full review of MIL-012; delta re-review of PP-001, earlier record [RC-076]
+- Language and domain: n/a (technical type)
+- Mode: supervised, not independent (the author, Jens Tirsvad Nielsen, asked in chat on 2026-10-19 for the acceptance and stands in for S01; the AI prepared the evidence)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | A concrete deliverable is defined for every gate | Pass | `## Deliverable` names release 2.2.0 with the two composite actions, their guides, README section, wiki pages in three languages, changelog entry and test; a record of one successful job per action; an ADR; and the framework templates pinned to the release tag. |
+| 2 | Explicit Go/No-Go criteria are stated for each gate | Pass | Ten criteria, each with a checkable Go and No-Go: the `uses:` form that resolves, a recorded run per action with the cleanup shown, no secret in any log (a search with a count), verified runner requirements, linting with a seeded error, a search that finds no branch reference, the release level and tags, the framework pull request, the review record. |
+| 3 | Dependencies on other milestones are explicitly mapped | Pass | [MIL-004] (the Release workflow) and [MIL-011] (`MAJOR_TAG`), [ADR-0006], and the two outside dependencies on S03 (runner, test peers) and on the branch of `TirSystem/sqa-qc-framework`; in the plan's dependency diagram (`MIL-004 + MIL-011 -> MIL-012`). The first read found the operator named S05; the Business Case and the Stakeholder Analysis give runners and secrets to S03, now corrected. |
+| 4 | Each milestone is traceable to a Business Case objective or KPI | Pass | Objective O6 and success criterion 6 of [BC-001], added in the same change and reviewed in [RC-081]. The first read found the milestone calling O6 "proposed in task 9", which would have left it untraceable until later; now the objective exists and task 9 writes the ADR only. |
+| 5 | Milestone owner and approving reviewer are identified | Pass | Owner S05, approving reviewer S01; both are in [SA-001]. |
+| 6 | Milestone has a defined target date consistent with project constraints | Pass | 2026-11-06, confirmed by S01 in chat on 2026-10-19; the Business Case sets no deadline. The window (2026-10-26 to 2026-11-06) overlaps [MIL-002] and [MIL-003], which are documentation and quality checks and do not use the runner's network; the plan says so. |
+
+## Plan delta (PP-001)
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | Every milestone has a `MIL-*` document and the plan's dates equal that document's target date | Pass | MIL-001 to MIL-012 exist; the MIL-012 decision date (2026-11-06) equals its Target Date. |
+| 2 | Every Business Case scope item is covered by a gateway | Pass | The new scope item "Shared composite actions that connect a deployment job to a private network" is covered by [MIL-012] in the scope table. |
+| 3 | The schedule respects the Business Case constraints | Pass | No deadline in the Business Case; the window is two weeks. |
+| 4 | Dependencies between milestones are stated | Pass | `MIL-004 + MIL-011 -> MIL-012`. |
+| 5 | Every gateway has an owner who is a stakeholder ID | Pass | S05. |
+| 6 | Plan content is internally consistent | Pass | The first read found a broken link target in the milestone (a wrong ADR-0006 file name and two milestone file names), now checked by resolving every link of the file. The Purpose says "twelve", and the Gantt, the schedule, the scope table and the dependencies agree. |
+| 7 | Open Issues are current | Pass | A plan risk is added: the runner cannot give `NET_ADMIN` and `/dev/net/tun`, or `tailscaled` does not survive to the next step, with the mitigation in tasks 2 to 4. |
+
+## Overall Verdict
+
+Go - all criteria pass after three corrections found in the first read (the operator S05 where the Business Case says S03, the objective O6 left as a proposal, and three wrong link targets). The author confirmed the acceptance in chat on 2026-10-19 as stand-in for S01; this is not an independent review.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| Confirm this record by S01 when an independent reading is possible | S01 | 2026-11-02 |
+| Task 2: ask the operator for the `vpn` runner and the test peers before task 3 starts; nothing in this milestone creates them | S03 | 2026-10-30 |
+| The code of both actions, their tests and guides already exist on the unreleased branch `wireguard-vpn-action`; commit it with `Task: MIL-012#N` trailers (tasks 3, 4, 6 and 7 own it) only after the milestone is published as issues | S05 | Before the first commit on that branch |
+
+---
+
+[MIL-012]: ../../milestones/mil-012-vpn-actions-for-deployment.md
+[PP-001]: ../../project-plan.md
+[BC-001]: ../../business-case.md
+[SA-001]: ../../stakeholder-analysis.md
+[MIL-002]: ../../milestones/mil-002-onboarding-and-operations.md
+[MIL-003]: ../../milestones/mil-003-quality-checks.md
+[MIL-004]: ../../milestones/mil-004-versioned-release.md
+[MIL-011]: ../../milestones/mil-011-code-metrics-default-tools-ref.md
+[ADR-0006]: ../../adr/adr-0006-release-process-and-version-pinning.md
+[RC-076]: ./rc-076-mil-011-plan.md
+[RC-081]: ./rc-081-bc-001-o6.md
+[QC-MIL-001]: ../../../framework/qc/artifacts/qc-milestones-gateways.md
+[c5d5941]: https://git.tirsystem.com/TirSystem/github-action/commit/c5d59418698316866807388bf61dcb6166d9fa8b

docs/sqa/reviews/rc-081-bc-001-o6.md

@@ -0,0 +1,53 @@
+# Review Record: BC-001 (objective O6, VPN actions for deployment)
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-081 |
+| CrossReference | [BC-001], [QC-BC-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-19 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version; accepted by the author in chat as stand-in for S01 | [c5d5941] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [BC-001]
+- Checklist used: [QC-BC-001]
+- Scope: delta re-review of criteria 2, 3, 4 and 7 (the change adds objective O6, an In Scope bullet, an assumption, a constraint and success criterion 6); criteria 1, 5, 6 and 8 are re-read and unchanged. Earlier record: [RC-067]
+- Language and domain: n/a for this delta (the action item of [RC-067] about the Language and Domain rows is still open)
+- Language reviewer: none
+- Mode: supervised, not independent (the author, Jens Tirsvad Nielsen, asked in chat on 2026-10-19 for the acceptance and stands in for S01; the AI prepared the evidence)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | ROI/Cost-Benefit analysis is quantitative, or where qualitative, is explicitly justified | Pass | Unchanged; the Cost-Benefit Assessment labels its qualitative form. |
+| 2 | Risks are identified with documented impact and mitigation | Pass | The delivery risk of the VPN actions (the runner cannot give the privileges, or the daemon does not survive between steps) is a plan risk in PP-001 with a mitigation; the Business Case risks about secrets already cover a leaked key. |
+| 3 | Success criteria are measurable, stating explicit targets rather than vague aspirations | Pass | Criterion 6: "2 (WireGuard and Tailscale) by MIL-012", measured by the recorded runs of tasks 3 to 5, with no secret in the run log. |
+| 4 | Scope explicitly separates In Scope vs Out of Scope | Pass | "Shared composite actions that connect a deployment job to a private network through WireGuard or Tailscale (MIL-012)" is a new In Scope bullet. Out of Scope is unchanged and consistent: operating runners stays out, and the new assumption says S03 provides the privileged runner. |
+| 5 | Stakeholders are cross-referenced to Stakeholder Analysis IDs rather than re-described inline | Pass | Unchanged; the new assumption names S03. |
+| 6 | Methodology and quality-standard foundation are stated explicitly (e.g. ISO/IEC 25010, Larman) | Pass | Unchanged. |
+| 7 | Assumptions and constraints are explicit and clearly distinguished from one another | Pass | The assumption (S03 provides a runner with `NET_ADMIN` and `/dev/net/tun`) and the constraint (a VPN key or token never appears in a log, an artifact or a command line) are in their own sections. |
+| 8 | Document supports executive decision-making with a clear, unambiguous recommendation | Pass | Unchanged: Proceed. |
+
+## Overall Verdict
+
+Go - all eight criteria pass for the revision that adds objective O6, its scope item, assumption, constraint and success criterion 6. The author confirmed the acceptance in chat on 2026-10-19 as stand-in for S01; there is no independent reader and the decision stays open to challenge.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| The Metadata table of BC-001 has no `Language` and `Domain` rows (QC-LANG-001 criterion 1); this predates this change and is carried over from [RC-067]. Add the rows or record in an ADR why they are not needed | S01 | Before the next material change to BC-001 |
+
+---
+
+[BC-001]: ../../business-case.md
+[QC-BC-001]: ../../../framework/qc/artifacts/qc-business-case.md
+[RC-067]: ./rc-067-bc-001-o5.md
+[c5d5941]: https://git.tirsystem.com/TirSystem/github-action/commit/c5d59418698316866807388bf61dcb6166d9fa8b

docs/sqa/reviews/rc-082-mil-012-results.md

@@ -0,0 +1,65 @@
+# Review Record: MIL-012 results of tasks 1, 6 and the review fixes (MIL-012)
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-082 |
+| CrossReference | [MIL-012], [QC-MIL-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-19 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version; accepted by the author in chat as stand-in for S01 | [3325bea] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [MIL-012]
+- Checklist used: [QC-MIL-001]
+- Scope: delta re-review of the milestone after [RC-080]: the new `## Verification results` section (task 1, task 6, the fixes made after the review of pull request 194), the added `[ADR-0011]` in the CrossReference, and the claims about open tasks. Criteria 1 to 6 are re-read; none of the milestone's own text for them changed. [ADR-0011] is **not** reviewed here: it stays `Proposed` and needs a review against its own checklist
+- Language and domain: n/a (technical type)
+- Mode: supervised, not independent (the author, Jens Tirsvad Nielsen, asked in chat on 2026-10-19 for the acceptance and stands in for S01; the AI prepared the evidence)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | A concrete deliverable is defined for every gate | Pass | Unchanged: release 2.2.0 with the two actions, guides, wiki pages in three languages, ADR, framework templates pinned. The results section does not claim any of it is delivered; it lists tasks 2 to 5, 7, 8 and 10 to 12 as open. |
+| 2 | Explicit Go/No-Go criteria are stated for each gate | Pass | Unchanged, ten criteria. The results bear on two of them. Criterion 1 (a `uses:` of a subfolder action resolves, the form recorded): runs 417 and 418 show both forms resolve at `@main`, and the failure at the deleted branch is explained by the log text "reference not found". Criterion 6 (scripts linted in CI, a seeded error fails): met by `tools/lint-action-scripts.sh` and its tests on the working branch; the pull-request run of the new step is the final evidence. The other eight criteria are not claimed. |
+| 3 | Dependencies on other milestones are explicitly mapped | Pass | Unchanged; [ADR-0011] is added to the CrossReference and exists. |
+| 4 | Each milestone is traceable to a Business Case objective or KPI | Pass | Unchanged: objective O6 and success criterion 6 of [BC-001], reviewed in [RC-081]. |
+| 5 | Milestone owner and approving reviewer are identified | Pass | Unchanged: owner S05, approving reviewer S01. |
+| 6 | Milestone has a defined target date consistent with project constraints | Pass | Unchanged: 2026-11-06. The open tasks 2 to 5 need the operator's runner (S03); the milestone states the dependency, and the date is at risk until the runner exists. |
+
+## Results check
+
+| # | Claim in the results | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | Task 1: both forms resolve at `@main` | Pass | Run 418 (`.../actions/runs/2425`): jobs `wg-short`, `wg-full`, `ts-short`, `ts-full` each executed the action's `mask` step and main step and failed with the action's own `[configuration]` error. Read from the job logs through the API. |
+| 2 | Run 417 failed because the branch was deleted | Pass | `git ls-remote` showed no `wireguard-vpn-action` head after pull request 194 merged; the log says `Unable to resolve wireguard-vpn-action: reference not found`. |
+| 3 | Task 6: lint script, workflow step, pinned tools, seeded-error test | Pass | `tools/lint-action-scripts.sh`; the test file seeds a shellcheck problem and a badly formatted script, shows both fail, and shows the two action scripts pass; the full suite (590 tests) passes locally. Not yet run by the instance's CI. |
+| 4 | The ten findings of the review of pull request 194 are answered | Pass | Each has a code change and an offline test (the daemon wait with a delayed stub, `sudo` that resets the environment, a host daemon not taken over, a line break refused, the key file removed on failure, `latest` refused). The wording of the results says they are offline-tested with stubs and that tasks 3 and 4 must show them on a runner. |
+| 5 | Open tasks are listed honestly | Pass | Tasks 2, 3, 4, 5, 7, 8, 10, 11 and 12 are named as open, with the reason. |
+
+## Overall Verdict
+
+Go - the results recorded are accurate and claim no more than the evidence shows. The author confirmed the acceptance in chat on 2026-10-19 as stand-in for S01; this is not an independent review.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| Review [ADR-0011] against its checklist and accept or change it; it is `Proposed` | S01 | Before task 10 (release 2.2.0) |
+| Provide the `vpn` runner, the WireGuard peer and the Tailscale tag with an OAuth client for tasks 3 and 4; the target date 2026-11-06 depends on it | S03 | 2026-10-30 |
+| Confirm this record by S01 when an independent reading is possible | S01 | 2026-11-02 |
+
+---
+
+[MIL-012]: ../../milestones/mil-012-vpn-actions-for-deployment.md
+[BC-001]: ../../business-case.md
+[ADR-0011]: ../../adr/adr-0011-vpn-composite-actions.md
+[RC-080]: ./rc-080-mil-012-plan.md
+[RC-081]: ./rc-081-bc-001-o6.md
+[QC-MIL-001]: ../../../framework/qc/artifacts/qc-milestones-gateways.md
+[3325bea]: https://git.tirsystem.com/TirSystem/github-action/commit/3325bea772304b54e8dfffad592b4afadc3ec2b8

docs/sqa/reviews/rc-083-mil-013-plan.md

@@ -0,0 +1,74 @@
+# Review Record: MIL-013 and PP-001 (MIL-013)
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-083 |
+| CrossReference | [MIL-013], [PP-001], [BC-001], [QC-MIL-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-19 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version; accepted by the author in chat as stand-in for S01, after one correction found in the first read | [e35b1c5] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [MIL-013]; delta of [PP-001] for the added milestone
+- Checklist used: [QC-MIL-001] for the milestone; for the plan, the criteria of `PP.md` (no QC checklist exists for PP-001)
+- Scope: full review of MIL-013; delta re-review of PP-001, earlier record [RC-080]
+- Language and domain: n/a (technical type)
+- Mode: supervised, not independent (the author, Jens Tirsvad Nielsen, asked in chat on 2026-10-19 for the acceptance and stands in for S01; the AI prepared the evidence)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | A concrete deliverable is defined for every gate | Pass | `## Deliverable` names release 2.3.0 with the reusable workflow, its scripts under `tools/`, guide, README section, wiki pages in three languages, changelog entry, offline tests, an ADR for the detection method and a review record, and the two pull requests in the other repositories. |
+| 2 | Explicit Go/No-Go criteria are stated for each gate | Pass | Eleven criteria, each with a checkable Go and No-Go. The first is measurable (a corpus of named size, recall of at least 90 % for Danish and Malay, at most one false positive per 200 English comments); the others are runs, searches or a verified setting. Criterion 7 (the merge is blocked) depends on a setting that only the repository owner makes, and says so. |
+| 3 | Dependencies on other milestones are explicitly mapped | Pass | [MIL-010] (the comment scanner), [MIL-004] (the Release workflow), [MIL-011] (`MAJOR_TAG`), [ADR-0005]; the outside dependencies (a Gitea token from S03, branch protection by S01 or S03, the framework and checklist repositories) are named. The first read noted that the planned window of [MIL-004] (2026-11-16 to 2026-11-28) starts after this milestone does; [MIL-004] is already released (`v1`, `v2`), so the dependency is met and the plan says nothing wrong. |
+| 4 | Each milestone is traceable to a Business Case objective or KPI | Pass | Objective O7 and success criterion 7 of [BC-001], added in the same change and reviewed in [RC-084]. The first read found the traceability row still saying O7 was "added at acceptance of this milestone", which is now false; it states the objective plainly. |
+| 5 | Milestone owner and approving reviewer are identified | Pass | Owner S05, approving reviewer S01; both are in [SA-001]. |
+| 6 | Milestone has a defined target date consistent with project constraints | Pass | 2026-11-20, confirmed by S01 in chat on 2026-10-19; the Business Case sets no deadline. The window (2026-11-09 to 2026-11-20) follows [MIL-012] (2026-11-06) and overlaps [MIL-009], which is wiki callers and does not use the check's token or reviewer. |
+
+## Plan delta (PP-001)
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | Every milestone has a `MIL-*` document and the plan's dates equal that document's target date | Pass | MIL-001 to MIL-013 exist; the MIL-013 decision date (2026-11-20) equals its Target Date. |
+| 2 | Every Business Case scope item is covered by a gateway | Pass | The new scope item "A shared workflow that checks that comments in source code are in English and tells the author" is covered by [MIL-013] in the scope table. |
+| 3 | The schedule respects the Business Case constraints | Pass | No deadline in the Business Case; the window is two weeks. |
+| 4 | Dependencies between milestones are stated | Pass | `MIL-004 + MIL-010 + MIL-011 -> MIL-013`. |
+| 5 | Every gateway has an owner who is a stakeholder ID | Pass | S05. |
+| 6 | Plan content is internally consistent | Pass | The Purpose says "thirteen"; the Gantt, the schedule, the scope table, the dependencies and the planning assumption agree. Unused commit link definitions left by the history roll were removed. |
+| 7 | Open Issues are current | Pass | A plan risk is added: the check calls a correct comment non-English or misses a Danish or Malay one, with the mitigation in tasks 1 and 2 and the exception marker. |
+
+## Overall Verdict
+
+Go - all criteria pass after one correction found in the first read (the stale "added at acceptance" wording). The author confirmed the acceptance in chat on 2026-10-19 as stand-in for S01; this is not an independent review.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| Confirm this record by S01 when an independent reading is possible | S01 | 2026-11-02 |
+| Task 9: decide which repositories mark the check as required and set it; the workflow cannot, and the AI does not change branch protection | S01 | Before task 8 ends |
+| Ask the operator for a Gitea token that may comment on pull requests, stored as an organization secret, before task 8 | S03 | 2026-11-13 |
+
+---
+
+[MIL-013]: ../../milestones/mil-013-english-comments-check.md
+[PP-001]: ../../project-plan.md
+[BC-001]: ../../business-case.md
+[SA-001]: ../../stakeholder-analysis.md
+[MIL-004]: ../../milestones/mil-004-versioned-release.md
+[MIL-009]: ../../milestones/mil-009-migrate-wiki-callers-and-remove-scoped-workflow.md
+[MIL-010]: ../../milestones/mil-010-code-metrics-badges.md
+[MIL-011]: ../../milestones/mil-011-code-metrics-default-tools-ref.md
+[MIL-012]: ../../milestones/mil-012-vpn-actions-for-deployment.md
+[ADR-0005]: ../../adr/adr-0005-quality-check-contract.md
+[RC-080]: ./rc-080-mil-012-plan.md
+[RC-084]: ./rc-084-bc-001-o7.md
+[QC-MIL-001]: ../../../framework/qc/artifacts/qc-milestones-gateways.md
+[e35b1c5]: https://git.tirsystem.com/TirSystem/github-action/commit/e35b1c56748a50430503f5518602469f93262357

docs/sqa/reviews/rc-084-bc-001-o7.md

@@ -0,0 +1,54 @@
+# Review Record: BC-001 (objective O7, English comments check)
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-084 |
+| CrossReference | [BC-001], [QC-BC-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-19 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version; accepted by the author in chat as stand-in for S01 | [e35b1c5] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [BC-001]
+- Checklist used: [QC-BC-001]
+- Scope: delta re-review of criteria 2, 3, 4 and 7 (the change adds objective O7, an In Scope bullet, an assumption, a constraint and success criterion 7); criteria 1, 5, 6 and 8 are re-read and unchanged. Earlier record: [RC-081]
+- Language and domain: n/a for this delta (the action item of [RC-067] about the Language and Domain rows is still open)
+- Language reviewer: none
+- Mode: supervised, not independent (the author, Jens Tirsvad Nielsen, asked in chat on 2026-10-19 for the acceptance and stands in for S01; the AI prepared the evidence)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | ROI/Cost-Benefit analysis is quantitative, or where qualitative, is explicitly justified | Pass | Unchanged; the Cost-Benefit Assessment labels its qualitative form. |
+| 2 | Risks are identified with documented impact and mitigation | Pass | The delivery risk (the check wrongly flags a correct comment, or misses a Danish or Malay one) is a plan risk in PP-001 with a mitigation: a measured corpus before the build, an exception marker and an allowed-words file. |
+| 3 | Success criteria are measurable, stating explicit targets rather than vague aspirations | Pass | Criterion 7: "0 after MIL-013" non-English comments reaching the default branch of a repository that calls the check, measured by the check's run on the default branch and a throwaway pull request that cannot be merged. |
+| 4 | Scope explicitly separates In Scope vs Out of Scope | Pass | "A shared workflow that checks that comments in source code are in English and tells the author (MIL-013)" is a new In Scope bullet. Out of Scope is unchanged and does not contradict it: "application code of consuming repositories" stays out because the check only reads comments and reports them, and changes nothing in the consuming repository; "operating the Gitea instance or runners" stays out because branch protection is set by S01 or S03, as the new assumption says. |
+| 5 | Stakeholders are cross-referenced to Stakeholder Analysis IDs rather than re-described inline | Pass | Unchanged; the new assumption names S01 and S03. |
+| 6 | Methodology and quality-standard foundation are stated explicitly (e.g. ISO/IEC 25010, Larman) | Pass | Unchanged. |
+| 7 | Assumptions and constraints are explicit and clearly distinguished from one another | Pass | The assumption (S03 provides a token that may comment on pull requests; S01 or S03 mark the check required) and the constraint (no source text leaves the instance, the token never appears in a log) are in their own sections. |
+| 8 | Document supports executive decision-making with a clear, unambiguous recommendation | Pass | Unchanged: Proceed. |
+
+## Overall Verdict
+
+Go - all eight criteria pass for the revision that adds objective O7, its scope item, assumption, constraint and success criterion 7. The author confirmed the acceptance in chat on 2026-10-19 as stand-in for S01; there is no independent reader and the decision stays open to challenge.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| The Metadata table of BC-001 has no `Language` and `Domain` rows (QC-LANG-001 criterion 1); this predates this change and is carried over from [RC-067]. Add the rows or record in an ADR why they are not needed | S01 | Before the next material change to BC-001 |
+
+---
+
+[BC-001]: ../../business-case.md
+[QC-BC-001]: ../../../framework/qc/artifacts/qc-business-case.md
+[RC-067]: ./rc-067-bc-001-o5.md
+[RC-081]: ./rc-081-bc-001-o6.md
+[e35b1c5]: https://git.tirsystem.com/TirSystem/github-action/commit/e35b1c56748a50430503f5518602469f93262357

docs/sqa/reviews/rc-085-mil-013-results.md

@@ -0,0 +1,67 @@
+# Review Record: MIL-013 results of tasks 1 to 8, 10 and 13 (MIL-013)
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | RC-085 |
+| CrossReference | [MIL-013], [QC-MIL-001] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-21 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version; accepted by the author in chat as stand-in for S01 | [88f852a] |
+
+---
+
+## Artifact Under Review
+
+- Instance reviewed: [MIL-013]
+- Checklist used: [QC-MIL-001]
+- Scope: delta re-review of the milestone after [RC-083]: the new `## Verification results` section (the results of the merged work, the trial on the instance and its three defects, the search of the logs), and the added `[ADR-0012]` in the CrossReference. Criteria 1 to 6 are re-read; none of the milestone's own text for them changed. [ADR-0012] is **not** reviewed here: it stays `Proposed` and needs a review against its own checklist
+- Language and domain: n/a (technical type)
+- Mode: supervised, not independent (the author, Jens Tirsvad Nielsen, asked in chat on 2026-10-21 for the acceptance and stands in for S01; the AI prepared the evidence)
+
+## Checklist Results
+
+| # | Criterion | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | A concrete deliverable is defined for every gate | Pass | Unchanged: release 2.3.0 with the workflow, scripts, guide, wiki, tests, ADR and the two pull requests in the other repositories. The results do not claim any of it is released. |
+| 2 | Explicit Go/No-Go criteria are stated for each gate | Pass | Unchanged, eleven criteria. The results bear on criterion 1 (corpus rates, met on the corpus, with the limits of an AI-written corpus said), 3 (a pull request with a Danish comment fails, one without passes: met in runs 440 and 445), 4 (an exception can be marked: met, the marked line was not reported), 5 (one comment that mentions the author, updated, resolved: met when the fix branch is called) and 6 (no token in a log: met for the four jobs searched; the detector made no network call). Criteria 7 to 11 are not claimed. |
+| 3 | Dependencies on other milestones are explicitly mapped | Pass | Unchanged; [ADR-0012] is added to the CrossReference and exists. |
+| 4 | Each milestone is traceable to a Business Case objective or KPI | Pass | Unchanged: objective O7 and success criterion 7 of [BC-001] ([RC-084]). |
+| 5 | Milestone owner and approving reviewer are identified | Pass | Unchanged: owner S05, approving reviewer S01. |
+| 6 | Milestone has a defined target date consistent with project constraints | Pass | Unchanged: 2026-11-20. Open tasks 9, 11, 12 and 14 and the merge of pull request 212 are before it; task 9 needs the owner. |
+
+## Results check
+
+| # | Claim in the results | Status | Evidence/Notes |
+| --- | --- | --- | --- |
+| 1 | The first call at `@main` found only the Malay comment and skipped the author step | Pass | Read from the log of job 2761 of run 433 (id 2478): one finding at `trial/sample.py:9`, and the step list shows "Tell the author" skipped. |
+| 2 | In a called workflow `gitea.event_name` is `workflow_call` | Pass | Printed by the debug workflow in runs 435 and 437: `event_name=workflow_call number=213 author=Tirsvad base_ref=main`; the steps with the event-name conditions are listed as skipped, the others as success. |
+| 3 | The fix branch finds both comments, writes one comment, updates it, resolves it | Pass | Runs 440, 443 and 445 read from the API: the comment list of pull request 213 held one comment (id 8715) after each run; its text after run 445 was the "passes" text without a mention. |
+| 4 | The run link equals the run's address | Pass | The link in the comment after run 447 is `https://git.tirsystem.com/TirSystem/github-action/actions/runs/2492`, the `html_url` of run 447. |
+| 5 | No credential in the logs | Pass | A search of four job logs; the only lines matching were `REPORT_TOKEN: ***`. The search patterns cannot find a short or oddly formed secret, which the result says by naming the patterns. |
+| 6 | The open items are listed honestly | Pass | The result names what the trial did not show: a corrected call at `@main`, a fork pull request, a custom token, the required check, and the call by this repository. |
+
+## Overall Verdict
+
+Go - the results recorded are accurate and claim no more than the evidence shows. The author confirmed the acceptance in chat on 2026-10-21 as stand-in for S01; this is not an independent review.
+
+## Action Items
+
+| Action | Owner | Due |
+| --- | --- | --- |
+| Review [ADR-0012] against its checklist and accept or change it; it is `Proposed` | S01 | Before task 11 (release 2.3.0) |
+| Review and merge pull request 212 (the three defects); call the corrected workflow at `@main` once more | S01 | 2026-11-06 |
+| Task 9: decide which repositories mark the check as required and set it | S01 | 2026-11-13 |
+| Confirm this record by S01 when an independent reading is possible | S01 | 2026-11-09 |
+
+---
+
+[MIL-013]: ../../milestones/mil-013-english-comments-check.md
+[BC-001]: ../../business-case.md
+[ADR-0012]: ../../adr/adr-0012-english-comment-detection.md
+[RC-083]: ./rc-083-mil-013-plan.md
+[RC-084]: ./rc-084-bc-001-o7.md
+[QC-MIL-001]: ../../../framework/qc/artifacts/qc-milestones-gateways.md
+[88f852a]: https://git.tirsystem.com/TirSystem/github-action/commit/88f852af9398468b91e88fe0190ce5c35dcf0fa2

docs/sqa/traceability-matrix.md

@@ -4,13 +4,13 @@
 | Key | Value |
 | --- | --- |
 | ID | TM-001 |
-| CrossReference | [BC-001], [SA-001], [PP-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [MIL-008], [RC-001], [RC-002], [RC-003], [RC-004], [RC-005], [RC-006], [RC-007], [RC-008], [RC-009], [RC-010], [RC-011], [RC-012], [RC-013], [RC-014], [RC-015], [RC-016], [RC-017], [RC-018], [RC-019], [RC-020], [RC-021], [RC-022], [RC-023], [RC-024], [RC-025], [RC-026], [RC-027], [RC-028], [RC-029], [RC-030], [RC-031], [RC-032], [RC-033], [RC-034], [RC-035], [RC-036], [RC-037], [RC-038], [RC-039], [RC-040], [RC-041], [RC-042], [RC-043], [RC-044], [RC-045], [RC-046], [RC-047], [RC-048], [RC-049], [RC-050], [RC-051], [RC-052], [RC-053], [RC-054], [RC-055], [RC-056], [RC-057], [RC-058], [RC-059], [RC-060], [ADR-0007], [ADR-0008], [UC-007], [UC-006], [ADR-0006], [UC-005], [ADR-0005], [UCD-001], [US-001], [UC-001], [UC-002], [UC-003], [UC-004], [ADR-0001], [ADR-0002], [ADR-0003], [ADR-0004] |
+| CrossReference | [BC-001], [SA-001], [PP-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [MIL-008], [MIL-009], [MIL-010], [MIL-011], [MIL-012], [MIL-013], [ADR-0011], [ADR-0012], [UC-008], [RC-001], [RC-002], [RC-003], [RC-004], [RC-005], [RC-006], [RC-007], [RC-008], [RC-009], [RC-010], [RC-011], [RC-012], [RC-013], [RC-014], [RC-015], [RC-016], [RC-017], [RC-018], [RC-019], [RC-020], [RC-021], [RC-022], [RC-023], [RC-024], [RC-025], [RC-026], [RC-027], [RC-028], [RC-029], [RC-030], [RC-031], [RC-032], [RC-033], [RC-034], [RC-035], [RC-036], [RC-037], [RC-038], [RC-039], [RC-040], [RC-041], [RC-042], [RC-043], [RC-044], [RC-045], [RC-046], [RC-047], [RC-048], [RC-049], [RC-050], [RC-051], [RC-052], [RC-053], [RC-054], [RC-055], [RC-056], [RC-057], [RC-058], [RC-059], [RC-060], [RC-061], [RC-062], [RC-063], [RC-064], [RC-065], [RC-066], [RC-067], [RC-068], [RC-069], [RC-070], [RC-071], [RC-072], [RC-073], [RC-074], [RC-075], [RC-076], [RC-077], [RC-078], [RC-079], [RC-080], [RC-081], [RC-082], [RC-083], [RC-084], [RC-085], [ADR-0007], [ADR-0008], [ADR-0009], [ADR-0010], [UC-007], [UC-006], [ADR-0006], [UC-005], [ADR-0005], [UCD-001], [US-001], [UC-001], [UC-002], [UC-003], [UC-004], [ADR-0001], [ADR-0002], [ADR-0003], [ADR-0004] |
 
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
-| 2026-10-13 | Proposed | Jens Tirsvad Nielsen | S01 | Added RC-059 (MIL-007 task 7 results) | [2481c26] |
-| 2026-10-13 | Proposed | Jens Tirsvad Nielsen | S01 | Added MIL-008, RC-060 and RC-061 | [01b9c29] |
+| 2026-10-19 | Proposed | Jens Tirsvad Nielsen | S01 | Added MIL-013 (English comments check), RC-083 and RC-084 (its plan and objective O7) | [e35b1c5] |
+| 2026-10-21 | Proposed | Jens Tirsvad Nielsen | S01 | Added ADR-0012 and RC-085 (MIL-013 results of the trial) | [88f852a] |
 
 ---
 
@@ -25,12 +25,15 @@ updated whenever an artifact instance is created or reviewed.
 | Artifact Instance | Type | Upstream (Backward Link) | Downstream (Forward Link) | Last Reviewed (RC-ID) |
 | --- | --- | --- | --- | --- |
 | [SA-001] | SA | - | [BC-001], [UCD-001] | [RC-004] |
-| [BC-001] | BC | [SA-001] | [PP-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006] | [RC-001], [RC-008] |
-| [PP-001] | PP | [BC-001], [SA-001] | [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [US-001] | [RC-002], [RC-009], [RC-015], [RC-017], [RC-025], [RC-032], [RC-053] |
+| [BC-001] | BC | [SA-001] | [PP-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-012], [MIL-013] | [RC-001], [RC-008], [RC-067], [RC-081], [RC-084] |
+| [PP-001] | PP | [BC-001], [SA-001] | [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-005], [MIL-006], [MIL-007], [MIL-008], [MIL-009], [MIL-010], [MIL-011], [MIL-012], [MIL-013], [US-001] | [RC-002], [RC-009], [RC-015], [RC-017], [RC-025], [RC-032], [RC-053], [RC-062], [RC-064], [RC-068], [RC-080], [RC-083] |
 | [MIL-001] | MIL | [BC-001], [PP-001] | [MIL-002] | [RC-003], [RC-026] |
 | [MIL-002] | MIL | [BC-001], [PP-001], [MIL-001] | [MIL-003], [MIL-005] | [RC-005], [RC-027] |
 | [MIL-003] | MIL | [BC-001], [PP-001], [MIL-002] | [MIL-004] | [RC-006], [RC-028], [RC-033], [RC-039] |
 | [MIL-004] | MIL | [BC-001], [PP-001], [MIL-003] | - | [RC-007], [RC-029], [RC-034], [RC-048] |
+| [ADR-0010] | ADR | [MIL-010], [UC-008], [US-001], [ADR-0005], [ADR-0006] | - | [RC-072], [RC-073] |
+| [ADR-0011] | ADR | [MIL-012], [ADR-0005], [ADR-0006] | - | - |
+| [ADR-0012] | ADR | [MIL-013], [ADR-0005], [ADR-0010] | - | - |
 | [RC-001] | RC | [BC-001] | - | - |
 | [RC-002] | RC | [PP-001] | - | - |
 | [RC-003] | RC | [MIL-001] | - | - |
@@ -40,7 +43,12 @@ updated whenever an artifact instance is created or reviewed.
 | [MIL-005] | MIL | [BC-001], [PP-001], [MIL-002] | [MIL-006] | [RC-010], [RC-011], [RC-030], [RC-050] |
 | [MIL-006] | MIL | [BC-001], [PP-001], [MIL-002], [MIL-005] | - | [RC-016], [RC-031], [RC-049], [RC-058] |
 | [MIL-007] | MIL | [BC-001], [PP-001], [MIL-003], [MIL-004], [ADR-0008] | - | [RC-052], [RC-055], [RC-059] |
-| [MIL-008] | MIL | [BC-001], [MIL-006], [ADR-0004] | - | [RC-060], [RC-061] |
+| [MIL-008] | MIL | [BC-001], [PP-001], [MIL-006], [ADR-0004] | [MIL-009] | [RC-060], [RC-061] |
+| [MIL-009] | MIL | [BC-001], [PP-001], [MIL-008], [ADR-0004], [ADR-0006], [ADR-0009] | - | [RC-064], [RC-066] |
+| [MIL-010] | MIL | [BC-001], [PP-001], [MIL-003], [MIL-004] | [MIL-011] | [RC-068], [RC-074], [RC-075] |
+| [MIL-011] | MIL | [BC-001], [PP-001], [MIL-010], [ADR-0006], [ADR-0010] | [MIL-012] | [RC-076], [RC-077], [RC-078], [RC-079] |
+| [MIL-012] | MIL | [BC-001], [PP-001], [MIL-004], [MIL-011], [ADR-0006], [ADR-0011] | - | [RC-080], [RC-082] |
+| [MIL-013] | MIL | [BC-001], [PP-001], [MIL-004], [MIL-010], [MIL-011], [ADR-0005], [ADR-0006], [ADR-0010] | - | [RC-083], [RC-085] |
 | [RC-007] | RC | [MIL-004] | - | - |
 | [RC-008] | RC | [BC-001] | - | - |
 | [RC-009] | RC | [PP-001] | - | - |
@@ -48,7 +56,7 @@ updated whenever an artifact instance is created or reviewed.
 | [ADR-0001] | ADR | [BC-001], [MIL-005] | [ADR-0003] | [RC-012] |
 | [ADR-0002] | ADR | [SA-001], [RC-001] | - | [RC-013] |
 | [ADR-0003] | ADR | [MIL-005], [ADR-0001], [RC-011] | [ADR-0004] | [RC-014] |
-| [ADR-0004] | ADR | [MIL-006], [ADR-0003], [ADR-0002] | - | [RC-018] |
+| [ADR-0004] | ADR | [MIL-006], [ADR-0003], [ADR-0002] | [ADR-0009] | [RC-018], [RC-065] |
 | [RC-011] | RC | [MIL-005] | - | - |
 | [RC-012] | RC | [ADR-0001] | - | - |
 | [RC-013] | RC | [ADR-0002] | - | - |
@@ -57,8 +65,8 @@ updated whenever an artifact instance is created or reviewed.
 | [RC-016] | RC | [MIL-006] | - | - |
 | [RC-017] | RC | [PP-001] | - | - |
 | [RC-018] | RC | [ADR-0004] | - | - |
-| [UCD-001] | UCD | [SA-001], [BC-001] | [US-001], [UC-001], [UC-002], [UC-003], [UC-004], [UC-005], [UC-006], [UC-007] | [RC-019], [RC-035], [RC-040], [RC-045] |
-| [US-001] | US | [UCD-001], [BC-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-007] | [UC-001], [UC-002], [UC-003], [UC-004], [UC-005], [UC-006], [UC-007] | [RC-020], [RC-036], [RC-041], [RC-046], [RC-057] |
+| [UCD-001] | UCD | [SA-001], [BC-001] | [US-001], [UC-001], [UC-002], [UC-003], [UC-004], [UC-005], [UC-006], [UC-007], [UC-008] | [RC-019], [RC-035], [RC-040], [RC-045], [RC-071] |
+| [US-001] | US | [UCD-001], [BC-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [MIL-007] | [UC-001], [UC-002], [UC-003], [UC-004], [UC-005], [UC-006], [UC-007], [UC-008] | [RC-020], [RC-036], [RC-041], [RC-046], [RC-057], [RC-070] |
 | [UC-001] | UC | [UCD-001], [US-001], [SA-001] | - | [RC-021] |
 | [UC-002] | UC | [UCD-001], [US-001], [SA-001] | - | [RC-022] |
 | [UC-003] | UC | [UCD-001], [US-001], [SA-001] | - | [RC-023] |
@@ -69,7 +77,9 @@ updated whenever an artifact instance is created or reviewed.
 | [ADR-0006] | ADR | [MIL-004], [UC-006], [US-001], [ADR-0004], [ADR-0005] | - | [RC-043] |
 | [ADR-0007] | ADR | [MIL-004], [UC-006], [ADR-0006] | - | [RC-047] |
 | [ADR-0008] | ADR | [MIL-007], [UC-005], [US-001], [ADR-0005], [ADR-0006] | - | [RC-054] |
+| [ADR-0009] | ADR | [MIL-008], [ADR-0003], [ADR-0004], [ADR-0005], [ADR-0006] | - | [RC-063] |
 | [UC-007] | UC | [UCD-001], [US-001], [SA-001] | - | [RC-044] |
+| [UC-008] | UC | [UCD-001], [US-001], [SA-001], [MIL-010] | - | [RC-069] |
 | [RC-019] | RC | [UCD-001] | - | - |
 | [RC-020] | RC | [US-001] | - | - |
 | [RC-021] | RC | [UC-001] | - | - |
@@ -113,6 +123,30 @@ updated whenever an artifact instance is created or reviewed.
 | [RC-059] | RC | [MIL-007] | - | - |
 | [RC-060] | RC | [MIL-008] | - | - |
 | [RC-061] | RC | [MIL-008] | - | - |
+| [RC-062] | RC | [PP-001] | - | - |
+| [RC-063] | RC | [ADR-0009] | - | - |
+| [RC-064] | RC | [MIL-009], [PP-001] | - | - |
+| [RC-065] | RC | [ADR-0004] | - | - |
+| [RC-066] | RC | [MIL-009] | - | - |
+| [RC-067] | RC | [BC-001] | - | - |
+| [RC-068] | RC | [MIL-010], [PP-001] | - | - |
+| [RC-069] | RC | [UC-008] | - | - |
+| [RC-070] | RC | [US-001] | - | - |
+| [RC-071] | RC | [UCD-001] | - | - |
+| [RC-072] | RC | [ADR-0010] | - | - |
+| [RC-073] | RC | [ADR-0010] | - | - |
+| [RC-074] | RC | [MIL-010] | - | - |
+| [RC-075] | RC | [MIL-010] | - | - |
+| [RC-076] | RC | [MIL-011], [PP-001] | - | - |
+| [RC-077] | RC | [MIL-011] | - | - |
+| [RC-078] | RC | [MIL-011] | - | - |
+| [RC-079] | RC | [MIL-011] | - | - |
+| [RC-080] | RC | [MIL-012], [PP-001] | - | - |
+| [RC-081] | RC | [BC-001] | - | - |
+| [RC-082] | RC | [MIL-012] | - | - |
+| [RC-083] | RC | [MIL-013], [PP-001] | - | - |
+| [RC-084] | RC | [BC-001] | - | - |
+| [RC-085] | RC | [MIL-013] | - | - |
 
 ## Coverage Notes
 
@@ -134,6 +168,14 @@ updated whenever an artifact instance is created or reviewed.
 [MIL-006]: ../milestones/mil-006-shared-wiki-publishing.md
 [MIL-007]: ../milestones/mil-007-cpp-csharp-quality-checks.md
 [MIL-008]: ../milestones/mil-008-wiki-reusable-workflow.md
+[MIL-010]: ../milestones/mil-010-code-metrics-badges.md
+[MIL-011]: ../milestones/mil-011-code-metrics-default-tools-ref.md
+[MIL-012]: ../milestones/mil-012-vpn-actions-for-deployment.md
+[MIL-013]: ../milestones/mil-013-english-comments-check.md
+[MIL-009]: ../milestones/mil-009-migrate-wiki-callers-and-remove-scoped-workflow.md
+[ADR-0010]: ../adr/adr-0010-code-metrics-badges-contract.md
+[ADR-0011]: ../adr/adr-0011-vpn-composite-actions.md
+[ADR-0012]: ../adr/adr-0012-english-comment-detection.md
 [RC-001]: ./reviews/rc-001-business-case.md
 [RC-002]: ./reviews/rc-002-project-plan.md
 [RC-003]: ./reviews/rc-003-mil-001.md
@@ -205,14 +247,39 @@ updated whenever an artifact instance is created or reviewed.
 [RC-059]: ./reviews/rc-059-mil-007-adoption.md
 [RC-060]: ./reviews/rc-060-mil-008-plan.md
 [RC-061]: ./reviews/rc-061-mil-008-task-5-deferred.md
+[RC-062]: ./reviews/rc-062-pp-001-mil-008.md
+[RC-063]: ./reviews/rc-063-adr-0009.md
+[RC-064]: ./reviews/rc-064-mil-009-plan.md
+[RC-065]: ./reviews/rc-065-adr-0004-superseded.md
+[RC-066]: ./reviews/rc-066-mil-009-outcome.md
+[RC-067]: ./reviews/rc-067-bc-001-o5.md
+[RC-068]: ./reviews/rc-068-mil-010-plan.md
+[RC-069]: ./reviews/rc-069-uc-008.md
+[RC-070]: ./reviews/rc-070-us-001-metrics.md
+[RC-071]: ./reviews/rc-071-ucd-001-metrics.md
+[RC-072]: ./reviews/rc-072-adr-0010.md
+[RC-073]: ./reviews/rc-073-adr-0010-artifact.md
+[RC-074]: ./reviews/rc-074-mil-010-results.md
+[RC-075]: ./reviews/rc-075-mil-010-outcome.md
+[RC-076]: ./reviews/rc-076-mil-011-plan.md
+[RC-077]: ./reviews/rc-077-mil-011-task-1-results.md
+[RC-078]: ./reviews/rc-078-mil-011-fix.md
+[RC-079]: ./reviews/rc-079-mil-011-outcome.md
+[RC-080]: ./reviews/rc-080-mil-012-plan.md
+[RC-081]: ./reviews/rc-081-bc-001-o6.md
+[RC-082]: ./reviews/rc-082-mil-012-results.md
+[RC-083]: ./reviews/rc-083-mil-013-plan.md
+[RC-084]: ./reviews/rc-084-bc-001-o7.md
+[RC-085]: ./reviews/rc-085-mil-013-results.md
 [ADR-0008]: ../adr/adr-0008-cpp-csharp-quality-check-contract.md
+[ADR-0009]: ../adr/adr-0009-wiki-publishing-reusable-workflow.md
 [ADR-0007]: ../adr/adr-0007-release-publish-destination.md
 [UC-007]: ../uc-007/uc.md
+[UC-008]: ../uc-008/uc.md
 [UC-006]: ../uc-006/uc.md
 [ADR-0006]: ../adr/adr-0006-release-process-and-version-pinning.md
 [UC-005]: ../uc-005/uc.md
 [ADR-0005]: ../adr/adr-0005-quality-check-contract.md
-[faf13b2]: https://git.tirsystem.com/TirSystem/github-action/commit/faf13b2c2a4901c0171977de1ffc2841023f537a
-[1bc56f8]: https://git.tirsystem.com/TirSystem/github-action/commit/1bc56f8b771531f221f218fc00b147ecc73c051e
-[2481c26]: https://git.tirsystem.com/TirSystem/github-action/commit/2481c26d802464decd51d75539157093b60e08e8
-[01b9c29]: https://git.tirsystem.com/TirSystem/github-action/commit/01b9c2972b4317bcc590540010aea0eaf7f30014
+[3d7a9df]: https://git.tirsystem.com/TirSystem/github-action/commit/3d7a9df3a3a4712dcc5214a71b0569d90122bf4e
+[e35b1c5]: https://git.tirsystem.com/TirSystem/github-action/commit/e35b1c56748a50430503f5518602469f93262357
+[88f852a]: https://git.tirsystem.com/TirSystem/github-action/commit/88f852af9398468b91e88fe0190ce5c35dcf0fa2

docs/uc-008/uc.md

@@ -0,0 +1,44 @@
+# UC-008: Show Code Metrics and Coverage Badges
+
+## Metadata
+| Key | Value |
+| --- | --- |
+| ID | UC-008 |
+| CrossReference | [UCD-001], [US-001], [SA-001], [MIL-010] |
+
+## Version History
+| Date | Status | Author | Reviewer | Change | Commit |
+| --- | --- | --- | --- | --- | --- |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Initial version; reviewed (RC-069) | [9ca9673] |
+
+---
+
+**Format:** Brief
+
+**Title:** Show Code Metrics and Coverage Badges
+**Scope:** Reusable Workflow Collection
+**Level:** user-goal
+**Primary Actor:** Software Engineer
+**Stakeholders:** S02, S05 (interests below)
+**Stories:** US-001.18, US-001.19, US-001.20
+
+## Brief
+
+A Software Engineer pushes a change to a repository that calls the shared code-metrics workflow. The workflow counts the code files and the lines of code (without comment and blank lines), reads the coverage report the repository supplies, and publishes three badges: the number of code files, the number of lines of code and the coverage. The repository's README shows the badges, and they show the numbers of the latest push.
+
+**Stakeholder interests**
+
+- S02 — the size and the coverage of the code are visible at a glance, without a service outside the instance, and a wrong or missing report is reported instead of shown as a number
+- S05 — the counting rules and the badge contract are defined once and change through a reviewed release
+
+**Preconditions:** The repository is onboarded and the shared workflow is available through reusable workflow delivery; a coverage badge needs a coverage report that the repository's own tests have produced.
+
+**Postconditions (success guarantee):** The three badges show the numbers of the pushed revision, nothing but the badges is changed in the repository, and a run whose numbers are unchanged changes nothing.
+
+---
+
+[UCD-001]: ../use-case-diagram.md
+[US-001]: ../user-stories.md
+[SA-001]: ../stakeholder-analysis.md
+[MIL-010]: ../milestones/mil-010-code-metrics-badges.md
+[9ca9673]: https://git.tirsystem.com/TirSystem/github-action/commit/9ca9673b00351cf913966f347c4da09890ed3f1f

docs/use-case-diagram.md

@@ -4,13 +4,13 @@
 | Key | Value |
 | --- | --- |
 | ID | UCD-001 |
-| CrossReference | [SA-001], [BC-001], [US-001], [UC-001], [UC-002], [UC-003], [UC-004], [UC-005], [UC-006], [UC-007] |
+| CrossReference | [SA-001], [BC-001], [US-001], [UC-001], [UC-002], [UC-003], [UC-004], [UC-005], [UC-006], [UC-007], [UC-008] |
 
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
-| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added the use case Release a Reusable Workflow (UC-006) | [044d8ba] |
-| 2026-10-10 | Accepted | Jens Tirsvad Nielsen | S01 | Added the use case Consume a Workflow Update (UC-007) (RC-045) | [4cf52af] |
+| 2026-10-10 | Deprecated | Jens Tirsvad Nielsen | S01 | Added the use case Consume a Workflow Update (UC-007) (RC-045) | [4cf52af] |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Added the use case Show Code Metrics and Coverage Badges (UC-008); reviewed (RC-071) | [9ca9673] |
 
 ---
 
@@ -46,6 +46,7 @@ rectangle "Reusable Workflow Collection" <<System>> {
   usecase "Run Project Quality Checks" as UC5
   usecase "Release a Reusable Workflow" as UC6
   usecase "Consume a Workflow Update" as UC7
+  usecase "Show Code Metrics and Coverage Badges" as UC8
 }
 
 DevOps --> UC1
@@ -57,6 +58,7 @@ Operator --> UC2
 Operator --> UC4
 Engineer --> UC5
 Engineer --> UC7
+Engineer --> UC8
 UC1 --> Gitea
 UC1 --> GitHub
 UC3 ..> UC2 : <<include>>
@@ -70,7 +72,7 @@ UC4 ..> UC1 : <<extend>>
 | --- | --- | --- | --- |
 | DevOps Professional | `<<Actor>>` | S05 | Synchronize Repository Metadata, Configure Workflow Credentials, Onboard a Repository, Diagnose a Failed Workflow, Release a Reusable Workflow |
 | Platform Operator | `<<Actor>>` | S03 | Configure Workflow Credentials, Diagnose a Failed Workflow |
-| Software Engineer | `<<Actor>>` | S02 | Run Project Quality Checks, Consume a Workflow Update |
+| Software Engineer | `<<Actor>>` | S02 | Run Project Quality Checks, Consume a Workflow Update, Show Code Metrics and Coverage Badges |
 | Gitea Instance | `<<System>>` | - | Synchronize Repository Metadata (source of description and topics) |
 | GitHub | `<<System>>` | S04 (audience of the mirror) | Synchronize Repository Metadata (target) |
 
@@ -85,6 +87,7 @@ UC4 ..> UC1 : <<extend>>
 | Run Project Quality Checks | Software Engineer | Lint, format and type checks run on every change and report a pass or a fail |
 | Release a Reusable Workflow | DevOps Professional | A validated, versioned update that consumers can pin |
 | Consume a Workflow Update | Software Engineer | A new version is adopted safely, one repository first |
+| Show Code Metrics and Coverage Badges | Software Engineer | The size and the coverage of the code are visible as badges that follow every push |
 
 ## Relationships
 
@@ -104,6 +107,7 @@ UC4 ..> UC1 : <<extend>>
 [UC-004]: ./uc-004/uc.md
 [UC-005]: ./uc-005/uc.md
 [UC-006]: ./uc-006/uc.md
-[044d8ba]: https://git.tirsystem.com/TirSystem/github-action/commit/044d8ba21f96f4aceb807d62addc35cdcbb56051
 [UC-007]: ./uc-007/uc.md
+[UC-008]: ./uc-008/uc.md
 [4cf52af]: https://git.tirsystem.com/TirSystem/github-action/commit/4cf52afe00f546c6b20424fb8dfc12796ffd9296
+[9ca9673]: https://git.tirsystem.com/TirSystem/github-action/commit/9ca9673b00351cf913966f347c4da09890ed3f1f

docs/user-stories.md

@@ -4,13 +4,13 @@
 | Key | Value |
 | --- | --- |
 | ID | US-001 |
-| CrossReference | [UCD-001], [BC-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [UC-001], [UC-002], [UC-003], [UC-004], [UC-005], [UC-006], [UC-007], [MIL-007] |
+| CrossReference | [UCD-001], [BC-001], [MIL-001], [MIL-002], [MIL-003], [MIL-004], [UC-001], [UC-002], [UC-003], [UC-004], [UC-005], [UC-006], [UC-007], [MIL-007], [UC-008], [MIL-010] |
 
 ## Version History
 | Date | Status | Author | Reviewer | Change | Commit |
 | --- | --- | --- | --- | --- | --- |
-| 2026-10-11 | Deprecated | Jens Tirsvad Nielsen | S01 | Added US-001.16 and US-001.17 (C++ and C# checks, MIL-007 task 1) | [32b5ab6] |
-| 2026-10-11 | Accepted | Jens Tirsvad Nielsen | S01 | US-001.16 and US-001.17 reviewed (RC-057) and accepted; the Purpose and Scope names the later stories | [1bc56f8] |
+| 2026-10-11 | Deprecated | Jens Tirsvad Nielsen | S01 | US-001.16 and US-001.17 reviewed (RC-057) and accepted; the Purpose and Scope names the later stories | [1bc56f8] |
+| 2026-10-14 | Accepted | Jens Tirsvad Nielsen | AI as stand-in for S01 | Added US-001.18 to US-001.20 (code metrics and coverage badges, MIL-010 task 1); reviewed (RC-070) | [9ca9673] |
 
 ---
 
@@ -21,7 +21,8 @@ These stories cover the P1 use cases of the Project Plan that MIL-002 delivers
 credentials, onboarding a repository and diagnosing a failed run. Roles are the
 actors of [UCD-001]. Later stories cover quality checks (US-001.09, US-001.10 and, for
 C++ and C#, US-001.16 and US-001.17), releases and updates (US-001.11 to
-US-001.15). Stories for the wiki (MIL-005, MIL-006) are not written yet.
+US-001.15) and the code metrics and coverage badges (US-001.18 to
+US-001.20). Stories for the wiki (MIL-005, MIL-006) are not written yet.
 
 ## Story List
 
@@ -248,9 +249,50 @@ US-001.15). Stories for the wiki (MIL-005, MIL-006) are not written yet.
 | --- | --- | --- |
 | [UC-005], [MIL-007] | fits one iteration | none |
 
+### US-001.18 — The size of the code is visible as badges
+
+**As a** Software Engineer, **I want** badges that show the number of code files and the number of lines of code without comment and blank lines, **so that** the size of the project is visible in its README without a service outside the instance.
+
+**Acceptance Criteria**
+
+- Given a repository that calls the shared code-metrics workflow, when a change is pushed, then a badge for the code files and a badge for the lines of code show the numbers of that revision.
+- Given a file with a comment line, a blank line and a code line, when the lines are counted, then only the code line is counted as a line of code.
+- Given a repository without a file of a supported language, when the workflow runs, then it passes with a notice and the badges show zero.
+
+| Traces to | Size | INVEST exceptions |
+| --- | --- | --- |
+| [UC-008], [MIL-010] | fits one iteration | none |
+
+### US-001.19 — The coverage is visible as a badge
+
+**As a** Software Engineer, **I want** a badge that shows how much of the code my tests cover, **so that** a drop in coverage is seen as soon as it is pushed.
+
+**Acceptance Criteria**
+
+- Given a repository that supplies a coverage report, when a change is pushed, then a coverage badge shows the percentage of the report, and its colour follows the thresholds of the contract.
+- Given a coverage report that is missing or that cannot be read, when the workflow runs, then it fails with a `[configuration]` message that names the report file and no coverage badge is changed.
+- Given a repository that supplies no coverage report, when the workflow runs, then it passes with a notice and publishes no coverage badge.
+
+| Traces to | Size | INVEST exceptions |
+| --- | --- | --- |
+| [UC-008], [MIL-010] | fits one iteration | none |
+
+### US-001.20 — A run with unchanged numbers changes nothing
+
+**As a** Software Engineer, **I want** the workflow to commit nothing when the numbers did not change, **so that** the history of the repository is not filled with badge commits.
+
+**Acceptance Criteria**
+
+- Given a push after which none of the three badges would differ, when the workflow runs, then no commit is made.
+- Given a push after which a number changed, when the workflow runs, then one commit changes only the badge files, and the workflow does not start again from that commit.
+
+| Traces to | Size | INVEST exceptions |
+| --- | --- | --- |
+| [UC-008], [MIL-010] | fits one iteration | none |
+
 ## INVEST Check
 
-All seventeen stories are independent of each other except that US-001.05 and
+All twenty stories are independent of each other except that US-001.05 and
 US-001.06 build on US-001.04 (the secrets must exist before a repository can
 run the workflow). Each states one goal and can be negotiated, delivers value
 to the named role, is small enough for one iteration, and has acceptance
@@ -274,5 +316,7 @@ behaviour is tested rather than built.
 [UC-005]: ./uc-005/uc.md
 [UC-006]: ./uc-006/uc.md
 [UC-007]: ./uc-007/uc.md
-[32b5ab6]: https://git.tirsystem.com/TirSystem/github-action/commit/32b5ab62ab5a82638b71b8fcfb43a819e92ab346
+[UC-008]: ./uc-008/uc.md
+[MIL-010]: ./milestones/mil-010-code-metrics-badges.md
 [1bc56f8]: https://git.tirsystem.com/TirSystem/github-action/commit/1bc56f8b771531f221f218fc00b147ecc73c051e
+[9ca9673]: https://git.tirsystem.com/TirSystem/github-action/commit/9ca9673b00351cf913966f347c4da09890ed3f1f

docs/wiki/Capabilities.da.md

@@ -1,4 +1,4 @@
-<!-- translation of Capabilities.md, source sha256 c60d434988dc -->
+<!-- translation of Capabilities.md, source sha256 a8c14f722a77 -->
 
 > Dette er en oversættelse af [`Capabilities`](Capabilities). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
 
@@ -13,8 +13,9 @@ Rækker, der siger Implementeret eller Vejledninger er skrevet, findes i dag. Re
 | Synkronisering af repositorymetadata (Gitea til GitHub-spejl) | Implementeret i `.gitea/scoped_workflows/`, med offline-tests og et valideringsworkflow |
 | Konfiguration og validering af workflow-credentials | Implementeret for synkroniseringsworkflowet: en forhåndskontrol tjekker begge tokens før enhver ændring ([vejledning](Credentials.da)) |
 | Tilslutning af et repository, administration af runners, fejlfinding | Vejledninger er skrevet ([tilslutning](Onboarding.da), [fejlfinding](Troubleshooting.da)); scoped levering til alle fire organisationers repositories er verificeret (MIL-002) |
-| Publicering af et repositorys wiki fra `wiki/` (tilmelding, leveres til alle organisationer) | Implementeret i `.gitea/scoped_workflows/publish-wiki.yml`, med offline-tests; et pilotforsøg i et andet repository publicerer sin wiki (MIL-006); afløses af det genbrugelige workflow nedenfor (ADR-0009) |
-| Publicering af et repositorys wiki fra `docs/wiki/` gennem et kaldt workflow | Implementeret som det genbrugelige workflow `.gitea/workflows/publish-wiki-pages.yml`, med offline-tests; dette repositorys egen wiki er i `docs/wiki/` og publiceres af det gennem `publish-own-wiki.yml`; endnu ikke kaldt fra et andet repository (MIL-008) |
+| Publicering af et repositorys wiki fra `docs/wiki/` gennem et kaldt workflow | Implementeret som det genbrugelige workflow `.gitea/workflows/publish-wiki-pages.yml`, med offline-tests; kaldt af hvert repository, der publicerer en wiki, og dette repositorys egen wiki er i `docs/wiki/` (MIL-008, MIL-009) |
 | Fælles kvalitetskontrol (Python og shell) | Implementeret som det genbrugelige workflow `.gitea/workflows/quality-checks.yml`, med offline-tests og et forsøg i en anden organisation; taget i brug i RepoFoundry ([vejledning](QualityChecksPythonShell.da)) |
 | Fælles kvalitetskontrol (C og C++, C#) | Implementeret som de genbrugelige workflows `.gitea/workflows/quality-checks-cpp.yml` og `.gitea/workflows/quality-checks-csharp.yml` med præcise værktøjsversioner og offline-tests; endnu ikke brugt i et andet repository (MIL-007) ([vejledning til C og C++](QualityChecksCpp.da), [vejledning til C#](QualityChecksCSharp.da)) |
+| Kodemålinger og dækningsbadges | Implementeret og udgivet i 2.1.0 som det genbrugelige workflow `.gitea/workflows/code-metrics.yml` med en tæller, en Cobertura-læser, en SVG-renderer og offline-tests; afprøvet i et kasserepository, endnu ikke brugt i et projektrepository (MIL-010) ([vejledning](CodeMetrics.da)) |
+| Engelske kommentarer | Implementeret som det genbrugelige workflow `.gitea/workflows/english-comments.yml` med en kommentarudtrækker, en sprogdetektor målt på et korpus (ADR-0012), en kommentar på pull requesten og offline-tests; endnu ikke kørt på instansen eller krævet af noget repository (MIL-013) ([vejledning](EnglishComments.da)) |
 | Versioneret udgivelse og publicering | Udgivelsesproces, changelog og opgraderingsvejledning er defineret; udgivelsesworkflowet findes, og `v1.0.0` er udgivet (MIL-004) ([vejledning](Upgrading.da)) |

docs/wiki/Capabilities.md

@@ -13,8 +13,9 @@ Rows that say Implemented or Guides written exist today. The rest is planned and
 | Synchronize repository metadata (Gitea to GitHub mirror) | Implemented in `.gitea/scoped_workflows/`, with offline tests and a validation workflow |
 | Configure and validate workflow credentials | Implemented for the sync workflow: preflight checks both tokens before any change ([guide](Credentials)) |
 | Onboard a repository, manage runners, diagnose failures | Guides written ([onboarding](Onboarding), [troubleshooting](Troubleshooting)); scoped delivery to the repositories of all four organizations verified (MIL-002) |
-| Publish a repository wiki from `wiki/` (opt-in, delivered to every organization) | Implemented in `.gitea/scoped_workflows/publish-wiki.yml`, with offline tests; a pilot in a second repository publishes its wiki (MIL-006); being replaced by the reusable workflow below (ADR-0009) |
-| Publish a repository wiki from `docs/wiki/` through a called workflow | Implemented as the reusable workflow `.gitea/workflows/publish-wiki-pages.yml`, with offline tests; this repository's own wiki is in `docs/wiki/` and published by it through `publish-own-wiki.yml`; not yet called from another repository (MIL-008) |
+| Publish a repository wiki from `docs/wiki/` through a called workflow | Implemented as the reusable workflow `.gitea/workflows/publish-wiki-pages.yml`, with offline tests; called by every repository that publishes a wiki, and this repository's own wiki is in `docs/wiki/` (MIL-008, MIL-009) |
 | Shared quality checks (Python and shell) | Implemented as the reusable workflow `.gitea/workflows/quality-checks.yml`, with offline tests and a trial in a second organization; adopted in RepoFoundry ([guide](QualityChecksPythonShell)) |
 | Shared quality checks (C and C++, C#) | Implemented as the reusable workflows `.gitea/workflows/quality-checks-cpp.yml` and `.gitea/workflows/quality-checks-csharp.yml` with exact tool versions and offline tests; not yet used in another repository (MIL-007) ([C and C++ guide](QualityChecksCpp), [C# guide](QualityChecksCSharp)) |
+| Code metrics and coverage badges | Implemented and released in 2.1.0 as the reusable workflow `.gitea/workflows/code-metrics.yml` with a counter, a Cobertura reader, an SVG renderer and offline tests; tried in a throwaway repository, not yet used in a project repository (MIL-010) ([guide](CodeMetrics)) |
+| English comments | Implemented as the reusable workflow `.gitea/workflows/english-comments.yml` with a comment extractor, a language detector measured on a corpus (ADR-0012), a pull request comment and offline tests; not yet run on the instance or required by any repository (MIL-013) ([guide](EnglishComments)) |
 | Versioned release and publishing | Release process, changelog and upgrade guide defined; the release workflow exists and `v1.0.0` is released (MIL-004) ([guide](Upgrading)) |

docs/wiki/Capabilities.ms.md

@@ -1,4 +1,4 @@
-<!-- translation of Capabilities.md, source sha256 c60d434988dc -->
+<!-- translation of Capabilities.md, source sha256 a8c14f722a77 -->
 
 > Ini ialah terjemahan [`Capabilities`](Capabilities). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
 
@@ -13,8 +13,9 @@ Baris yang menyatakan Dilaksanakan atau Panduan telah ditulis wujud hari ini. Se
 | Menyegerakkan metadata repositori (Gitea ke cermin GitHub) | Dilaksanakan dalam `.gitea/scoped_workflows/`, dengan ujian luar talian dan aliran kerja pengesahan |
 | Mengkonfigur dan mengesahkan kelayakan (credentials) aliran kerja | Dilaksanakan untuk aliran kerja penyegerakan: semakan awal (preflight) memeriksa kedua-dua token sebelum sebarang perubahan ([panduan](Credentials.ms)) |
 | Menyertakan repositori, mengurus runner, mendiagnosis kegagalan | Panduan telah ditulis ([menyertakan repositori](Onboarding.ms), [diagnosis](Troubleshooting.ms)); penghantaran scoped ke repositori keempat-empat organisasi telah disahkan (MIL-002) |
-| Menerbitkan wiki repositori daripada `wiki/` (pilih menyertai, dihantar ke setiap organisasi) | Dilaksanakan dalam `.gitea/scoped_workflows/publish-wiki.yml`, dengan ujian luar talian; satu juruterbang dalam repositori kedua menerbitkan wikinya (MIL-006); sedang diganti oleh aliran kerja boleh guna semula di bawah (ADR-0009) |
-| Menerbitkan wiki repositori daripada `docs/wiki/` melalui aliran kerja yang dipanggil | Dilaksanakan sebagai aliran kerja boleh guna semula `.gitea/workflows/publish-wiki-pages.yml`, dengan ujian luar talian; wiki repositori ini sendiri ada dalam `docs/wiki/` dan diterbitkan olehnya melalui `publish-own-wiki.yml`; belum dipanggil daripada repositori lain (MIL-008) |
+| Menerbitkan wiki repositori daripada `docs/wiki/` melalui aliran kerja yang dipanggil | Dilaksanakan sebagai aliran kerja boleh guna semula `.gitea/workflows/publish-wiki-pages.yml`, dengan ujian luar talian; dipanggil oleh setiap repositori yang menerbitkan wiki, dan wiki repositori ini sendiri ada dalam `docs/wiki/` (MIL-008, MIL-009) |
 | Semakan kualiti bersama (Python dan shell) | Dilaksanakan sebagai aliran kerja boleh guna semula `.gitea/workflows/quality-checks.yml`, dengan ujian luar talian dan percubaan dalam organisasi kedua; digunakan dalam RepoFoundry ([panduan](QualityChecksPythonShell.ms)) |
 | Semakan kualiti bersama (C dan C++, C#) | Dilaksanakan sebagai aliran kerja boleh guna semula `.gitea/workflows/quality-checks-cpp.yml` dan `.gitea/workflows/quality-checks-csharp.yml` dengan versi alat yang tepat dan ujian luar talian; belum digunakan dalam repositori lain (MIL-007) ([panduan C dan C++](QualityChecksCpp.ms), [panduan C#](QualityChecksCSharp.ms)) |
+| Metrik kod dan lencana liputan | Dilaksanakan dan diterbitkan dalam 2.1.0 sebagai aliran kerja boleh guna semula `.gitea/workflows/code-metrics.yml` dengan pengira, pembaca Cobertura, pemaparan SVG dan ujian luar talian; dicuba dalam repositori sekali pakai, belum digunakan dalam repositori projek (MIL-010) ([panduan](CodeMetrics.ms)) |
+| Komen dalam bahasa Inggeris | Dilaksanakan sebagai aliran kerja boleh guna semula `.gitea/workflows/english-comments.yml` dengan pengekstrak komen, pengesan bahasa yang diukur pada korpus (ADR-0012), komen pada pull request dan ujian luar talian; belum dijalankan pada instans atau diwajibkan oleh mana-mana repositori (MIL-013) ([panduan](EnglishComments.ms)) |
 | Keluaran berversi dan penerbitan | Proses keluaran, changelog dan panduan naik taraf telah ditakrifkan; aliran kerja keluaran sudah ada dan `v1.0.0` telah dikeluarkan (MIL-004) ([panduan](Upgrading.ms)) |

docs/wiki/CodeMetrics.da.md

@@ -0,0 +1,92 @@
+<!-- translation of CodeMetrics.md, source sha256 03134e97a78a -->
+
+> Dette er en oversættelse af [`CodeMetrics`](CodeMetrics). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
+
+[English](CodeMetrics) | Dansk | [Bahasa Melayu](CodeMetrics.ms)
+
+# Visning af kodemålinger og dækningsbadges
+
+Sådan kalder en softwareudvikler det fælles kodemålings-workflow og viser dets tre badges (kodefiler, kodelinjer og dækning) i en README. Workflowet tæller repositoryets kode, læser en dækningsrapport, som kalderen leverer, og committer tre SVG-filer til en `badges`-gren. Det kører ingen test og kræver ingen secret. Dets kontrakt er ADR-0010 i dette repository.
+
+## Kald af workflowet
+
+Workflowet kan ikke se filerne fra dit testjob, så testene kører i et job, du selv ejer, uploader Cobertura XML-rapporten som artefakt, og målingsjobbet kører bagefter:
+
+```yaml
+name: Code metrics
+
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4.2.2
+      - run: python3 -m pip install pytest pytest-cov && python3 -m pytest --cov --cov-report=xml
+      - uses: actions/upload-artifact@v4.6.2
+        with:
+          name: coverage
+          path: coverage.xml
+
+  metrics:
+    needs: tests
+    permissions:
+      contents: write
+    uses: TirSystem/github-action/.gitea/workflows/code-metrics.yml@v2
+    with:
+      coverage-artifact: coverage
+      coverage-report: coverage.xml
+```
+
+| Input | Standard | Betydning |
+| --- | --- | --- |
+| `working-directory` | `.` | Mappe, relativt til repositoryets rod, hvis kode tælles |
+| `exclude` | tom | Kommasepareret liste af mønstre for filer og mapper, der ikke tælles, ud over standardudeladelserne; et mønster uden `/` matcher et navn overalt, et mønster med `/` matcher stien under `working-directory` |
+| `coverage-report` | tom | Cobertura XML-rapport: filen i artefaktet, når `coverage-artifact` er sat, ellers en sti i repositoryet; tom giver intet dækningsbadge |
+| `coverage-artifact` | tom | Navn på et artefakt, uploadet af et tidligere job i samme kørsel, der indeholder rapporten |
+| `coverage-warn` | `60` | Dækning i procent, under hvilken badget er rødt |
+| `coverage-good` | `80` | Dækning i procent, fra hvilken badget er grønt; derimellem er det gult |
+| `badges-branch` | `badges` | Gren, der indeholder badge-filerne; den oprettes, hvis den ikke findes |
+| `tools-ref` | `v2` | Tag eller gren i `TirSystem/github-action`, hvorfra scripts i `tools/` hentes |
+
+Reference workflowet ved major-tagget (`@v1`) eller ved et præcist tag, aldrig ved `main`. Et kald ved et præcist tag er kun fuldt fastlåst, når `tools-ref` navngiver samme tag. Se opgraderingsvejledningen. Start workflowet kun ved push til din standardgren: badge-committet har `[skip ci]` og laves med kørslens token, som ikke starter en ny kørsel, men en trigger på alle grene ville skrive ét commit pr. gren.
+
+## Hvad der tælles
+
+- En kodefil er en tekstfil med filendelsen for et understøttet sprog: Python, shell, PowerShell, C, C++, C#, Java, JavaScript, TypeScript, Go, Rust og SQL. Markdown, YAML, JSON, XML, HTML og CSS er ikke kodefiler.
+- Hver linje er præcis én af: tom (kun blanktegn), kommentar (kun kommentartekst) eller kode (alt andet, også en linje med kode og en afsluttende kommentar). Badget viser kun kodelinjerne.
+- En kommentarmarkør i en streng er ikke en kommentar, og en Python-docstring er en streng og tæller derfor som kode.
+- Mapper, der starter med punktum, og `node_modules`, `vendor`, `third_party`, `dist`, `build`, `out`, `bin`, `obj`, `target`, `venv`, `__pycache__` og `shared-scripts` tælles ikke. Genereret kode udelades med `exclude`.
+- Rå og ordrette strenge, der afviger fra en almindelig streng (Rust `r#"..."#`, C# `@"..."`, C++-rå strenge), kan tælles forkert. Tallene afviger lidt fra andre værktøjer; reglerne er de samme ved hver kørsel.
+
+## Dækningsbadget
+
+Rapporten er en Cobertura XML-fil, som `coverage.py` (`coverage xml`), `gcovr` (`--cobertura`) og `coverlet` (formatet `cobertura`) skriver. Badget viser `lines-covered` over `lines-valid`, afrundet til hele procent, og farven følger de to grænser. En rapport, der ikke findes, ikke er velformet Cobertura XML eller ikke har gyldige linjer, får kørslen til at fejle med filen nævnt; dækningsbadget skrives aldrig som `0%` for en dårlig rapport. Uden `coverage-report` består kørslen med en note og uden dækningsbadge.
+
+## Visning af badges
+
+Tilføj billederne til README med grenens rå URL'er:
+
+```markdown
+![code files](https://git.tirsystem.com/OWNER/REPO/raw/branch/badges/code-files.svg)
+![lines of code](https://git.tirsystem.com/OWNER/REPO/raw/branch/badges/code-lines.svg)
+![coverage](https://git.tirsystem.com/OWNER/REPO/raw/branch/badges/coverage.svg)
+```
+
+På GitHub-spejlet bruges `https://raw.githubusercontent.com/OWNER/REPO/badges/code-files.svg`; push-spejlet kopierer grenen. `badges`-grenen indeholder også `code-metrics.json` med tallene pr. sprog. Instansen cacher en rå fil i op til seks timer, så et ændret badge kan vise det gamle tal et stykke tid dér; spejlet cacher i fem minutter. Et privat repository viser ikke badges for en læser, der ikke er logget ind.
+
+## Når workflowet fejler
+
+| Meddelelse | Årsag | Løsning |
+| --- | --- | --- |
+| `[configuration] working-directory must be a relative path inside the repository.` | En absolut sti eller `..` | Brug en sti inde i repositoryet |
+| `[configuration] coverage-report '<x>' does not exist.` | Rapporten blev ikke frembragt, eller artefaktnavnet eller stien er forkert | Tjek testjobbet og artefaktnavnet; stien er inde i artefaktet |
+| `[configuration] coverage-report '<x>' is not well-formed XML` eller `is not a Cobertura report` | Filen har et andet format | Skriv Cobertura XML (`coverage xml`, `gcovr --cobertura`) |
+| `[configuration] coverage-report '<x>' has no valid lines.` | Testene kørte ingen målt kode | Tjek dækningskonfigurationen |
+| `[configuration] coverage-artifact '<x>' needs coverage-report` | Artefaktet er navngivet, men ikke filen i det | Sæt `coverage-report` |
+| `[configuration] coverage-warn ... is above coverage-good` eller `is not a number from 0 to 100` | En grænse er ugyldig | Ret inputtet |
+| `[configuration] badges-branch '<x>' must not be a default branch` eller `holds files that are not badge files` | Grenen hedder `main`, `master` eller har andet indhold | Brug en gren, der kun indeholder badges |
+| `the push to '<x>' failed twice` | En anden kørsel skrev grenen samtidig, eller tokenet kan ikke skrive | Kør igen; tjek at jobbet har `contents: write` |
+| Download-trinnet fejler | Artefaktet findes ikke i denne kørsel, eller jobbet kører ikke efter testjobbet | Tilføj `needs:` og tjek artefaktnavnet |

docs/wiki/CodeMetrics.md

@@ -0,0 +1,123 @@
+<!-- Generated from guides/code-metrics.md by tools/build_wiki.py. Edit the source, not this page. -->
+
+> This page is generated from [`guides/code-metrics.md`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/guides/code-metrics.md). Changes made here are overwritten the next time the wiki is published.
+
+English | [Dansk](CodeMetrics.da) | [Bahasa Melayu](CodeMetrics.ms)
+
+# Showing code metrics and coverage badges
+
+How a software engineer calls the shared code-metrics workflow and shows its
+three badges (code files, lines of code and coverage) in a README. The workflow
+counts the code of the repository, reads a coverage report that the caller
+supplies and commits three SVG files to a `badges` branch. It runs no test and
+needs no secret. Its contract is ADR-0010 in this repository.
+
+## Calling the workflow
+
+The workflow cannot see the files of your test job, so the tests run in a job of
+your own, upload the Cobertura XML report as an artifact, and the metrics job
+runs after it:
+
+```yaml
+name: Code metrics
+
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4.2.2
+      - run: python3 -m pip install pytest pytest-cov && python3 -m pytest --cov --cov-report=xml
+      - uses: actions/upload-artifact@v4.6.2
+        with:
+          name: coverage
+          path: coverage.xml
+
+  metrics:
+    needs: tests
+    permissions:
+      contents: write
+    uses: TirSystem/github-action/.gitea/workflows/code-metrics.yml@v2
+    with:
+      coverage-artifact: coverage
+      coverage-report: coverage.xml
+```
+
+| Input | Default | Meaning |
+| --- | --- | --- |
+| `working-directory` | `.` | Directory, relative to the repository root, whose code is counted |
+| `exclude` | empty | Comma list of patterns of files and directories that are not counted, in addition to the defaults; a pattern without `/` matches a name anywhere, a pattern with `/` matches the path below `working-directory` |
+| `coverage-report` | empty | Cobertura XML report: the file inside the artifact when `coverage-artifact` is set, otherwise a path in the repository; empty writes no coverage badge |
+| `coverage-artifact` | empty | Name of an artifact, uploaded by an earlier job of the same run, that holds the report |
+| `coverage-warn` | `60` | Coverage in percent below which the badge is red |
+| `coverage-good` | `80` | Coverage in percent from which the badge is green; in between it is yellow |
+| `badges-branch` | `badges` | Branch that holds the badge files; it is created when it does not exist |
+| `tools-ref` | `v2` | Tag or branch of `TirSystem/github-action` from which the scripts in `tools/` are fetched |
+
+Reference the workflow at the major tag (`@v2`) or at an exact tag, never at
+`main`. A call at an exact tag is pinned completely only when `tools-ref` names
+the same tag. See the upgrade guide. Start the workflow on pushes to your
+default branch only: the badge commit carries `[skip ci]` and is made with the
+token of the run, which does not start another run, but a trigger on every
+branch would write one commit per branch.
+
+## What is counted
+
+- A code file is a text file with the extension of a supported language:
+  Python, shell, PowerShell, C, C++, C#, Java, JavaScript, TypeScript, Go, Rust
+  and SQL. Markdown, YAML, JSON, XML, HTML and CSS are not code files.
+- Every line is exactly one of blank (only white space), comment (only comment
+  text) or code (everything else, including a line with code and a trailing
+  comment). The badge shows the lines of code only.
+- A comment marker inside a string is not a comment, and a Python docstring is a
+  string, so it counts as code.
+- Directories that start with a dot and `node_modules`, `vendor`, `third_party`,
+  `dist`, `build`, `out`, `bin`, `obj`, `target`, `venv`, `__pycache__` and
+  `shared-scripts` are not counted. Generated code is excluded with `exclude`.
+- Raw and verbatim strings that differ from an ordinary string (Rust `r#"..."#`,
+  C# `@"..."`, C++ raw strings) can be counted wrongly. The counts will differ
+  a little from other tools; the rules are the same on every run.
+
+## The coverage badge
+
+The report is a Cobertura XML file, which `coverage.py` (`coverage xml`),
+`gcovr` (`--cobertura`) and `coverlet` (`cobertura` format) write. The badge
+shows `lines-covered` over `lines-valid`, rounded to a whole percent, and its
+colour follows the two thresholds. A report that does not exist, is not
+well-formed Cobertura XML or has no valid lines fails the run with the file
+named; the coverage badge is never written as `0%` for a bad report. Without
+`coverage-report` the run passes with a notice and no coverage badge.
+
+## Showing the badges
+
+Add the images to the README with the raw URLs of the branch:
+
+```markdown
+![code files](https://git.tirsystem.com/OWNER/REPO/raw/branch/badges/code-files.svg)
+![lines of code](https://git.tirsystem.com/OWNER/REPO/raw/branch/badges/code-lines.svg)
+![coverage](https://git.tirsystem.com/OWNER/REPO/raw/branch/badges/coverage.svg)
+```
+
+On the GitHub mirror use `https://raw.githubusercontent.com/OWNER/REPO/badges/code-files.svg`;
+the push mirror copies the branch. The `badges` branch also holds
+`code-metrics.json` with the numbers per language. The instance caches a raw
+file for up to six hours, so a changed badge can show the old number for a
+while there; the mirror caches for five minutes. A private repository does not
+show the badges to a reader who is not signed in.
+
+## When the workflow fails
+
+| Message | Cause | Fix |
+| --- | --- | --- |
+| `[configuration] working-directory must be a relative path inside the repository.` | An absolute path or `..` | Use a path inside the repository |
+| `[configuration] coverage-report '<x>' does not exist.` | The report was not produced, or the artifact name or path is wrong | Check the test job and the artifact name; the path is inside the artifact |
+| `[configuration] coverage-report '<x>' is not well-formed XML` or `is not a Cobertura report` | The file is another format | Write Cobertura XML (`coverage xml`, `gcovr --cobertura`) |
+| `[configuration] coverage-report '<x>' has no valid lines.` | The tests ran no measured code | Check the coverage configuration |
+| `[configuration] coverage-artifact '<x>' needs coverage-report` | The artifact is named but not the file in it | Set `coverage-report` |
+| `[configuration] coverage-warn ... is above coverage-good` or `is not a number from 0 to 100` | A threshold is invalid | Correct the input |
+| `[configuration] badges-branch '<x>' must not be a default branch` or `holds files that are not badge files` | The branch name is `main`, `master` or a branch with other content | Use a branch that holds only the badges |
+| `the push to '<x>' failed twice` | Another run wrote the branch at the same time, or the token cannot write | Re-run; check that the job has `contents: write` |
+| The download step fails | The artifact does not exist in this run, or the job does not run after the test job | Add `needs:` and check the artifact name |

docs/wiki/CodeMetrics.ms.md

@@ -0,0 +1,92 @@
+<!-- translation of CodeMetrics.md, source sha256 03134e97a78a -->
+
+> Ini ialah terjemahan [`CodeMetrics`](CodeMetrics). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
+
+[English](CodeMetrics) | [Dansk](CodeMetrics.da) | Bahasa Melayu
+
+# Menunjukkan metrik kod dan lencana liputan
+
+Cara seorang jurutera perisian memanggil aliran kerja metrik kod bersama dan menunjukkan tiga lencananya (fail kod, baris kod dan liputan) dalam README. Aliran kerja ini mengira kod repositori, membaca laporan liputan yang dibekalkan oleh pemanggil dan melakukan commit tiga fail SVG ke cabang `badges`. Ia tidak menjalankan sebarang ujian dan tidak memerlukan secret. Kontraknya ialah ADR-0010 dalam repositori ini.
+
+## Memanggil aliran kerja
+
+Aliran kerja tidak dapat melihat fail daripada kerja ujian anda, jadi ujian dijalankan dalam kerja anda sendiri, memuat naik laporan Cobertura XML sebagai artifak, dan kerja metrik dijalankan selepasnya:
+
+```yaml
+name: Code metrics
+
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4.2.2
+      - run: python3 -m pip install pytest pytest-cov && python3 -m pytest --cov --cov-report=xml
+      - uses: actions/upload-artifact@v4.6.2
+        with:
+          name: coverage
+          path: coverage.xml
+
+  metrics:
+    needs: tests
+    permissions:
+      contents: write
+    uses: TirSystem/github-action/.gitea/workflows/code-metrics.yml@v2
+    with:
+      coverage-artifact: coverage
+      coverage-report: coverage.xml
+```
+
+| Input | Lalai | Maksud |
+| --- | --- | --- |
+| `working-directory` | `.` | Direktori, relatif kepada akar repositori, yang kodnya dikira |
+| `exclude` | kosong | Senarai corak fail dan direktori yang tidak dikira, dipisahkan koma, sebagai tambahan kepada pengecualian lalai; corak tanpa `/` sepadan dengan nama di mana-mana, corak dengan `/` sepadan dengan laluan di bawah `working-directory` |
+| `coverage-report` | kosong | Laporan Cobertura XML: fail dalam artifak apabila `coverage-artifact` ditetapkan, jika tidak laluan dalam repositori; kosong bermakna tiada lencana liputan |
+| `coverage-artifact` | kosong | Nama artifak, dimuat naik oleh kerja yang lebih awal dalam larian yang sama, yang memegang laporan |
+| `coverage-warn` | `60` | Liputan dalam peratus di bawahnya lencana berwarna merah |
+| `coverage-good` | `80` | Liputan dalam peratus yang bermulanya lencana berwarna hijau; di antaranya kuning |
+| `badges-branch` | `badges` | Cabang yang memegang fail lencana; ia dicipta jika tidak wujud |
+| `tools-ref` | `v2` | Tag atau cabang `TirSystem/github-action` tempat skrip dalam `tools/` diambil |
+
+Rujuk aliran kerja pada tag major (`@v1`) atau pada tag tepat, jangan sekali-kali pada `main`. Panggilan pada tag tepat hanya tersemat sepenuhnya apabila `tools-ref` menamakan tag yang sama. Lihat panduan menaik taraf. Mulakan aliran kerja pada push ke cabang lalai anda sahaja: commit lencana membawa `[skip ci]` dan dibuat dengan token larian, yang tidak memulakan larian lain, tetapi pencetus pada setiap cabang akan menulis satu commit bagi setiap cabang.
+
+## Apa yang dikira
+
+- Fail kod ialah fail teks dengan sambungan bagi bahasa yang disokong: Python, shell, PowerShell, C, C++, C#, Java, JavaScript, TypeScript, Go, Rust dan SQL. Markdown, YAML, JSON, XML, HTML dan CSS bukan fail kod.
+- Setiap baris tepat satu daripada: kosong (hanya ruang putih), komen (hanya teks komen) atau kod (selebihnya, termasuk baris dengan kod dan komen di hujung). Lencana hanya menunjukkan baris kod.
+- Penanda komen dalam rentetan bukan komen, dan docstring Python ialah rentetan jadi dikira sebagai kod.
+- Direktori yang bermula dengan titik, serta `node_modules`, `vendor`, `third_party`, `dist`, `build`, `out`, `bin`, `obj`, `target`, `venv`, `__pycache__` dan `shared-scripts` tidak dikira. Kod yang dijana dikecualikan dengan `exclude`.
+- Rentetan mentah dan verbatim yang berbeza daripada rentetan biasa (Rust `r#"..."#`, C# `@"..."`, rentetan mentah C++) boleh dikira dengan salah. Angka sedikit berbeza daripada alat lain; peraturannya sama pada setiap larian.
+
+## Lencana liputan
+
+Laporan ialah fail Cobertura XML, yang ditulis oleh `coverage.py` (`coverage xml`), `gcovr` (`--cobertura`) dan `coverlet` (format `cobertura`). Lencana menunjukkan `lines-covered` berbanding `lines-valid`, dibundarkan kepada peratus penuh, dan warnanya mengikut dua ambang. Laporan yang tidak wujud, bukan Cobertura XML yang terbentuk dengan baik atau tidak mempunyai baris sah menyebabkan larian gagal dengan nama fail disebut; lencana liputan tidak pernah ditulis sebagai `0%` bagi laporan yang rosak. Tanpa `coverage-report` larian lulus dengan notis dan tanpa lencana liputan.
+
+## Menunjukkan lencana
+
+Tambahkan imej ke README dengan URL mentah cabang:
+
+```markdown
+![code files](https://git.tirsystem.com/OWNER/REPO/raw/branch/badges/code-files.svg)
+![lines of code](https://git.tirsystem.com/OWNER/REPO/raw/branch/badges/code-lines.svg)
+![coverage](https://git.tirsystem.com/OWNER/REPO/raw/branch/badges/coverage.svg)
+```
+
+Pada cermin GitHub gunakan `https://raw.githubusercontent.com/OWNER/REPO/badges/code-files.svg`; cermin push menyalin cabang itu. Cabang `badges` juga memegang `code-metrics.json` dengan angka bagi setiap bahasa. Instans menyimpan fail mentah dalam cache sehingga enam jam, jadi lencana yang berubah mungkin menunjukkan angka lama seketika di sana; cermin menyimpannya lima minit. Repositori persendirian tidak menunjukkan lencana kepada pembaca yang belum log masuk.
+
+## Apabila aliran kerja gagal
+
+| Mesej | Punca | Pembetulan |
+| --- | --- | --- |
+| `[configuration] working-directory must be a relative path inside the repository.` | Laluan mutlak atau `..` | Gunakan laluan di dalam repositori |
+| `[configuration] coverage-report '<x>' does not exist.` | Laporan tidak dihasilkan, atau nama artifak atau laluan salah | Semak kerja ujian dan nama artifak; laluan berada di dalam artifak |
+| `[configuration] coverage-report '<x>' is not well-formed XML` atau `is not a Cobertura report` | Fail itu berformat lain | Tulis Cobertura XML (`coverage xml`, `gcovr --cobertura`) |
+| `[configuration] coverage-report '<x>' has no valid lines.` | Ujian tidak menjalankan kod yang diukur | Semak konfigurasi liputan |
+| `[configuration] coverage-artifact '<x>' needs coverage-report` | Artifak dinamakan tetapi bukan fail di dalamnya | Tetapkan `coverage-report` |
+| `[configuration] coverage-warn ... is above coverage-good` atau `is not a number from 0 to 100` | Ambang tidak sah | Betulkan input |
+| `[configuration] badges-branch '<x>' must not be a default branch` atau `holds files that are not badge files` | Nama cabang ialah `main`, `master` atau cabang dengan kandungan lain | Gunakan cabang yang hanya memegang lencana |
+| `the push to '<x>' failed twice` | Larian lain menulis cabang pada masa yang sama, atau token tidak boleh menulis | Jalankan semula; semak bahawa kerja mempunyai `contents: write` |
+| Langkah muat turun gagal | Artifak tidak wujud dalam larian ini, atau kerja tidak berjalan selepas kerja ujian | Tambah `needs:` dan semak nama artifak |

docs/wiki/EnglishComments.da.md

@@ -0,0 +1,108 @@
+<!-- translation of EnglishComments.md, source sha256 9dafcabbc807 -->
+
+> Dette er en oversættelse af [`EnglishComments`](EnglishComments). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
+
+[English](EnglishComments) | Dansk | [Bahasa Melayu](EnglishComments.ms)
+
+# Kommentarer i kildekoden på engelsk
+
+Sådan kalder en softwareudvikler det fælles workflow, der kontrollerer, at
+kommentarerne og docstrings i en pull request er skrevet på engelsk. Workflowet
+lader kørslen fejle, når én ikke er det, og skriver én kommentar på pull
+requesten, der nævner forfatteren. Det ændrer ingen fil og sender ingen
+kildetekst ud af instansen. Beslutningen bag er ADR-0012 i dette repository.
+
+## Kald af workflowet
+
+```yaml
+name: English comments
+
+on:
+  pull_request:
+
+jobs:
+  english-comments:
+    uses: TirSystem/github-action/.gitea/workflows/english-comments.yml@v2
+    with:
+      exclude: "docs/generated/**"
+      allowed-words-file: .english-comments-allowed-words
+```
+
+| Input | Standard | Betydning |
+| --- | --- | --- |
+| `scope` | `changed` | `changed` kontrollerer kommentarerne på de linjer, pull requesten tilføjer; `all` kontrollerer hver sporet fil |
+| `exclude` | | Kommasepareret liste af fil- eller stimønstre, der ikke kontrolleres (`*` og `**` er jokertegn) |
+| `allowed-words-file` | | En fil i repositoryet med ord, der aldrig bedømmes, ét pr. linje; `#` starter en kommentar |
+| `threshold` | `0.6` | Sandsynligheden, over 0 og højst 1, hvorfra en kommentar regnes for ikke at være engelsk |
+| `min-words` | `3` | En kommentar med færre ord bedømmes ikke |
+| `langid-version`, `numpy-version` | `1.1.6`, `2.1.3` | De fastlåste pakker, detektoren bruger |
+| `tools-ref` | den nuværende hovedversion | Det tag i dette repository, hvis scripts køres; fastlås det sammen med workflowet |
+
+Den valgfri secret `REPORT_TOKEN` er et Gitea-token, der må kommentere på pull
+requests. Uden den bruger workflowet kørslens eget token, så kommentaren
+skrives af Actions-botten. En pull request fra en fork har et token med kun
+læseadgang: kontrollen får stadig kørslen til at fejle, men der skrives ingen
+kommentar.
+
+## Hvad der kontrolleres
+
+Kommentarerne og docstrings i filer på de sprog, kodetælleren kender
+([kodemålinger](CodeMetrics)): Python, shell, PowerShell, C, C++, C#, Java,
+JavaScript, TypeScript, Go, Rust og SQL. Strenge og kode læses ikke. Kommentarlinjer
+efter hinanden danner en blok. Hver linje i en blok bedømmes for sig (mindst fire ord og en
+sandsynlighed på mindst 0,7), så en engelsk linje ikke kan skjule en dansk ved siden af; når ingen linje
+markeres, bedømmes blokken som helhed (mindst `min-words` ord og `threshold`), så en sætning delt over korte
+linjer ikke overses.
+
+Før en blok bedømmes, fjernes alt, der ikke er et ord: stier, URL'er, tilvalg
+(`--output`), filnavne, identifikatorer (`snake_case`, `camelCase`), tal,
+akronymer og konstanter (`JSON`), en indledende etiket som `Usage:` og ordene
+i filen med tilladte ord. En blok med færre end `min-words` ord tilbage
+bedømmes ikke, så en kort kommentar slipper igennem. Kommentarer, der
+konfigurerer et værktøj (`noqa`, `type:`, `pragma`, `shellcheck`), læses ikke.
+
+## Når kontrollen fejler
+
+Kørslen fejler, hvert fund vises som en annotation (`::error file=...,line=...`)
+og i loggen som `file:line: looks Danish (0.93): "the comment"`, og én kommentar
+på pull requesten opregner dem og nævner forfatteren. En ny kørsel opdaterer den
+kommentar; når pull requesten består, markeres kommentaren som løst og nævner
+ikke længere nogen.
+
+Ret det ved at skrive kommentaren om på engelsk. For et citat eller et navn, der
+ikke er engelsk, kan du enten skrive `english-comments: ignore` i kommentaren
+(det springer hele den kommentarblok over, den står i), eller tilføje ordet til
+filen med tilladte ord.
+
+## Blokering af sammenfletningen
+
+En fejlende kørsel blokerer ikke i sig selv en sammenfletning. Markér kontrollen
+som påkrævet i grenbeskyttelsen af målgrenen: kør workflowet én gang på en pull
+request og vælg dets post på listen over statuskontroller (det præcise navn
+dannes af det kaldende workflow, dets job og hændelsen). At indstille
+grenbeskyttelse er repositoryejerens handling; workflowet ændrer den ikke.
+
+## Hvor præcis den er
+
+Detektoren er `langid`, begrænset til engelsk, dansk, norsk, svensk, tysk,
+fransk, malajisk, indonesisk og hollandsk. På repositoryets korpus markerer den
+ingen af 300 engelske kommentarer, 44 af 45 danske og 41 af 45 malajiske
+kommentarer og alle 48 tyske, svenske, norske og franske (ADR-0012). Dens
+grænser:
+
+- en kommentar på ét eller to ord, eller en der mest består af navne, bedømmes ikke;
+- en kommentar på dårligt engelsk slipper igennem, og en kommentar, der blander
+  engelske fagudtryk med få danske eller malajiske ord, kan slippe igennem;
+- korpussets danske og malajiske kommentarer er skrevet til testen og ikke samlet
+  fra rigtig kode, så rigtig kode vil vise andre fejl. Meld en misset kommentar
+  eller et falsk fund med kommentaren, så kommer den med i korpussen.
+
+## Fejlfinding
+
+| Besked | Årsag |
+| --- | --- |
+| `[configuration] give --base` | Workflowet blev startet af en hændelse, der ikke er en pull request, med `scope: changed`; kald det på `pull_request` eller brug `scope: all` |
+| `[configuration] git diff failed` | Basisgrenen findes ikke i checkout; workflowet henter hele historikken, så tjek at pull requesten har en målgren |
+| `[configuration] langid is not installed` | Installationstrinnet fejlede; tjek de fastlåste versioner |
+| `[permissions] ... may not comment on pull requests` | Tokenet må ikke kommentere; giv `REPORT_TOKEN` skriveadgang til issues og pull requests |
+| Et fund, der ikke er et fund | Tilføj ordene til filen med tilladte ord, eller `english-comments: ignore` til kommentaren |

docs/wiki/EnglishComments.md

@@ -0,0 +1,106 @@
+<!-- Generated from guides/english-comments.md by tools/build_wiki.py. Edit the source, not this page. -->
+
+> This page is generated from [`guides/english-comments.md`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/guides/english-comments.md). Changes made here are overwritten the next time the wiki is published.
+
+English | [Dansk](EnglishComments.da) | [Bahasa Melayu](EnglishComments.ms)
+
+# Keeping source code comments in English
+
+How a software engineer calls the shared workflow that checks that the comments
+and docstrings of a pull request are written in English. The workflow fails the
+run when one is not, and writes one comment on the pull request that mentions
+the author. It changes no file and sends no source text outside the instance.
+Its decision is ADR-0012 in this repository.
+
+## Calling the workflow
+
+```yaml
+name: English comments
+
+on:
+  pull_request:
+
+jobs:
+  english-comments:
+    uses: TirSystem/github-action/.gitea/workflows/english-comments.yml@v2
+    with:
+      exclude: "docs/generated/**"
+      allowed-words-file: .english-comments-allowed-words
+```
+
+| Input | Default | Meaning |
+| --- | --- | --- |
+| `scope` | `changed` | `changed` checks the comments on the lines the pull request adds; `all` checks every tracked file |
+| `exclude` | | Comma list of file name or path patterns that are not checked (`*` and `**` are wildcards) |
+| `allowed-words-file` | | A file of the repository with words that are never judged, one per line, `#` starts a comment |
+| `threshold` | `0.6` | The probability, above 0 and at most 1, from which a comment counts as not English |
+| `min-words` | `3` | A comment with fewer words is not judged |
+| `langid-version`, `numpy-version` | `1.1.6`, `2.1.3` | The pinned packages the detector needs |
+| `tools-ref` | the current major | The tag of this repository whose scripts are run; pin it together with the workflow |
+
+The optional secret `REPORT_TOKEN` is a Gitea token that may comment on pull
+requests. Without it the workflow uses the token of the run, so the comment is
+written by the Actions bot. A pull request from a fork has a read-only token:
+the check still fails the run, but no comment is written.
+
+## What is checked
+
+The comments and docstrings of the files of the languages in the code counter
+([code metrics](CodeMetrics)): Python, shell, PowerShell, C, C++, C#, Java,
+JavaScript, TypeScript, Go, Rust and SQL. Strings and code are not read.
+Consecutive comment lines form a block. Each line of a block is judged on its own
+(at least four words and a probability of at least 0.7), so an English line cannot
+hide a Danish one next to it; when no line is flagged, the block is judged as a whole
+(at least `min-words` words and `threshold`), so a sentence cut over short lines is not missed.
+
+Before a block is judged, everything that is not a word is removed: paths, URLs,
+options (`--output`), file names, identifiers (`snake_case`, `camelCase`),
+numbers, acronyms and constants (`JSON`), a leading label such as `Usage:`, and
+the words of the allowed-words file. A block with fewer than `min-words` words
+left is not judged, so a short comment passes. Comments that configure a tool
+(`noqa`, `type:`, `pragma`, `shellcheck`) are not read.
+
+## When the check fails
+
+The run fails, each finding is shown as an annotation (`::error file=...,line=...`)
+and in the log as `file:line: looks Danish (0.93): "the comment"`, and one comment
+on the pull request lists them and mentions the author. A new run updates that
+comment; when the pull request passes, the comment is marked resolved and no
+longer mentions anyone.
+
+Fix it by rewriting the comment in English. For a quotation or a name that is
+not English, either put `english-comments: ignore` in the comment (it skips the
+whole comment block it is in), or add the word to the allowed-words file.
+
+## Blocking the merge
+
+A failing run does not block a merge by itself. In the branch protection of the
+target branch, mark the check as required: run the workflow once on a pull
+request and choose its entry in the list of status checks (the exact name is
+made from the calling workflow, its job and the event). Setting branch
+protection is the repository owner's action; the workflow does not change it.
+
+## How accurate it is
+
+The detector is `langid`, limited to English, Danish, Norwegian, Swedish,
+German, French, Malay, Indonesian and Dutch. On the corpus of the repository it
+flags none of 300 English comments, 44 of 45 Danish and 41 of 45 Malay comments
+and all of the 48 German, Swedish, Norwegian and French ones (ADR-0012). Its
+limits:
+
+- a comment of one or two words, or one that is mostly names, is not judged;
+- a comment in poor English passes, and a comment that mixes English technical
+  terms with few Danish or Malay words can pass;
+- the Danish and Malay comments of the corpus were written for the test, not
+  collected from real code, so real code will show other misses. Report a miss
+  or a false positive with the comment, and it joins the corpus.
+
+## Troubleshooting
+
+| Message | Cause |
+| --- | --- |
+| `[configuration] give --base` | The workflow was started by an event that is not a pull request with `scope: changed`; call it on `pull_request` or use `scope: all` |
+| `[configuration] git diff failed` | The base branch is not in the checkout; the workflow fetches the full history, so check that the pull request has a target branch |
+| `[configuration] langid is not installed` | The install step failed; check the pinned versions |
+| `[permissions] ... may not comment on pull requests` | The token cannot comment; give `REPORT_TOKEN` write access to issues and pull requests |
+| A finding that is not a finding | Add the words to the allowed-words file, or `english-comments: ignore` to the comment |

docs/wiki/EnglishComments.ms.md

@@ -0,0 +1,110 @@
+<!-- translation of EnglishComments.md, source sha256 9dafcabbc807 -->
+
+> Ini ialah terjemahan [`EnglishComments`](EnglishComments). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
+
+[English](EnglishComments) | [Dansk](EnglishComments.da) | Bahasa Melayu
+
+# Memastikan komen kod sumber dalam bahasa Inggeris
+
+Cara seorang jurutera perisian memanggil aliran kerja bersama yang menyemak bahawa
+komen dan docstring sesuatu pull request ditulis dalam bahasa Inggeris. Aliran
+kerja menggagalkan larian apabila ada yang bukan bahasa Inggeris, dan menulis satu
+komen pada pull request yang menyebut penulisnya. Ia tidak mengubah sebarang fail
+dan tidak menghantar teks sumber keluar daripada instans. Keputusan di
+belakangnya ialah ADR-0012 dalam repositori ini.
+
+## Memanggil aliran kerja
+
+```yaml
+name: English comments
+
+on:
+  pull_request:
+
+jobs:
+  english-comments:
+    uses: TirSystem/github-action/.gitea/workflows/english-comments.yml@v2
+    with:
+      exclude: "docs/generated/**"
+      allowed-words-file: .english-comments-allowed-words
+```
+
+| Input | Lalai | Maksud |
+| --- | --- | --- |
+| `scope` | `changed` | `changed` menyemak komen pada baris yang ditambah oleh pull request; `all` menyemak setiap fail yang dijejaki |
+| `exclude` | | Senarai corak nama fail atau laluan yang dipisahkan koma dan tidak disemak (`*` dan `**` ialah kad liar) |
+| `allowed-words-file` | | Fail dalam repositori dengan perkataan yang tidak pernah dinilai, satu pada setiap baris; `#` memulakan komen |
+| `threshold` | `0.6` | Kebarangkalian, melebihi 0 dan paling banyak 1, yang mulai daripadanya sesuatu komen dianggap bukan bahasa Inggeris |
+| `min-words` | `3` | Komen dengan perkataan yang lebih sedikit tidak dinilai |
+| `langid-version`, `numpy-version` | `1.1.6`, `2.1.3` | Pakej tetap yang diperlukan oleh pengesan |
+| `tools-ref` | major semasa | Tag repositori ini yang skripnya dijalankan; tetapkan bersama aliran kerja |
+
+Secret pilihan `REPORT_TOKEN` ialah token Gitea yang boleh memberi komen pada pull
+request. Tanpanya, aliran kerja menggunakan token larian itu sendiri, jadi komen
+ditulis oleh bot Actions. Pull request daripada fork mempunyai token baca sahaja:
+semakan masih menggagalkan larian, tetapi tiada komen ditulis.
+
+## Apa yang disemak
+
+Komen dan docstring dalam fail bahasa yang dikenali oleh pengira kod
+([metrik kod](CodeMetrics)): Python, shell, PowerShell, C, C++, C#, Java,
+JavaScript, TypeScript, Go, Rust dan SQL. String dan kod tidak dibaca. Baris komen
+yang berturutan membentuk satu blok. Setiap baris dalam blok dinilai secara berasingan (sekurang-kurangnya
+empat perkataan dan kebarangkalian sekurang-kurangnya 0.7), jadi baris bahasa Inggeris tidak dapat menyembunyikan
+baris bahasa Denmark di sebelahnya; apabila tiada baris ditandakan, blok dinilai secara keseluruhan
+(sekurang-kurangnya `min-words` perkataan dan `threshold`), supaya ayat yang dipecahkan kepada baris pendek tidak terlepas.
+
+Sebelum sesuatu blok dinilai, segala yang bukan perkataan dibuang: laluan, URL,
+pilihan (`--output`), nama fail, pengecam (`snake_case`, `camelCase`), nombor,
+akronim dan pemalar (`JSON`), label di permulaan seperti `Usage:`, dan perkataan
+dalam fail perkataan yang dibenarkan. Blok yang tinggal kurang daripada
+`min-words` perkataan tidak dinilai, jadi komen pendek lulus. Komen yang
+mengkonfigurasi alat (`noqa`, `type:`, `pragma`, `shellcheck`) tidak dibaca.
+
+## Apabila semakan gagal
+
+Larian gagal, setiap penemuan dipaparkan sebagai anotasi (`::error file=...,line=...`)
+dan dalam log sebagai `file:line: looks Danish (0.93): "the comment"`, dan satu
+komen pada pull request menyenaraikannya serta menyebut penulisnya. Larian baharu
+mengemas kini komen itu; apabila pull request lulus, komen ditandakan selesai dan
+tidak lagi menyebut sesiapa.
+
+Betulkannya dengan menulis semula komen dalam bahasa Inggeris. Untuk petikan atau
+nama yang bukan bahasa Inggeris, sama ada letakkan `english-comments: ignore`
+dalam komen (ia melangkau seluruh blok komen tempat ia berada), atau tambahkan
+perkataan itu ke dalam fail perkataan yang dibenarkan.
+
+## Menyekat penggabungan
+
+Larian yang gagal tidak menyekat penggabungan dengan sendirinya. Dalam
+perlindungan cabang bagi cabang sasaran, tandakan semakan sebagai wajib: jalankan
+aliran kerja sekali pada sebuah pull request dan pilih entrinya dalam senarai
+semakan status (nama tepatnya dibentuk daripada aliran kerja pemanggil, kerjanya
+dan peristiwa). Menetapkan perlindungan cabang ialah tindakan pemilik repositori;
+aliran kerja tidak mengubahnya.
+
+## Sejauh mana ia tepat
+
+Pengesan ialah `langid`, terhad kepada bahasa Inggeris, Denmark, Norway, Sweden,
+Jerman, Perancis, Melayu, Indonesia dan Belanda. Pada korpus repositori, ia
+menandakan tiada satu pun daripada 300 komen bahasa Inggeris, 44 daripada 45
+komen bahasa Denmark dan 41 daripada 45 komen bahasa Melayu, serta kesemua 48
+komen bahasa Jerman, Sweden, Norway dan Perancis (ADR-0012). Batasannya:
+
+- komen satu atau dua perkataan, atau yang kebanyakannya nama, tidak dinilai;
+- komen dalam bahasa Inggeris yang lemah lulus, dan komen yang mencampurkan istilah
+  teknikal bahasa Inggeris dengan beberapa perkataan Denmark atau Melayu boleh lulus;
+- komen bahasa Denmark dan Melayu dalam korpus ditulis untuk ujian, bukan dikumpulkan
+  daripada kod sebenar, jadi kod sebenar akan menunjukkan kesilapan lain. Laporkan
+  komen yang terlepas atau penemuan palsu bersama komennya, dan ia akan masuk ke
+  dalam korpus.
+
+## Diagnosis
+
+| Mesej | Punca |
+| --- | --- |
+| `[configuration] give --base` | Aliran kerja dimulakan oleh peristiwa yang bukan pull request dengan `scope: changed`; panggil pada `pull_request` atau gunakan `scope: all` |
+| `[configuration] git diff failed` | Cabang asas tiada dalam checkout; aliran kerja mengambil seluruh sejarah, jadi semak bahawa pull request mempunyai cabang sasaran |
+| `[configuration] langid is not installed` | Langkah pemasangan gagal; semak versi yang ditetapkan |
+| `[permissions] ... may not comment on pull requests` | Token tidak boleh memberi komen; berikan `REPORT_TOKEN` akses tulis kepada isu dan pull request |
+| Penemuan yang bukan penemuan | Tambahkan perkataan ke dalam fail perkataan yang dibenarkan, atau `english-comments: ignore` pada komen |

docs/wiki/Home.da.md

@@ -1,4 +1,4 @@
-<!-- translation of Home.md, source sha256 b6796554f4eb -->
+<!-- translation of Home.md, source sha256 9b84b5cf7534 -->
 
 > Dette er en oversættelse af [`Home`](Home). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
 
@@ -13,21 +13,22 @@ En samling af genbrugelige Gitea Actions-workflows til DevOps-professionelle og
 
 Dette repository er den centrale samling af genbrugelig automatisering til TirSystems repositories. Det primære repository ligger på `git.tirsystem.com` (Gitea) og spejles med push til GitHub.
 
-Det indeholder ti workflows: synkronisering af metadata til GitHub-spejlet, publicering af wiki (scoped og genbrugeligt for repositories, der kalder det), fælles kvalitetskontrol for Python og shell, for C og C++ og for C#, et udgivelsesworkflow, publicering af accepterede milepæle og repositoryets egen validering. De er listet med formål og diagram under [Workflows](#workflows).
+Det indeholder elleve workflows: synkronisering af metadata til GitHub-spejlet, publicering af wiki (kaldt af hvert repository), fælles kvalitetskontrol for Python og shell, for C og C++ og for C#, kodemålinger og dækningsbadges, en kontrol af, at kommentarer er på engelsk, et udgivelsesworkflow, publicering af accepterede milepæle og repositoryets egen validering. De er listet med formål og diagram under [Workflows](#workflows).
 
 
 ## Workflows
 
-Der er ti workflows i dette repository. Et **scoped** workflow leveres af instansen til alle repositories i TirSystem-organisationerne og kræver intet i repositoryet; et **genbrugeligt** workflow kaldes fra et repository med `uses:`; de øvrige kører kun her. Diagrammerne er PlantUML-kildekode og er på engelsk.
+Der er elleve workflows i dette repository. Et **scoped** workflow leveres af instansen til alle repositories i TirSystem-organisationerne og kræver intet i repositoryet; et **genbrugeligt** workflow kaldes fra et repository med `uses:`; de øvrige kører kun her. Diagrammerne er PlantUML-kildekode og er på engelsk.
 
 | Workflow | Fil | Type | Starter ved | Formål |
 | --- | --- | --- | --- | --- |
 | Sync GitHub mirror metadata | [`sync-github-metadata.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/scoped_workflows/sync-github-metadata.yml) | Scoped | push til `main`, manuelt, dagligt kl. 03:17 UTC | Kopierer beskrivelsen og emnerne for et Gitea-repository til dets GitHub push-spejl |
-| Publish wiki | [`publish-wiki.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/scoped_workflows/publish-wiki.yml) | Scoped, tilmelding med `wiki/.publish`; forældet, afløses af det genbrugelige workflow nedenfor (ADR-0009) | push til `main`, der ændrer `wiki/**`, manuelt | Publicerer siderne i `wiki/` til repositoryets wiki |
 | Publish wiki pages | [`publish-wiki-pages.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/publish-wiki-pages.yml) | Genbrugeligt (`workflow_call`) | et kald fra et andet repository | Publicerer siderne i `docs/wiki/` (eller den mappe, `wiki_dir` angiver) til wikien i det kaldende repository |
 | Quality checks | [`quality-checks.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/quality-checks.yml) | Genbrugeligt (`workflow_call`) | et kald fra et andet repository | Kører ruff, mypy, shellcheck og shfmt på de sporede filer og ændrer intet |
 | Quality checks C++ | [`quality-checks-cpp.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/quality-checks-cpp.yml) | Genbrugeligt (`workflow_call`) | et kald fra et andet repository | Kører clang-format og clang-tidy i præcise versioner på de sporede C- og C++-filer og ændrer intet |
 | Quality checks C# | [`quality-checks-csharp.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/quality-checks-csharp.yml) | Genbrugeligt (`workflow_call`) | et kald fra et andet repository | Kører `dotnet format` og `dotnet build` på et præcist .NET SDK 10 eller nyere og ændrer intet |
+| Code metrics | [`code-metrics.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/code-metrics.yml) | Genbrugeligt (`workflow_call`) | et kald fra et andet repository | Tæller kodefilerne og kodelinjerne (uden kommentar- og tomme linjer), læser en Cobertura-dækningsrapport og committer tre SVG-badges til en `badges`-gren |
+| English comments | [`english-comments.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/english-comments.yml) | Genbrugeligt (`workflow_call`) | et kald fra et andet repository, på en pull request | Bedømmer sproget i de kommentarer og docstrings, en pull request tilføjer, lader kørslen fejle, når én ikke er engelsk, og skriver én kommentar på pull requesten, der nævner forfatteren |
 | Publish own wiki | [`publish-own-wiki.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/publish-own-wiki.yml) | Kun dette repository | push til `main`, der ændrer `docs/wiki/**`, manuelt | Kalder det genbrugelige workflow Publish wiki pages for dette repositorys wiki |
 | Release | [`release.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/release.yml) | Kun dette repository | manuelt | Opretter versionstagget, udgivelsessiden og major-tagget efter kontrollerne |
 | Publicering af accepterede milepæle | [`sync-milestones.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/sync-milestones.yml) | Kun dette repository | push til `main`, der ændrer `docs/milestones/**` eller `docs/sqa/reviews/**`, manuelt (tørkørsel som standard) | Opretter eller opdaterer Gitea-milepælen og issues for hver milepæl, der er Accepted med en Go-gennemgang |
@@ -99,50 +100,6 @@ deactivate Workflow
 @enduml
 ```
 
-### Publicering af wiki (scoped, forældet)
-
-Publicerer `wiki/` til repositoryets wiki, kun i et repository, der har tilmeldt sig med `wiki/.publish`. Ordet `prune` i den fil sletter også sider, som ikke findes i `wiki/`.
-
-#### Workflow
-
-```plantuml
-@startuml
-title Publish wiki/ to the repository wiki
-
-autonumber
-
-actor "Push to main that changes wiki/**,\nor manual trigger" as Trigger
-participant "Gitea Actions\npublish-wiki" as Workflow
-participant "shared-scripts\n(tools/publish_wiki.py at v1)" as Script
-participant "Gitea wiki API" as Wiki
-
-Trigger -> Workflow: Start workflow
-activate Workflow
-Workflow -> Script: Check out the repository and the script, run it
-activate Script
-
-alt wiki/.publish does not exist
-  Script --> Workflow: Log that publishing is not enabled and succeed\n(nothing is written)
-else wiki/ has no Markdown pages
-  Script --> Workflow: Fail with [configuration]\n(an empty wiki/ never deletes pages)
-else
-  Script -> Script: Read the marker (empty, or the word prune)\nand TOKEN_FOR_GITEA_WIKI
-  Script -> Wiki: GET repository (preflight)
-  Wiki --> Script: Wiki is enabled, token accepted
-  Script -> Wiki: GET pages
-  Wiki --> Script: Existing pages
-  Script -> Wiki: Create new pages, update changed pages
-  opt marker says prune
-    Script -> Wiki: Delete pages that are not in wiki/
-  end
-  Script --> Workflow: Log created, updated and deleted counts
-end
-deactivate Script
-Workflow --> Trigger: Workflow result
-deactivate Workflow
-@enduml
-```
-
 ### Kvalitetskontrol
 
 Et genbrugeligt workflow til Python og shell, kaldt med `uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v1` (se [vejledningen](QualityChecksPythonShell)).
@@ -279,6 +236,90 @@ deactivate Workflow
 @enduml
 ```
 
+### Kodemålinger og dækningsbadges
+
+Et genbrugeligt workflow, der tæller kodefilerne og kodelinjerne (uden kommentar- og tomme linjer) i et repository og udgiver dem sammen med testdækningen som tre SVG-badges på en `badges`-gren, kaldt med `uses: TirSystem/github-action/.gitea/workflows/code-metrics.yml@v2` (ADR-0010). Det kræver `contents: write` og kører ingen test: et tidligere job hos kalderen frembringer en dækningsrapport i Cobertura XML-format og uploader den som artefakt ([vejledning](CodeMetrics.da)).
+
+#### Workflow
+
+```plantuml
+@startuml
+title Code metrics and coverage badges (reusable workflow)
+
+autonumber
+
+actor "Calling repository\nuses: ...code-metrics.yml@v2" as Caller
+participant "Gitea Actions\ncode-metrics" as Workflow
+participant "Branch badges\nof the caller" as Branch
+
+Caller -> Workflow: workflow_call with working-directory, exclude,\ncoverage-report and thresholds
+activate Workflow
+
+Workflow -> Workflow: Check out the caller and the shared scripts
+Workflow -> Workflow: Validate the inputs
+alt an input is invalid
+  Workflow --> Caller: Fail with [configuration]
+end
+
+Workflow -> Workflow: Download the coverage artifact (when given)
+Workflow -> Workflow: Count code files and lines of code
+alt a coverage report is given but missing or malformed
+  Workflow --> Caller: Fail with [configuration] that names the file
+else
+  Workflow -> Workflow: Write code-files.svg, code-lines.svg\nand coverage.svg
+end
+
+Workflow -> Branch: Compare with the files of the branch
+alt no badge changed
+  Workflow --> Caller: Notice: nothing to commit, pass
+else
+  Workflow -> Branch: One commit with [skip ci]
+  Workflow --> Caller: Badges published
+end
+deactivate Workflow
+@enduml
+```
+
+### Engelske kommentarer
+
+Et genbrugeligt workflow, der kontrollerer, at de kommentarer og docstrings, en pull request tilføjer, er skrevet på engelsk, lader kørslen fejle, når én ikke er det, og skriver én kommentar på pull requesten, der nævner forfatteren. Det ændrer ingen fil og sender ingen kildetekst ud af instansen; at markere kontrollen som påkrævet i grenbeskyttelsen er det, der blokerer sammenfletningen ([vejledning](EnglishComments.da), ADR-0012).
+
+#### Workflow
+
+```plantuml
+@startuml
+title English comments check (reusable workflow)
+
+autonumber
+
+actor "Pull request
+uses: ...english-comments.yml@v2" as Caller
+participant "Gitea Actions
+english-comments" as Workflow
+participant "Gitea REST API" as Gitea
+
+Caller -> Workflow: workflow_call with scope, exclude,
+allowed-words-file, threshold and min-words
+activate Workflow
+
+Workflow -> Workflow: Check out the full history and the shared scripts
+Workflow -> Workflow: Install the pinned language detector
+Workflow -> Workflow: Read the comments on the added lines
+Workflow -> Workflow: Remove paths, options, identifiers and allowed words
+Workflow -> Workflow: Judge the language of each comment block
+
+alt a block is not English
+  Workflow -> Gitea: Create or update one comment that mentions the author
+  Workflow --> Caller: run failed (the required check blocks the merge)
+else all blocks are English
+  Workflow -> Gitea: Mark an earlier comment resolved
+  Workflow --> Caller: run passed
+end
+
+deactivate Workflow
+@enduml
+```
+
 ### Udgivelse
 
 Startes manuelt af en vedligeholder; med `dry_run` `true` (standard) kontrollerer det kun (se [udgivelsesprocessen](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/guides/release-process.md)).

docs/wiki/Home.md

@@ -13,21 +13,22 @@ A collection of reusable Gitea Actions workflows for DevOps professionals and so
 
 This repository is the central collection of reusable automation for TirSystem repositories. The primary repository lives at `git.tirsystem.com` (Gitea) and is push-mirrored to GitHub.
 
-It contains ten workflows: metadata sync to the GitHub mirror, wiki publishing (scoped, and reusable for repositories that call it), shared quality checks for Python and shell, for C and C++ and for C#, a release workflow, the publishing of accepted milestones and the repository's own validation. They are listed with their purpose and a diagram under [Workflows](#workflows).
+It contains eleven workflows: metadata sync to the GitHub mirror, wiki publishing (called by each repository), shared quality checks for Python and shell, for C and C++ and for C#, code metrics and coverage badges, a check that comments are in English, a release workflow, the publishing of accepted milestones and the repository's own validation. They are listed with their purpose and a diagram under [Workflows](#workflows).
 
 
 ## Workflows
 
-Ten workflows live in this repository. A **scoped** workflow is delivered by the instance to every repository of the TirSystem organizations and needs nothing in the repository; a **reusable** workflow is called by a repository with `uses:`; the others run only here. The diagrams are PlantUML source.
+Eleven workflows live in this repository. A **scoped** workflow is delivered by the instance to every repository of the TirSystem organizations and needs nothing in the repository; a **reusable** workflow is called by a repository with `uses:`; the others run only here. The diagrams are PlantUML source.
 
 | Workflow | File | Kind | Starts on | Purpose |
 | --- | --- | --- | --- | --- |
 | Sync GitHub mirror metadata | [`sync-github-metadata.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/scoped_workflows/sync-github-metadata.yml) | Scoped | push to `main`, manual, daily 03:17 UTC | Copies the description and topics of a Gitea repository to its GitHub push mirror |
-| Publish wiki | [`publish-wiki.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/scoped_workflows/publish-wiki.yml) | Scoped, opt-in with `wiki/.publish`; deprecated, replaced by the reusable workflow below (ADR-0009) | push to `main` that changes `wiki/**`, manual | Publishes the pages in `wiki/` to the repository wiki |
 | Publish wiki pages | [`publish-wiki-pages.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/publish-wiki-pages.yml) | Reusable (`workflow_call`) | a call from another repository | Publishes the pages in `docs/wiki/` (or the folder named by `wiki_dir`) to the wiki of the calling repository |
 | Quality checks | [`quality-checks.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/quality-checks.yml) | Reusable (`workflow_call`) | a call from another repository | Runs ruff, mypy, shellcheck and shfmt on the tracked files and changes nothing |
 | Quality checks C++ | [`quality-checks-cpp.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/quality-checks-cpp.yml) | Reusable (`workflow_call`) | a call from another repository | Runs clang-format and clang-tidy at exact versions on the tracked C and C++ files and changes nothing |
 | Quality checks C# | [`quality-checks-csharp.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/quality-checks-csharp.yml) | Reusable (`workflow_call`) | a call from another repository | Runs `dotnet format` and `dotnet build` on an exact .NET SDK 10 or later and changes nothing |
+| Code metrics | [`code-metrics.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/code-metrics.yml) | Reusable (`workflow_call`) | a call from another repository | Counts the code files and the lines of code (without comment and blank lines), reads a Cobertura coverage report and commits three SVG badges to a `badges` branch |
+| English comments | [`english-comments.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/english-comments.yml) | Reusable (`workflow_call`) | a call from another repository, on a pull request | Judges the language of the comments and docstrings a pull request adds, fails the run when one is not English and writes one comment on the pull request that mentions the author |
 | Publish own wiki | [`publish-own-wiki.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/publish-own-wiki.yml) | This repository only | push to `main` that changes `docs/wiki/**`, manual | Calls the reusable Publish wiki pages workflow for the wiki of this repository |
 | Release | [`release.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/release.yml) | This repository only | manual | Creates the version tag, the release page and the major tag after the checks |
 | Publish accepted milestones | [`sync-milestones.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/sync-milestones.yml) | This repository only | push to `main` that changes `docs/milestones/**` or `docs/sqa/reviews/**`, manual (dry run by default) | Creates or updates the Gitea milestone and issues of every milestone that is Accepted with a Go review |
@@ -99,50 +100,6 @@ deactivate Workflow
 @enduml
 ```
 
-### Publish wiki (scoped, deprecated)
-
-Publishes `wiki/` to the repository wiki, only in a repository that has opted in with `wiki/.publish`. The word `prune` in that file also deletes pages that are not in `wiki/`.
-
-#### Workflow
-
-```plantuml
-@startuml
-title Publish wiki/ to the repository wiki
-
-autonumber
-
-actor "Push to main that changes wiki/**,\nor manual trigger" as Trigger
-participant "Gitea Actions\npublish-wiki" as Workflow
-participant "shared-scripts\n(tools/publish_wiki.py at v1)" as Script
-participant "Gitea wiki API" as Wiki
-
-Trigger -> Workflow: Start workflow
-activate Workflow
-Workflow -> Script: Check out the repository and the script, run it
-activate Script
-
-alt wiki/.publish does not exist
-  Script --> Workflow: Log that publishing is not enabled and succeed\n(nothing is written)
-else wiki/ has no Markdown pages
-  Script --> Workflow: Fail with [configuration]\n(an empty wiki/ never deletes pages)
-else
-  Script -> Script: Read the marker (empty, or the word prune)\nand TOKEN_FOR_GITEA_WIKI
-  Script -> Wiki: GET repository (preflight)
-  Wiki --> Script: Wiki is enabled, token accepted
-  Script -> Wiki: GET pages
-  Wiki --> Script: Existing pages
-  Script -> Wiki: Create new pages, update changed pages
-  opt marker says prune
-    Script -> Wiki: Delete pages that are not in wiki/
-  end
-  Script --> Workflow: Log created, updated and deleted counts
-end
-deactivate Script
-Workflow --> Trigger: Workflow result
-deactivate Workflow
-@enduml
-```
-
 ### Quality checks
 
 A reusable workflow for Python and shell, called with `uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v1` (see the [guide](QualityChecksPythonShell)).
@@ -279,6 +236,90 @@ deactivate Workflow
 @enduml
 ```
 
+### Code metrics
+
+A reusable workflow that counts the code files and the lines of code (without comment and blank lines) of a repository and publishes them, with the test coverage, as three SVG badges on a `badges` branch, called with `uses: TirSystem/github-action/.gitea/workflows/code-metrics.yml@v2` (ADR-0010). It needs `contents: write` and runs no test: an earlier job of the caller produces a Cobertura XML coverage report and uploads it as an artifact ([guide](CodeMetrics)).
+
+#### Workflow
+
+```plantuml
+@startuml
+title Code metrics and coverage badges (reusable workflow)
+
+autonumber
+
+actor "Calling repository\nuses: ...code-metrics.yml@v2" as Caller
+participant "Gitea Actions\ncode-metrics" as Workflow
+participant "Branch badges\nof the caller" as Branch
+
+Caller -> Workflow: workflow_call with working-directory, exclude,\ncoverage-report and thresholds
+activate Workflow
+
+Workflow -> Workflow: Check out the caller and the shared scripts
+Workflow -> Workflow: Validate the inputs
+alt an input is invalid
+  Workflow --> Caller: Fail with [configuration]
+end
+
+Workflow -> Workflow: Download the coverage artifact (when given)
+Workflow -> Workflow: Count code files and lines of code
+alt a coverage report is given but missing or malformed
+  Workflow --> Caller: Fail with [configuration] that names the file
+else
+  Workflow -> Workflow: Write code-files.svg, code-lines.svg\nand coverage.svg
+end
+
+Workflow -> Branch: Compare with the files of the branch
+alt no badge changed
+  Workflow --> Caller: Notice: nothing to commit, pass
+else
+  Workflow -> Branch: One commit with [skip ci]
+  Workflow --> Caller: Badges published
+end
+deactivate Workflow
+@enduml
+```
+
+### English comments
+
+A reusable workflow that checks that the comments and docstrings a pull request adds are written in English, fails the run when one is not, and writes one comment on the pull request that mentions the author. It changes no file and sends no source text outside the instance; marking the check as required in the branch protection is what blocks the merge ([guide](EnglishComments), ADR-0012).
+
+#### Workflow
+
+```plantuml
+@startuml
+title English comments check (reusable workflow)
+
+autonumber
+
+actor "Pull request
+uses: ...english-comments.yml@v2" as Caller
+participant "Gitea Actions
+english-comments" as Workflow
+participant "Gitea REST API" as Gitea
+
+Caller -> Workflow: workflow_call with scope, exclude,
+allowed-words-file, threshold and min-words
+activate Workflow
+
+Workflow -> Workflow: Check out the full history and the shared scripts
+Workflow -> Workflow: Install the pinned language detector
+Workflow -> Workflow: Read the comments on the added lines
+Workflow -> Workflow: Remove paths, options, identifiers and allowed words
+Workflow -> Workflow: Judge the language of each comment block
+
+alt a block is not English
+  Workflow -> Gitea: Create or update one comment that mentions the author
+  Workflow --> Caller: run failed (the required check blocks the merge)
+else all blocks are English
+  Workflow -> Gitea: Mark an earlier comment resolved
+  Workflow --> Caller: run passed
+end
+
+deactivate Workflow
+@enduml
+```
+
 ### Release
 
 Started by hand by a maintainer; with `dry_run` `true` (the default) it only checks (see the [release process](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/guides/release-process.md)).

docs/wiki/Home.ms.md

@@ -1,4 +1,4 @@
-<!-- translation of Home.md, source sha256 b6796554f4eb -->
+<!-- translation of Home.md, source sha256 9b84b5cf7534 -->
 
 > Ini ialah terjemahan [`Home`](Home). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
 
@@ -13,21 +13,22 @@ Koleksi aliran kerja (workflow) Gitea Actions yang boleh digunakan semula untuk
 
 Repositori ini ialah koleksi pusat bagi automasi yang boleh digunakan semula untuk repositori TirSystem. Repositori utama berada di `git.tirsystem.com` (Gitea) dan dicerminkan dengan push ke GitHub.
 
-Ia mengandungi sepuluh aliran kerja: penyegerakan metadata ke cermin GitHub, penerbitan wiki (scoped, dan boleh guna semula bagi repositori yang memanggilnya), semakan kualiti bersama untuk Python dan shell, untuk C dan C++ serta untuk C#, aliran kerja keluaran, penerbitan pencapaian (milestone) yang diterima dan pengesahan repositori sendiri. Ia disenaraikan dengan tujuan dan rajah di bawah [Aliran kerja](#aliran-kerja).
+Ia mengandungi sebelas aliran kerja: penyegerakan metadata ke cermin GitHub, penerbitan wiki (dipanggil oleh setiap repositori), semakan kualiti bersama untuk Python dan shell, untuk C dan C++ serta untuk C#, metrik kod dan lencana liputan, semakan bahawa komen ditulis dalam bahasa Inggeris, aliran kerja keluaran, penerbitan pencapaian (milestone) yang diterima dan pengesahan repositori sendiri. Ia disenaraikan dengan tujuan dan rajah di bawah [Aliran kerja](#aliran-kerja).
 
 
 ## Aliran kerja
 
-Terdapat sepuluh aliran kerja dalam repositori ini. Aliran kerja **scoped** dihantar oleh instans ke setiap repositori organisasi TirSystem dan tidak memerlukan apa-apa dalam repositori; aliran kerja **boleh guna semula** dipanggil oleh sebuah repositori dengan `uses:`; yang lain hanya berjalan di sini. Rajah ialah kod sumber PlantUML dan dalam bahasa Inggeris.
+Terdapat sebelas aliran kerja dalam repositori ini. Aliran kerja **scoped** dihantar oleh instans ke setiap repositori organisasi TirSystem dan tidak memerlukan apa-apa dalam repositori; aliran kerja **boleh guna semula** dipanggil oleh sebuah repositori dengan `uses:`; yang lain hanya berjalan di sini. Rajah ialah kod sumber PlantUML dan dalam bahasa Inggeris.
 
 | Aliran kerja | Fail | Jenis | Bermula apabila | Tujuan |
 | --- | --- | --- | --- | --- |
 | Sync GitHub mirror metadata | [`sync-github-metadata.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/scoped_workflows/sync-github-metadata.yml) | Scoped | push ke `main`, manual, setiap hari 03:17 UTC | Menyalin penerangan dan topik repositori Gitea ke push mirror GitHub-nya |
-| Publish wiki | [`publish-wiki.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/scoped_workflows/publish-wiki.yml) | Scoped, pilih menyertai dengan `wiki/.publish`; usang, sedang diganti oleh aliran kerja boleh guna semula di bawah (ADR-0009) | push ke `main` yang mengubah `wiki/**`, manual | Menerbitkan halaman dalam `wiki/` ke wiki repositori |
 | Publish wiki pages | [`publish-wiki-pages.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/publish-wiki-pages.yml) | Boleh guna semula (`workflow_call`) | panggilan daripada repositori lain | Menerbitkan halaman dalam `docs/wiki/` (atau folder yang dinamakan oleh `wiki_dir`) ke wiki repositori pemanggil |
 | Quality checks | [`quality-checks.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/quality-checks.yml) | Boleh guna semula (`workflow_call`) | panggilan daripada repositori lain | Menjalankan ruff, mypy, shellcheck dan shfmt pada fail yang dijejaki dan tidak mengubah apa-apa |
 | Quality checks C++ | [`quality-checks-cpp.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/quality-checks-cpp.yml) | Boleh guna semula (`workflow_call`) | panggilan daripada repositori lain | Menjalankan clang-format dan clang-tidy pada versi tepat pada fail C dan C++ yang dijejaki dan tidak mengubah apa-apa |
 | Quality checks C# | [`quality-checks-csharp.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/quality-checks-csharp.yml) | Boleh guna semula (`workflow_call`) | panggilan daripada repositori lain | Menjalankan `dotnet format` dan `dotnet build` pada .NET SDK 10 atau lebih baharu yang tepat dan tidak mengubah apa-apa |
+| Code metrics | [`code-metrics.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/code-metrics.yml) | Boleh guna semula (`workflow_call`) | panggilan daripada repositori lain | Mengira fail kod dan baris kod (tanpa baris komen dan baris kosong), membaca laporan liputan Cobertura dan melakukan commit tiga lencana SVG ke cabang `badges` |
+| English comments | [`english-comments.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/english-comments.yml) | Boleh guna semula (`workflow_call`) | panggilan daripada repositori lain, pada pull request | Menilai bahasa komen dan docstring yang ditambah oleh pull request, menggagalkan larian apabila ada yang bukan bahasa Inggeris dan menulis satu komen pada pull request yang menyebut penulisnya |
 | Publish own wiki | [`publish-own-wiki.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/publish-own-wiki.yml) | Repositori ini sahaja | push ke `main` yang mengubah `docs/wiki/**`, manual | Memanggil aliran kerja boleh guna semula Publish wiki pages untuk wiki repositori ini |
 | Release | [`release.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/release.yml) | Repositori ini sahaja | manual | Mencipta tag versi, halaman keluaran dan tag major selepas semakan |
 | Menerbitkan milestone yang diterima | [`sync-milestones.yml`](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/.gitea/workflows/sync-milestones.yml) | Repositori ini sahaja | push ke `main` yang mengubah `docs/milestones/**` atau `docs/sqa/reviews/**`, manual (larian percubaan secara lalai) | Mencipta atau mengemas kini milestone Gitea dan isu bagi setiap milestone yang Accepted dengan semakan Go |
@@ -99,50 +100,6 @@ deactivate Workflow
 @enduml
 ```
 
-### Menerbitkan wiki (scoped, usang)
-
-Menerbitkan `wiki/` ke wiki repositori, hanya dalam repositori yang telah menyertai dengan `wiki/.publish`. Perkataan `prune` dalam fail itu juga memadam halaman yang tiada dalam `wiki/`.
-
-#### Aliran kerja
-
-```plantuml
-@startuml
-title Publish wiki/ to the repository wiki
-
-autonumber
-
-actor "Push to main that changes wiki/**,\nor manual trigger" as Trigger
-participant "Gitea Actions\npublish-wiki" as Workflow
-participant "shared-scripts\n(tools/publish_wiki.py at v1)" as Script
-participant "Gitea wiki API" as Wiki
-
-Trigger -> Workflow: Start workflow
-activate Workflow
-Workflow -> Script: Check out the repository and the script, run it
-activate Script
-
-alt wiki/.publish does not exist
-  Script --> Workflow: Log that publishing is not enabled and succeed\n(nothing is written)
-else wiki/ has no Markdown pages
-  Script --> Workflow: Fail with [configuration]\n(an empty wiki/ never deletes pages)
-else
-  Script -> Script: Read the marker (empty, or the word prune)\nand TOKEN_FOR_GITEA_WIKI
-  Script -> Wiki: GET repository (preflight)
-  Wiki --> Script: Wiki is enabled, token accepted
-  Script -> Wiki: GET pages
-  Wiki --> Script: Existing pages
-  Script -> Wiki: Create new pages, update changed pages
-  opt marker says prune
-    Script -> Wiki: Delete pages that are not in wiki/
-  end
-  Script --> Workflow: Log created, updated and deleted counts
-end
-deactivate Script
-Workflow --> Trigger: Workflow result
-deactivate Workflow
-@enduml
-```
-
 ### Semakan kualiti
 
 Aliran kerja boleh guna semula untuk Python dan shell, dipanggil dengan `uses: TirSystem/github-action/.gitea/workflows/quality-checks.yml@v1` (lihat [panduan](QualityChecksPythonShell)).
@@ -279,6 +236,90 @@ deactivate Workflow
 @enduml
 ```
 
+### Metrik kod dan lencana liputan
+
+Aliran kerja boleh guna semula yang mengira fail kod dan baris kod (tanpa baris komen dan baris kosong) sesebuah repositori dan menerbitkannya, bersama liputan ujian, sebagai tiga lencana SVG pada cabang `badges`, dipanggil dengan `uses: TirSystem/github-action/.gitea/workflows/code-metrics.yml@v2` (ADR-0010). Ia memerlukan `contents: write` dan tidak menjalankan sebarang ujian: kerja yang lebih awal oleh pemanggil menghasilkan laporan liputan format Cobertura XML dan memuat naiknya sebagai artifak ([panduan](CodeMetrics.ms)).
+
+#### Aliran kerja
+
+```plantuml
+@startuml
+title Code metrics and coverage badges (reusable workflow)
+
+autonumber
+
+actor "Calling repository\nuses: ...code-metrics.yml@v2" as Caller
+participant "Gitea Actions\ncode-metrics" as Workflow
+participant "Branch badges\nof the caller" as Branch
+
+Caller -> Workflow: workflow_call with working-directory, exclude,\ncoverage-report and thresholds
+activate Workflow
+
+Workflow -> Workflow: Check out the caller and the shared scripts
+Workflow -> Workflow: Validate the inputs
+alt an input is invalid
+  Workflow --> Caller: Fail with [configuration]
+end
+
+Workflow -> Workflow: Download the coverage artifact (when given)
+Workflow -> Workflow: Count code files and lines of code
+alt a coverage report is given but missing or malformed
+  Workflow --> Caller: Fail with [configuration] that names the file
+else
+  Workflow -> Workflow: Write code-files.svg, code-lines.svg\nand coverage.svg
+end
+
+Workflow -> Branch: Compare with the files of the branch
+alt no badge changed
+  Workflow --> Caller: Notice: nothing to commit, pass
+else
+  Workflow -> Branch: One commit with [skip ci]
+  Workflow --> Caller: Badges published
+end
+deactivate Workflow
+@enduml
+```
+
+### Komen dalam bahasa Inggeris
+
+Aliran kerja boleh guna semula yang menyemak bahawa komen dan docstring yang ditambah oleh pull request ditulis dalam bahasa Inggeris, menggagalkan larian apabila ada yang tidak, dan menulis satu komen pada pull request yang menyebut penulisnya. Ia tidak mengubah sebarang fail dan tidak menghantar teks sumber keluar daripada instans; menandakan semakan sebagai wajib dalam perlindungan cabang ialah yang menyekat penggabungan ([panduan](EnglishComments.ms), ADR-0012).
+
+#### Aliran kerja
+
+```plantuml
+@startuml
+title English comments check (reusable workflow)
+
+autonumber
+
+actor "Pull request
+uses: ...english-comments.yml@v2" as Caller
+participant "Gitea Actions
+english-comments" as Workflow
+participant "Gitea REST API" as Gitea
+
+Caller -> Workflow: workflow_call with scope, exclude,
+allowed-words-file, threshold and min-words
+activate Workflow
+
+Workflow -> Workflow: Check out the full history and the shared scripts
+Workflow -> Workflow: Install the pinned language detector
+Workflow -> Workflow: Read the comments on the added lines
+Workflow -> Workflow: Remove paths, options, identifiers and allowed words
+Workflow -> Workflow: Judge the language of each comment block
+
+alt a block is not English
+  Workflow -> Gitea: Create or update one comment that mentions the author
+  Workflow --> Caller: run failed (the required check blocks the merge)
+else all blocks are English
+  Workflow -> Gitea: Mark an earlier comment resolved
+  Workflow --> Caller: run passed
+end
+
+deactivate Workflow
+@enduml
+```
+
 ### Keluaran
 
 Dimulakan secara manual oleh penyelenggara; dengan `dry_run` `true` (lalai) ia hanya menyemak (lihat [proses keluaran](https://git.tirsystem.com/TirSystem/github-action/src/branch/main/guides/release-process.md)).

docs/wiki/Onboarding.da.md

@@ -1,4 +1,4 @@
-<!-- translation of Onboarding.md, source sha256 4de4897fb3b7 -->
+<!-- translation of Onboarding.md, source sha256 1bc66efd5874 -->
 
 > Dette er en oversættelse af [`Onboarding`](Onboarding). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
 
@@ -56,8 +56,6 @@ Det genbrugelige workflow **Publish wiki pages** kopierer Markdown-siderne i `do
 4. Gem `TOKEN_FOR_GITEA_WIKI` som en secret i repositoryets organisation med det scope, der står i [credentials.md](Credentials.da).
 5. Flet ændringen til `main`. Loggen skal slutte med `Published <n> page(s) to the wiki of <owner>/<repo>`.
 
-Et repository, der stadig har markøren `wiki/.publish`, publiceres af det ældre scoped workflow, som fjernes, når alle repositories har et kald. Flyt siderne til `docs/wiki/` og tilføj kaldet, før det sker.
-
 ## Runners
 
 | Punkt | Værdi |

docs/wiki/Onboarding.md

@@ -85,10 +85,6 @@ The wiki has English and the product owner's language as a minimum.
 5. Merge the change to `main`. The log must end with `Published <n> page(s) to
    the wiki of <owner>/<repo>`.
 
-A repository that still has the marker `wiki/.publish` is published by the
-older scoped workflow, which is removed once every repository has a call.
-Move the pages to `docs/wiki/` and add the call before that.
-
 ## Runners
 
 | Item | Value |

docs/wiki/Onboarding.ms.md

@@ -1,4 +1,4 @@
-<!-- translation of Onboarding.md, source sha256 4de4897fb3b7 -->
+<!-- translation of Onboarding.md, source sha256 1bc66efd5874 -->
 
 > Ini ialah terjemahan [`Onboarding`](Onboarding). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
 
@@ -56,8 +56,6 @@ Aliran kerja boleh guna semula **Publish wiki pages** menyalin halaman Markdown
 4. Simpan `TOKEN_FOR_GITEA_WIKI` sebagai secret organisasi repositori, dengan skop yang tertera dalam [credentials.md](Credentials.ms).
 5. Gabungkan perubahan ke `main`. Log mesti berakhir dengan `Published <n> page(s) to the wiki of <owner>/<repo>`.
 
-Repositori yang masih mempunyai penanda `wiki/.publish` diterbitkan oleh aliran kerja scoped yang lebih lama, yang dibuang apabila setiap repositori mempunyai panggilan. Alihkan halaman ke `docs/wiki/` dan tambah panggilan sebelum itu.
-
 ## Runners
 
 | Perkara | Nilai |

docs/wiki/QualityChecksCSharp.da.md

@@ -1,4 +1,4 @@
-<!-- translation of QualityChecksCSharp.md, source sha256 36e34031e0b9 -->
+<!-- translation of QualityChecksCSharp.md, source sha256 a024fde8d1b3 -->
 
 > Dette er en oversættelse af [`QualityChecksCSharp`](QualityChecksCSharp). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
 
@@ -32,7 +32,7 @@ jobs:
 | `working-directory` | `.` | Mappe, relativt til repositoryets rod, hvis filer kontrolleres |
 | `project` | tom | Solution- eller projektfil, relativt til `working-directory`; tom bruger den eneste sporede `*.sln` eller `*.slnx`, ellers den eneste `*.csproj`, der er sporet dér |
 | `dotnet-sdk-version` | `10.0.401` | Præcis version af .NET SDK, 10 eller nyere; en kanal som `10.0`, et interval og en version under 10 afvises |
-| `tools-ref` | `v1` | Tag eller gren i `TirSystem/github-action`, hvorfra scriptet `tools/quality-checks-csharp.sh` hentes |
+| `tools-ref` | `v2` | Tag eller gren i `TirSystem/github-action`, hvorfra scriptet `tools/quality-checks-csharp.sh` hentes |
 
 Henvis til workflowet ved major-tagget (`@v1`) eller et præcist tag, aldrig ved `main`. Et kald ved et præcist tag er kun fuldt fastlåst, når `tools-ref` angiver samme tag. Se opgraderingsvejledningen. SDK-versionen er præcis: at hæve standardværdien er en ny udgivelse af dette repository, ikke en stille ændring.
 

docs/wiki/QualityChecksCSharp.md

@@ -36,7 +36,7 @@ jobs:
 | `working-directory` | `.` | Directory, relative to the repository root, whose files are checked |
 | `project` | empty | Solution or project file, relative to `working-directory`; empty uses the single `*.sln` or `*.slnx`, else the single `*.csproj`, that is tracked there |
 | `dotnet-sdk-version` | `10.0.401` | Exact version of the .NET SDK, 10 or later; a channel such as `10.0`, a range and a version below 10 are refused |
-| `tools-ref` | `v1` | Tag or branch of `TirSystem/github-action` from which the script `tools/quality-checks-csharp.sh` is fetched |
+| `tools-ref` | `v2` | Tag or branch of `TirSystem/github-action` from which the script `tools/quality-checks-csharp.sh` is fetched |
 
 Reference the workflow at the major tag (`@v1`) or at an exact tag, never at
 `main`. A call at an exact tag is pinned completely only when `tools-ref` names

docs/wiki/QualityChecksCSharp.ms.md

@@ -1,4 +1,4 @@
-<!-- translation of QualityChecksCSharp.md, source sha256 36e34031e0b9 -->
+<!-- translation of QualityChecksCSharp.md, source sha256 a024fde8d1b3 -->
 
 > Ini ialah terjemahan [`QualityChecksCSharp`](QualityChecksCSharp). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
 
@@ -32,7 +32,7 @@ jobs:
 | `working-directory` | `.` | Direktori, relatif kepada akar repositori, yang failnya disemak |
 | `project` | kosong | Fail solution atau projek, relatif kepada `working-directory`; kosong menggunakan satu-satunya `*.sln` atau `*.slnx` yang dijejaki, jika tiada maka satu-satunya `*.csproj` yang dijejaki di situ |
 | `dotnet-sdk-version` | `10.0.401` | Versi tepat .NET SDK, 10 atau lebih baharu; saluran seperti `10.0`, julat dan versi di bawah 10 ditolak |
-| `tools-ref` | `v1` | Tag atau cabang `TirSystem/github-action` tempat skrip `tools/quality-checks-csharp.sh` diambil |
+| `tools-ref` | `v2` | Tag atau cabang `TirSystem/github-action` tempat skrip `tools/quality-checks-csharp.sh` diambil |
 
 Rujuk aliran kerja pada tag major (`@v1`) atau pada tag tepat, jangan sekali-kali pada `main`. Panggilan pada tag tepat hanya disematkan sepenuhnya apabila `tools-ref` menamakan tag yang sama. Lihat panduan naik taraf. Versi SDK adalah tepat: menaikkan nilai lalai ialah keluaran baharu repositori ini, bukan perubahan senyap.
 

docs/wiki/QualityChecksCpp.da.md

@@ -1,4 +1,4 @@
-<!-- translation of QualityChecksCpp.md, source sha256 6faa57183a11 -->
+<!-- translation of QualityChecksCpp.md, source sha256 29d1e1390494 -->
 
 > Dette er en oversættelse af [`QualityChecksCpp`](QualityChecksCpp). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
 
@@ -34,7 +34,7 @@ jobs:
 | `compile-commands-dir` | tom | Mappe, relativt til repositoryets rod, med en `compile_commands.json`, som din pipeline har bygget før kaldet; når den er sat, bruger clang-tidy den og ignorerer `std` |
 | `clang-format-version` | `23.1.3` | Præcis version af pakken clang-format |
 | `clang-tidy-version` | `22.1.8` | Præcis version af pakken clang-tidy |
-| `tools-ref` | `v1` | Tag eller gren i `TirSystem/github-action`, hvorfra scriptet `tools/quality-checks-cpp.sh` hentes |
+| `tools-ref` | `v2` | Tag eller gren i `TirSystem/github-action`, hvorfra scriptet `tools/quality-checks-cpp.sh` hentes |
 
 Henvis til workflowet ved major-tagget (`@v1`) eller et præcist tag, aldrig ved `main`. Et kald ved et præcist tag er kun fuldt fastlåst, når `tools-ref` angiver samme tag. Se opgraderingsvejledningen. Værktøjsversionerne er præcise: en nyere version af et værktøj er en ny udgivelse af dette repository, ikke en stille ændring.
 

docs/wiki/QualityChecksCpp.md

@@ -37,7 +37,7 @@ jobs:
 | `compile-commands-dir` | empty | Directory, relative to the repository root, with a `compile_commands.json` that your pipeline built before the call; when set, clang-tidy uses it and ignores `std` |
 | `clang-format-version` | `23.1.3` | Exact version of the clang-format package |
 | `clang-tidy-version` | `22.1.8` | Exact version of the clang-tidy package |
-| `tools-ref` | `v1` | Tag or branch of `TirSystem/github-action` from which the script `tools/quality-checks-cpp.sh` is fetched |
+| `tools-ref` | `v2` | Tag or branch of `TirSystem/github-action` from which the script `tools/quality-checks-cpp.sh` is fetched |
 
 Reference the workflow at the major tag (`@v1`) or at an exact tag, never at
 `main`. A call at an exact tag is pinned completely only when `tools-ref` names

docs/wiki/QualityChecksCpp.ms.md

@@ -1,4 +1,4 @@
-<!-- translation of QualityChecksCpp.md, source sha256 6faa57183a11 -->
+<!-- translation of QualityChecksCpp.md, source sha256 29d1e1390494 -->
 
 > Ini ialah terjemahan [`QualityChecksCpp`](QualityChecksCpp). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
 
@@ -34,7 +34,7 @@ jobs:
 | `compile-commands-dir` | kosong | Direktori, relatif kepada akar repositori, dengan `compile_commands.json` yang dibina oleh saluran paip anda sebelum panggilan; apabila ditetapkan, clang-tidy menggunakannya dan mengabaikan `std` |
 | `clang-format-version` | `23.1.3` | Versi tepat pakej clang-format |
 | `clang-tidy-version` | `22.1.8` | Versi tepat pakej clang-tidy |
-| `tools-ref` | `v1` | Tag atau cabang `TirSystem/github-action` tempat skrip `tools/quality-checks-cpp.sh` diambil |
+| `tools-ref` | `v2` | Tag atau cabang `TirSystem/github-action` tempat skrip `tools/quality-checks-cpp.sh` diambil |
 
 Rujuk aliran kerja pada tag major (`@v1`) atau pada tag tepat, jangan sekali-kali pada `main`. Panggilan pada tag tepat hanya disematkan sepenuhnya apabila `tools-ref` menamakan tag yang sama. Lihat panduan naik taraf. Versi alat adalah tepat: versi alat yang lebih baharu ialah keluaran baharu repositori ini, bukan perubahan senyap.
 

docs/wiki/QualityChecksPythonShell.da.md

@@ -1,4 +1,4 @@
-<!-- translation of QualityChecksPythonShell.md, source sha256 2a0c9d43c77d -->
+<!-- translation of QualityChecksPythonShell.md, source sha256 ef64b44b88ad -->
 
 > Dette er en oversættelse af [`QualityChecksPythonShell`](QualityChecksPythonShell). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
 
@@ -35,7 +35,7 @@ jobs:
 | `mypy-version` | `1.11.2` | Version af mypy |
 | `shellcheck-py-version` | `0.10.0.1` | Version af pakken shellcheck-py (ShellCheck 0.10.0) |
 | `shfmt-py-version` | `3.11.0.2` | Version af pakken shfmt-py (shfmt 3.11.0) |
-| `tools-ref` | `v1` | Tag eller gren i `TirSystem/github-action`, hvorfra scriptet `tools/quality-checks.sh` hentes |
+| `tools-ref` | `v2` | Tag eller gren i `TirSystem/github-action`, hvorfra scriptet `tools/quality-checks.sh` hentes |
 
 Henvis til workflowet ved major-tagget (`@v1`) eller et præcist tag (`@v1.0.0`), aldrig ved `main` og aldrig ved en pull requests gren: den gren slettes, når pull requesten flettes, og henvisningen holder op med at virke. Se opgraderingsvejledningen for, hvad hvert valg modtager.
 

docs/wiki/QualityChecksPythonShell.md

@@ -38,7 +38,7 @@ jobs:
 | `mypy-version` | `1.11.2` | Version of mypy |
 | `shellcheck-py-version` | `0.10.0.1` | Version of the shellcheck-py package (ShellCheck 0.10.0) |
 | `shfmt-py-version` | `3.11.0.2` | Version of the shfmt-py package (shfmt 3.11.0) |
-| `tools-ref` | `v1` | Tag or branch of `TirSystem/github-action` from which the script `tools/quality-checks.sh` is fetched |
+| `tools-ref` | `v2` | Tag or branch of `TirSystem/github-action` from which the script `tools/quality-checks.sh` is fetched |
 
 Reference the workflow at the major tag (`@v1`) or at an exact tag
 (`@v1.0.0`), never at `main` and never at the branch of a pull request: that

docs/wiki/QualityChecksPythonShell.ms.md

@@ -1,4 +1,4 @@
-<!-- translation of QualityChecksPythonShell.md, source sha256 2a0c9d43c77d -->
+<!-- translation of QualityChecksPythonShell.md, source sha256 ef64b44b88ad -->
 
 > Ini ialah terjemahan [`QualityChecksPythonShell`](QualityChecksPythonShell). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
 
@@ -35,7 +35,7 @@ jobs:
 | `mypy-version` | `1.11.2` | Versi mypy |
 | `shellcheck-py-version` | `0.10.0.1` | Versi pakej shellcheck-py (ShellCheck 0.10.0) |
 | `shfmt-py-version` | `3.11.0.2` | Versi pakej shfmt-py (shfmt 3.11.0) |
-| `tools-ref` | `v1` | Tag atau cabang `TirSystem/github-action` tempat skrip `tools/quality-checks.sh` diambil |
+| `tools-ref` | `v2` | Tag atau cabang `TirSystem/github-action` tempat skrip `tools/quality-checks.sh` diambil |
 
 Rujuk aliran kerja pada tag major (`@v1`) atau pada tag tepat (`@v1.0.0`), jangan sekali-kali pada `main` dan jangan pada cabang pull request: cabang itu dipadam apabila pull request digabungkan dan rujukan itu berhenti berfungsi. Lihat panduan naik taraf untuk apa yang diterima oleh setiap pilihan.
 

docs/wiki/Troubleshooting.da.md

@@ -1,4 +1,4 @@
-<!-- translation of Troubleshooting.md, source sha256 c68827295812 -->
+<!-- translation of Troubleshooting.md, source sha256 cad6363616e8 -->
 
 > Dette er en oversættelse af [`Troubleshooting`](Troubleshooting). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
 
@@ -31,7 +31,6 @@ Kategorien fortæller, hvor du skal kigge. En fejl uden for scriptet (jobbet sta
 | `Could not determine the Gitea source repository.` | configuration | Kørslen har intet repositorynavn; meld det som en defekt |
 | `Expected at most one GitHub push mirror ... found N` | configuration | Behold ét GitHub push-spejl |
 | `TOKEN_FOR_GITEA_WIKI is missing or empty.` | configuration | Kun wiki-publicering: repositoryet kalder workflowet, men dets organisation har ingen sådan secret, eller kaldet sender den ikke; gem den og send den i `secrets:` (se [credentials.md](Credentials.da)) |
-| `wiki/.publish may only be empty or contain the word 'prune'.` | configuration | Kun wiki-publicering gennem det ældre scoped workflow: lad markøren være tom, eller skriv kun ordet `prune` i den |
 | `The prune input must be 'true' or 'false'` | configuration | Kun wiki-publicering: sæt `prune` i kaldet til `"true"` eller `"false"` |
 | `The wiki folder ... does not exist` | configuration | Kun wiki-publicering: sæt `wiki_dir` i kaldet til mappen med siderne (standard `docs/wiki`) |
 | `... HTTP 403 ...` ved publicering af wikien | permissions | Kun wiki-publicering: tokenet skal have `write:repository` og skriveadgang til dette repository |
@@ -53,9 +52,7 @@ Kategorien fortæller, hvor du skal kigge. En fejl uden for scriptet (jobbet sta
 
 `WARNING: Gitea returned an invalid push mirror list; GitHub metadata was not synced.` Kørslen lykkes, men intet blev synkroniseret. Kontroller, at Gitea-versionen understøtter push mirror-API'et, og kør igen.
 
-`No wiki/.publish marker in <owner>/<repo>; wiki publishing is not enabled for this repository.` Kørslen af det ældre scoped Publish wiki lykkes og skriver intet. Repositoryet har ikke meldt sig til; kald det genbrugelige workflow **Publish wiki pages** (se [onboarding.md](Onboarding.da)), hvis det skal publicere.
-
-`<n> page(s) are in the wiki but not in <folder>/ and were kept; set the prune input to true to delete them.` Kørslen lykkes. Sider, der kun findes i wikien, lades i fred, medmindre kaldet sætter `prune: "true"` (med det ældre scoped workflow: ordet `prune` i `wiki/.publish`).
+`<n> page(s) are in the wiki but not in <folder>/ and were kept; set the prune input to true to delete them.` Kørslen lykkes. Sider, der kun findes i wikien, lades i fred, medmindre kaldet sætter `prune: "true"`.
 
 ## Runner-problemer
 

docs/wiki/Troubleshooting.md

@@ -33,7 +33,6 @@ never starts, or stops before the step) is a **runner** problem.
 | `Could not determine the Gitea source repository.` | configuration | The run has no repository name; report as a defect |
 | `Expected at most one GitHub push mirror ... found N` | configuration | Keep one GitHub push mirror |
 | `TOKEN_FOR_GITEA_WIKI is missing or empty.` | configuration | Wiki publishing only: the repository calls the workflow but its organization has no such secret, or the call does not pass it; store it and pass it in `secrets:` (see [credentials.md](Credentials)) |
-| `wiki/.publish may only be empty or contain the word 'prune'.` | configuration | Wiki publishing through the older scoped workflow only: leave the marker empty, or put only the word `prune` in it |
 | `The prune input must be 'true' or 'false'` | configuration | Wiki publishing only: set `prune` in the call to `"true"` or `"false"` |
 | `The wiki folder ... does not exist` | configuration | Wiki publishing only: set `wiki_dir` in the call to the folder with the pages (default `docs/wiki`) |
 | `... HTTP 403 ...` while publishing the wiki | permissions | Wiki publishing only: the token needs `write:repository` and write access to this repository |
@@ -60,15 +59,9 @@ settings.
 synced.` The run succeeds but nothing was synced. Check that the Gitea
 version supports the push mirror API and re-run.
 
-`No wiki/.publish marker in <owner>/<repo>; wiki publishing is not enabled for
-this repository.` The older scoped Publish wiki run succeeds and writes
-nothing. The repository has not opted in; call the reusable workflow
-**Publish wiki pages** (see [onboarding.md](Onboarding)) if it should publish.
-
 `<n> page(s) are in the wiki but not in <folder>/ and were kept; set the prune
 input to true to delete them.` The run succeeds. Pages that exist only in the
-wiki are left alone unless the call sets `prune: "true"` (with the older scoped
-workflow: the word `prune` in `wiki/.publish`).
+wiki are left alone unless the call sets `prune: "true"`.
 
 ## Runner problems
 

docs/wiki/Troubleshooting.ms.md

@@ -1,4 +1,4 @@
-<!-- translation of Troubleshooting.md, source sha256 c68827295812 -->
+<!-- translation of Troubleshooting.md, source sha256 cad6363616e8 -->
 
 > Ini ialah terjemahan [`Troubleshooting`](Troubleshooting). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
 
@@ -31,7 +31,6 @@ Kategori menunjukkan di mana perlu dilihat. Kegagalan di luar skrip (kerja tidak
 | `Could not determine the Gitea source repository.` | configuration | Larian tiada nama repositori; laporkan sebagai kecacatan |
 | `Expected at most one GitHub push mirror ... found N` | configuration | Kekalkan satu push mirror GitHub |
 | `TOKEN_FOR_GITEA_WIKI is missing or empty.` | configuration | Penerbitan wiki sahaja: repositori memanggil aliran kerja tetapi organisasinya tiada secret itu, atau panggilan tidak menghantarnya; simpannya dan hantar dalam `secrets:` (lihat [credentials.md](Credentials.ms)) |
-| `wiki/.publish may only be empty or contain the word 'prune'.` | configuration | Penerbitan wiki melalui aliran kerja scoped yang lebih lama sahaja: biarkan penanda kosong, atau letakkan hanya perkataan `prune` di dalamnya |
 | `The prune input must be 'true' or 'false'` | configuration | Penerbitan wiki sahaja: tetapkan `prune` dalam panggilan kepada `"true"` atau `"false"` |
 | `The wiki folder ... does not exist` | configuration | Penerbitan wiki sahaja: tetapkan `wiki_dir` dalam panggilan kepada folder yang mengandungi halaman (lalai `docs/wiki`) |
 | `... HTTP 403 ...` semasa menerbitkan wiki | permissions | Penerbitan wiki sahaja: token memerlukan `write:repository` dan akses tulis kepada repositori ini |
@@ -53,9 +52,7 @@ Kategori menunjukkan di mana perlu dilihat. Kegagalan di luar skrip (kerja tidak
 
 `WARNING: Gitea returned an invalid push mirror list; GitHub metadata was not synced.` Larian berjaya tetapi tiada apa-apa disegerakkan. Semak bahawa versi Gitea menyokong API push mirror dan jalankan semula.
 
-`No wiki/.publish marker in <owner>/<repo>; wiki publishing is not enabled for this repository.` Larian Publish wiki scoped yang lebih lama berjaya dan tidak menulis apa-apa. Repositori belum memilih menyertainya; panggil aliran kerja boleh guna semula **Publish wiki pages** (lihat [onboarding.md](Onboarding.ms)) jika ia sepatutnya menerbitkan.
-
-`<n> page(s) are in the wiki but not in <folder>/ and were kept; set the prune input to true to delete them.` Larian berjaya. Halaman yang hanya ada dalam wiki dibiarkan melainkan panggilan menetapkan `prune: "true"` (dengan aliran kerja scoped yang lebih lama: perkataan `prune` dalam `wiki/.publish`).
+`<n> page(s) are in the wiki but not in <folder>/ and were kept; set the prune input to true to delete them.` Larian berjaya. Halaman yang hanya ada dalam wiki dibiarkan melainkan panggilan menetapkan `prune: "true"`.
 
 ## Masalah runner
 

docs/wiki/Upgrading.da.md

@@ -1,4 +1,4 @@
-<!-- translation of Upgrading.md, source sha256 7fba937279b1 -->
+<!-- translation of Upgrading.md, source sha256 29086c9fa3a7 -->
 
 > Dette er en oversættelse af [`Upgrading`](Upgrading). Den engelske side er autoritativ, og ændringer her bliver overskrevet, næste gang wikien publiceres.
 
@@ -18,9 +18,9 @@ Sådan tager en softwareudvikler en ny udgivelse af de fælles workflows i brug
 
 En udgivelse, der bryder kompatibiliteten, får en ny major-version (`v2`), så en pipeline på `@v1` aldrig modtager den, før du selv ændrer linjen.
 
-Kvalitetskontrol-workflowene (`quality-checks.yml`, `quality-checks-cpp.yml` og `quality-checks-csharp.yml`) henter deres script ved deres input `tools-ref`, som som standard er `v1`. For at fastlåse et helt skal du kalde det ved et præcist tag og sætte `tools-ref` til samme tag; ellers følger scriptet major-tagget.
+Kvalitetskontrol-workflowene (`quality-checks.yml`, `quality-checks-cpp.yml` og `quality-checks-csharp.yml`) og kodemålings-workflowet (`code-metrics.yml`) henter deres scripts ved deres input `tools-ref`, som som standard er det aktuelle major-tag (`v2`). For at fastlåse et helt skal du kalde det ved et præcist tag og sætte `tools-ref` til samme tag; ellers følger scriptet major-tagget.
 
-De to scoped workflows (**Sync GitHub mirror metadata** og **Publish wiki**) leveres af instansen og står ikke i dine `uses:`-linjer; du kan ikke fastlåse dem, men de henter deres scripts ved major-tagget.
+Det scoped workflow **Sync GitHub mirror metadata** leveres af instansen og står ikke i dine `uses:`-linjer; du kan ikke fastlåse det, men det henter sit script ved major-tagget. Publicering af wiki er et genbrugeligt workflow, du kalder (`publish-wiki-pages.yml`); det scoped workflow **Publish wiki** og dets markør `wiki/.publish` blev fjernet i 2.0.0, så et repository, der stadig har markøren, publicerer ikke mere, før det kalder det genbrugelige workflow (se introduktionsguiden).
 
 ## Aflæsning af en changelog-post
 

docs/wiki/Upgrading.md

@@ -23,13 +23,17 @@ A breaking release gets a new major version (`v2`), so a pipeline on `@v1`
 never receives it until you change the line yourself.
 
 The quality-checks workflows (`quality-checks.yml`, `quality-checks-cpp.yml` and
-`quality-checks-csharp.yml`) fetch their script at their input `tools-ref`, which
-defaults to `v1`. To pin one completely, call it at an exact tag and set
+`quality-checks-csharp.yml`) and the code-metrics workflow (`code-metrics.yml`)
+fetch their scripts at their input `tools-ref`, which defaults to the current major tag (`v2`). To pin one completely, call it at an exact tag and set
 `tools-ref` to the same tag; otherwise the script follows the major tag.
 
-The two scoped workflows (**Sync GitHub mirror metadata** and **Publish
-wiki**) are delivered by the instance and are not in your `uses:` lines; you
-cannot pin them, but they fetch their scripts at the major tag.
+The scoped workflow **Sync GitHub mirror metadata** is delivered by the
+instance and is not in your `uses:` lines; you cannot pin it, but it fetches its
+script at the major tag. Wiki publishing is a reusable workflow you call
+(`publish-wiki-pages.yml`); the scoped **Publish wiki** workflow and its
+`wiki/.publish` marker were removed in 2.0.0, so a repository that still has the
+marker no longer publishes until it calls the reusable workflow (see the
+onboarding guide).
 
 ## Reading a changelog entry
 

docs/wiki/Upgrading.ms.md

@@ -1,4 +1,4 @@
-<!-- translation of Upgrading.md, source sha256 7fba937279b1 -->
+<!-- translation of Upgrading.md, source sha256 29086c9fa3a7 -->
 
 > Ini ialah terjemahan [`Upgrading`](Upgrading). Halaman bahasa Inggeris ialah teks yang sah, dan perubahan di sini akan ditimpa pada penerbitan wiki yang seterusnya.
 
@@ -18,9 +18,9 @@ Cara seorang jurutera perisian menerima keluaran baharu aliran kerja bersama den
 
 Keluaran yang memecahkan keserasian mendapat versi major baharu (`v2`), jadi saluran paip pada `@v1` tidak menerimanya sehingga anda sendiri menukar baris itu.
 
-Aliran kerja semakan kualiti (`quality-checks.yml`, `quality-checks-cpp.yml` dan `quality-checks-csharp.yml`) mengambil skripnya pada inputnya `tools-ref`, yang lalai ialah `v1`. Untuk menyematkan satu sepenuhnya, panggil pada tag tepat dan tetapkan `tools-ref` kepada tag yang sama; jika tidak, skrip mengikuti tag major.
+Aliran kerja semakan kualiti (`quality-checks.yml`, `quality-checks-cpp.yml` dan `quality-checks-csharp.yml`) dan aliran kerja metrik kod (`code-metrics.yml`) mengambil skripnya pada inputnya `tools-ref`, yang lalai ialah tag major semasa (`v2`). Untuk menyematkan satu sepenuhnya, panggil pada tag tepat dan tetapkan `tools-ref` kepada tag yang sama; jika tidak, skrip mengikuti tag major.
 
-Dua aliran kerja scoped (**Sync GitHub mirror metadata** dan **Publish wiki**) dihantar oleh instans dan tidak terdapat dalam baris `uses:` anda; anda tidak boleh menyematkannya, tetapi ia mengambil skripnya pada tag major.
+Aliran kerja scoped **Sync GitHub mirror metadata** dihantar oleh instans dan tidak terdapat dalam baris `uses:` anda; anda tidak boleh menyematkannya, tetapi ia mengambil skripnya pada tag major. Penerbitan wiki ialah aliran kerja boleh guna semula yang anda panggil (`publish-wiki-pages.yml`); aliran kerja scoped **Publish wiki** dan penanda `wiki/.publish` telah dibuang dalam 2.0.0, jadi repositori yang masih mempunyai penanda itu tidak lagi menerbitkan sehingga ia memanggil aliran kerja boleh guna semula (lihat panduan permulaan).
 
 ## Membaca satu catatan changelog
 

docs/wiki/_Sidebar.md

@@ -11,6 +11,8 @@
 - [Quality checks (Python, shell)](QualityChecksPythonShell)
 - [Quality checks (C and C++)](QualityChecksCpp)
 - [Quality checks (C#)](QualityChecksCSharp)
+- [Code metrics](CodeMetrics)
+- [English comments](EnglishComments)
 - [Upgrading](Upgrading)
 - [Capabilities](Capabilities)
 
@@ -23,6 +25,8 @@
 - [Kvalitetskontrol (Python, shell)](QualityChecksPythonShell.da)
 - [Kvalitetskontrol (C og C++)](QualityChecksCpp.da)
 - [Kvalitetskontrol (C#)](QualityChecksCSharp.da)
+- [Kodemålinger](CodeMetrics.da)
+- [Engelske kommentarer](EnglishComments.da)
 - [Opgradering](Upgrading.da)
 - [Kapabiliteter](Capabilities.da)
 
@@ -35,5 +39,7 @@
 - [Semakan kualiti (Python, shell)](QualityChecksPythonShell.ms)
 - [Semakan kualiti (C dan C++)](QualityChecksCpp.ms)
 - [Semakan kualiti (C#)](QualityChecksCSharp.ms)
+- [Metrik kod](CodeMetrics.ms)
+- [Komen dalam bahasa Inggeris](EnglishComments.ms)
 - [Menaik taraf](Upgrading.ms)
 - [Keupayaan](Capabilities.ms)

guides/code-metrics.md

@@ -0,0 +1,117 @@
+# Showing code metrics and coverage badges
+
+How a software engineer calls the shared code-metrics workflow and shows its
+three badges (code files, lines of code and coverage) in a README. The workflow
+counts the code of the repository, reads a coverage report that the caller
+supplies and commits three SVG files to a `badges` branch. It runs no test and
+needs no secret. Its contract is ADR-0010 in this repository.
+
+## Calling the workflow
+
+The workflow cannot see the files of your test job, so the tests run in a job of
+your own, upload the Cobertura XML report as an artifact, and the metrics job
+runs after it:
+
+```yaml
+name: Code metrics
+
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4.2.2
+      - run: python3 -m pip install pytest pytest-cov && python3 -m pytest --cov --cov-report=xml
+      - uses: actions/upload-artifact@v4.6.2
+        with:
+          name: coverage
+          path: coverage.xml
+
+  metrics:
+    needs: tests
+    permissions:
+      contents: write
+    uses: TirSystem/github-action/.gitea/workflows/code-metrics.yml@v2
+    with:
+      coverage-artifact: coverage
+      coverage-report: coverage.xml
+```
+
+| Input | Default | Meaning |
+| --- | --- | --- |
+| `working-directory` | `.` | Directory, relative to the repository root, whose code is counted |
+| `exclude` | empty | Comma list of patterns of files and directories that are not counted, in addition to the defaults; a pattern without `/` matches a name anywhere, a pattern with `/` matches the path below `working-directory` |
+| `coverage-report` | empty | Cobertura XML report: the file inside the artifact when `coverage-artifact` is set, otherwise a path in the repository; empty writes no coverage badge |
+| `coverage-artifact` | empty | Name of an artifact, uploaded by an earlier job of the same run, that holds the report |
+| `coverage-warn` | `60` | Coverage in percent below which the badge is red |
+| `coverage-good` | `80` | Coverage in percent from which the badge is green; in between it is yellow |
+| `badges-branch` | `badges` | Branch that holds the badge files; it is created when it does not exist |
+| `tools-ref` | `v2` | Tag or branch of `TirSystem/github-action` from which the scripts in `tools/` are fetched |
+
+Reference the workflow at the major tag (`@v2`) or at an exact tag, never at
+`main`. A call at an exact tag is pinned completely only when `tools-ref` names
+the same tag. See the upgrade guide. Start the workflow on pushes to your
+default branch only: the badge commit carries `[skip ci]` and is made with the
+token of the run, which does not start another run, but a trigger on every
+branch would write one commit per branch.
+
+## What is counted
+
+- A code file is a text file with the extension of a supported language:
+  Python, shell, PowerShell, C, C++, C#, Java, JavaScript, TypeScript, Go, Rust
+  and SQL. Markdown, YAML, JSON, XML, HTML and CSS are not code files.
+- Every line is exactly one of blank (only white space), comment (only comment
+  text) or code (everything else, including a line with code and a trailing
+  comment). The badge shows the lines of code only.
+- A comment marker inside a string is not a comment, and a Python docstring is a
+  string, so it counts as code.
+- Directories that start with a dot and `node_modules`, `vendor`, `third_party`,
+  `dist`, `build`, `out`, `bin`, `obj`, `target`, `venv`, `__pycache__` and
+  `shared-scripts` are not counted. Generated code is excluded with `exclude`.
+- Raw and verbatim strings that differ from an ordinary string (Rust `r#"..."#`,
+  C# `@"..."`, C++ raw strings) can be counted wrongly. The counts will differ
+  a little from other tools; the rules are the same on every run.
+
+## The coverage badge
+
+The report is a Cobertura XML file, which `coverage.py` (`coverage xml`),
+`gcovr` (`--cobertura`) and `coverlet` (`cobertura` format) write. The badge
+shows `lines-covered` over `lines-valid`, rounded to a whole percent, and its
+colour follows the two thresholds. A report that does not exist, is not
+well-formed Cobertura XML or has no valid lines fails the run with the file
+named; the coverage badge is never written as `0%` for a bad report. Without
+`coverage-report` the run passes with a notice and no coverage badge.
+
+## Showing the badges
+
+Add the images to the README with the raw URLs of the branch:
+
+```markdown
+![code files](https://git.tirsystem.com/OWNER/REPO/raw/branch/badges/code-files.svg)
+![lines of code](https://git.tirsystem.com/OWNER/REPO/raw/branch/badges/code-lines.svg)
+![coverage](https://git.tirsystem.com/OWNER/REPO/raw/branch/badges/coverage.svg)
+```
+
+On the GitHub mirror use `https://raw.githubusercontent.com/OWNER/REPO/badges/code-files.svg`;
+the push mirror copies the branch. The `badges` branch also holds
+`code-metrics.json` with the numbers per language. The instance caches a raw
+file for up to six hours, so a changed badge can show the old number for a
+while there; the mirror caches for five minutes. A private repository does not
+show the badges to a reader who is not signed in.
+
+## When the workflow fails
+
+| Message | Cause | Fix |
+| --- | --- | --- |
+| `[configuration] working-directory must be a relative path inside the repository.` | An absolute path or `..` | Use a path inside the repository |
+| `[configuration] coverage-report '<x>' does not exist.` | The report was not produced, or the artifact name or path is wrong | Check the test job and the artifact name; the path is inside the artifact |
+| `[configuration] coverage-report '<x>' is not well-formed XML` or `is not a Cobertura report` | The file is another format | Write Cobertura XML (`coverage xml`, `gcovr --cobertura`) |
+| `[configuration] coverage-report '<x>' has no valid lines.` | The tests ran no measured code | Check the coverage configuration |
+| `[configuration] coverage-artifact '<x>' needs coverage-report` | The artifact is named but not the file in it | Set `coverage-report` |
+| `[configuration] coverage-warn ... is above coverage-good` or `is not a number from 0 to 100` | A threshold is invalid | Correct the input |
+| `[configuration] badges-branch '<x>' must not be a default branch` or `holds files that are not badge files` | The branch name is `main`, `master` or a branch with other content | Use a branch that holds only the badges |
+| `the push to '<x>' failed twice` | Another run wrote the branch at the same time, or the token cannot write | Re-run; check that the job has `contents: write` |
+| The download step fails | The artifact does not exist in this run, or the job does not run after the test job | Add `needs:` and check the artifact name |

guides/english-comments.md

@@ -0,0 +1,100 @@
+# Keeping source code comments in English
+
+How a software engineer calls the shared workflow that checks that the comments
+and docstrings of a pull request are written in English. The workflow fails the
+run when one is not, and writes one comment on the pull request that mentions
+the author. It changes no file and sends no source text outside the instance.
+Its decision is ADR-0012 in this repository.
+
+## Calling the workflow
+
+```yaml
+name: English comments
+
+on:
+  pull_request:
+
+jobs:
+  english-comments:
+    uses: TirSystem/github-action/.gitea/workflows/english-comments.yml@v2
+    with:
+      exclude: "docs/generated/**"
+      allowed-words-file: .english-comments-allowed-words
+```
+
+| Input | Default | Meaning |
+| --- | --- | --- |
+| `scope` | `changed` | `changed` checks the comments on the lines the pull request adds; `all` checks every tracked file |
+| `exclude` | | Comma list of file name or path patterns that are not checked (`*` and `**` are wildcards) |
+| `allowed-words-file` | | A file of the repository with words that are never judged, one per line, `#` starts a comment |
+| `threshold` | `0.6` | The probability, above 0 and at most 1, from which a comment counts as not English |
+| `min-words` | `3` | A comment with fewer words is not judged |
+| `langid-version`, `numpy-version` | `1.1.6`, `2.1.3` | The pinned packages the detector needs |
+| `tools-ref` | the current major | The tag of this repository whose scripts are run; pin it together with the workflow |
+
+The optional secret `REPORT_TOKEN` is a Gitea token that may comment on pull
+requests. Without it the workflow uses the token of the run, so the comment is
+written by the Actions bot. A pull request from a fork has a read-only token:
+the check still fails the run, but no comment is written.
+
+## What is checked
+
+The comments and docstrings of the files of the languages in the code counter
+([code metrics](code-metrics.md)): Python, shell, PowerShell, C, C++, C#, Java,
+JavaScript, TypeScript, Go, Rust and SQL. Strings and code are not read.
+Consecutive comment lines form a block. Each line of a block is judged on its own
+(at least four words and a probability of at least 0.7), so an English line cannot
+hide a Danish one next to it; when no line is flagged, the block is judged as a whole
+(at least `min-words` words and `threshold`), so a sentence cut over short lines is not missed.
+
+Before a block is judged, everything that is not a word is removed: paths, URLs,
+options (`--output`), file names, identifiers (`snake_case`, `camelCase`),
+numbers, acronyms and constants (`JSON`), a leading label such as `Usage:`, and
+the words of the allowed-words file. A block with fewer than `min-words` words
+left is not judged, so a short comment passes. Comments that configure a tool
+(`noqa`, `type:`, `pragma`, `shellcheck`) are not read.
+
+## When the check fails
+
+The run fails, each finding is shown as an annotation (`::error file=...,line=...`)
+and in the log as `file:line: looks Danish (0.93): "the comment"`, and one comment
+on the pull request lists them and mentions the author. A new run updates that
+comment; when the pull request passes, the comment is marked resolved and no
+longer mentions anyone.
+
+Fix it by rewriting the comment in English. For a quotation or a name that is
+not English, either put `english-comments: ignore` in the comment (it skips the
+whole comment block it is in), or add the word to the allowed-words file.
+
+## Blocking the merge
+
+A failing run does not block a merge by itself. In the branch protection of the
+target branch, mark the check as required: run the workflow once on a pull
+request and choose its entry in the list of status checks (the exact name is
+made from the calling workflow, its job and the event). Setting branch
+protection is the repository owner's action; the workflow does not change it.
+
+## How accurate it is
+
+The detector is `langid`, limited to English, Danish, Norwegian, Swedish,
+German, French, Malay, Indonesian and Dutch. On the corpus of the repository it
+flags none of 300 English comments, 44 of 45 Danish and 41 of 45 Malay comments
+and all of the 48 German, Swedish, Norwegian and French ones (ADR-0012). Its
+limits:
+
+- a comment of one or two words, or one that is mostly names, is not judged;
+- a comment in poor English passes, and a comment that mixes English technical
+  terms with few Danish or Malay words can pass;
+- the Danish and Malay comments of the corpus were written for the test, not
+  collected from real code, so real code will show other misses. Report a miss
+  or a false positive with the comment, and it joins the corpus.
+
+## Troubleshooting
+
+| Message | Cause |
+| --- | --- |
+| `[configuration] give --base` | The workflow was started by an event that is not a pull request with `scope: changed`; call it on `pull_request` or use `scope: all` |
+| `[configuration] git diff failed` | The base branch is not in the checkout; the workflow fetches the full history, so check that the pull request has a target branch |
+| `[configuration] langid is not installed` | The install step failed; check the pinned versions |
+| `[permissions] ... may not comment on pull requests` | The token cannot comment; give `REPORT_TOKEN` write access to issues and pull requests |
+| A finding that is not a finding | Add the words to the allowed-words file, or `english-comments: ignore` to the comment |

guides/onboarding.md

@@ -79,10 +79,6 @@ The wiki has English and the product owner's language as a minimum.
 5. Merge the change to `main`. The log must end with `Published <n> page(s) to
    the wiki of <owner>/<repo>`.
 
-A repository that still has the marker `wiki/.publish` is published by the
-older scoped workflow, which is removed once every repository has a call.
-Move the pages to `docs/wiki/` and add the call before that.
-
 ## Runners
 
 | Item | Value |

guides/quality-checks-cpp.md

@@ -31,7 +31,7 @@ jobs:
 | `compile-commands-dir` | empty | Directory, relative to the repository root, with a `compile_commands.json` that your pipeline built before the call; when set, clang-tidy uses it and ignores `std` |
 | `clang-format-version` | `23.1.3` | Exact version of the clang-format package |
 | `clang-tidy-version` | `22.1.8` | Exact version of the clang-tidy package |
-| `tools-ref` | `v1` | Tag or branch of `TirSystem/github-action` from which the script `tools/quality-checks-cpp.sh` is fetched |
+| `tools-ref` | `v2` | Tag or branch of `TirSystem/github-action` from which the script `tools/quality-checks-cpp.sh` is fetched |
 
 Reference the workflow at the major tag (`@v1`) or at an exact tag, never at
 `main`. A call at an exact tag is pinned completely only when `tools-ref` names

guides/quality-checks-csharp.md

@@ -30,7 +30,7 @@ jobs:
 | `working-directory` | `.` | Directory, relative to the repository root, whose files are checked |
 | `project` | empty | Solution or project file, relative to `working-directory`; empty uses the single `*.sln` or `*.slnx`, else the single `*.csproj`, that is tracked there |
 | `dotnet-sdk-version` | `10.0.401` | Exact version of the .NET SDK, 10 or later; a channel such as `10.0`, a range and a version below 10 are refused |
-| `tools-ref` | `v1` | Tag or branch of `TirSystem/github-action` from which the script `tools/quality-checks-csharp.sh` is fetched |
+| `tools-ref` | `v2` | Tag or branch of `TirSystem/github-action` from which the script `tools/quality-checks-csharp.sh` is fetched |
 
 Reference the workflow at the major tag (`@v1`) or at an exact tag, never at
 `main`. A call at an exact tag is pinned completely only when `tools-ref` names

guides/quality-checks.md

@@ -32,7 +32,7 @@ jobs:
 | `mypy-version` | `1.11.2` | Version of mypy |
 | `shellcheck-py-version` | `0.10.0.1` | Version of the shellcheck-py package (ShellCheck 0.10.0) |
 | `shfmt-py-version` | `3.11.0.2` | Version of the shfmt-py package (shfmt 3.11.0) |
-| `tools-ref` | `v1` | Tag or branch of `TirSystem/github-action` from which the script `tools/quality-checks.sh` is fetched |
+| `tools-ref` | `v2` | Tag or branch of `TirSystem/github-action` from which the script `tools/quality-checks.sh` is fetched |
 
 Reference the workflow at the major tag (`@v1`) or at an exact tag
 (`@v1.0.0`), never at `main` and never at the branch of a pull request: that

guides/troubleshooting.md

@@ -27,7 +27,6 @@ never starts, or stops before the step) is a **runner** problem.
 | `Could not determine the Gitea source repository.` | configuration | The run has no repository name; report as a defect |
 | `Expected at most one GitHub push mirror ... found N` | configuration | Keep one GitHub push mirror |
 | `TOKEN_FOR_GITEA_WIKI is missing or empty.` | configuration | Wiki publishing only: the repository calls the workflow but its organization has no such secret, or the call does not pass it; store it and pass it in `secrets:` (see [credentials.md](credentials.md)) |
-| `wiki/.publish may only be empty or contain the word 'prune'.` | configuration | Wiki publishing through the older scoped workflow only: leave the marker empty, or put only the word `prune` in it |
 | `The prune input must be 'true' or 'false'` | configuration | Wiki publishing only: set `prune` in the call to `"true"` or `"false"` |
 | `The wiki folder ... does not exist` | configuration | Wiki publishing only: set `wiki_dir` in the call to the folder with the pages (default `docs/wiki`) |
 | `... HTTP 403 ...` while publishing the wiki | permissions | Wiki publishing only: the token needs `write:repository` and write access to this repository |
@@ -54,15 +53,9 @@ settings.
 synced.` The run succeeds but nothing was synced. Check that the Gitea
 version supports the push mirror API and re-run.
 
-`No wiki/.publish marker in <owner>/<repo>; wiki publishing is not enabled for
-this repository.` The older scoped Publish wiki run succeeds and writes
-nothing. The repository has not opted in; call the reusable workflow
-**Publish wiki pages** (see [onboarding.md](onboarding.md)) if it should publish.
-
 `<n> page(s) are in the wiki but not in <folder>/ and were kept; set the prune
 input to true to delete them.` The run succeeds. Pages that exist only in the
-wiki are left alone unless the call sets `prune: "true"` (with the older scoped
-workflow: the word `prune` in `wiki/.publish`).
+wiki are left alone unless the call sets `prune: "true"`.
 
 ## Runner problems
 

guides/upgrading.md

@@ -17,13 +17,17 @@ A breaking release gets a new major version (`v2`), so a pipeline on `@v1`
 never receives it until you change the line yourself.
 
 The quality-checks workflows (`quality-checks.yml`, `quality-checks-cpp.yml` and
-`quality-checks-csharp.yml`) fetch their script at their input `tools-ref`, which
-defaults to `v1`. To pin one completely, call it at an exact tag and set
+`quality-checks-csharp.yml`) and the code-metrics workflow (`code-metrics.yml`)
+fetch their scripts at their input `tools-ref`, which defaults to the current major tag (`v2`). To pin one completely, call it at an exact tag and set
 `tools-ref` to the same tag; otherwise the script follows the major tag.
 
-The two scoped workflows (**Sync GitHub mirror metadata** and **Publish
-wiki**) are delivered by the instance and are not in your `uses:` lines; you
-cannot pin them, but they fetch their scripts at the major tag.
+The scoped workflow **Sync GitHub mirror metadata** is delivered by the
+instance and is not in your `uses:` lines; you cannot pin it, but it fetches its
+script at the major tag. Wiki publishing is a reusable workflow you call
+(`publish-wiki-pages.yml`); the scoped **Publish wiki** workflow and its
+`wiki/.publish` marker were removed in 2.0.0, so a repository that still has the
+marker no longer publishes until it calls the reusable workflow (see the
+onboarding guide).
 
 ## Reading a changelog entry
 

guides/vpn-tailscale.md

@@ -0,0 +1,132 @@
+# Reaching a tailnet with Tailscale
+
+The composite action `actions/connect-tailscale` joins a Tailscale network from
+a Gitea Actions runner, so the next steps of the same job (a deployment over
+SSH, a migration) can reach hosts on the tailnet. It does what the GitHub
+marketplace action `tailscale/github-action` does, written for Gitea Actions:
+that action is built for GitHub and has not been verified on Gitea. It is
+**experimental**: it is released in 2.2.0, and it has not yet run on a
+runner with a real tailnet (MIL-012). For a plain tunnel without a third-party service, see
+[WireGuard](vpn-wireguard.md).
+
+A node belongs to one job: every job that deploys joins on its own and logs out
+in a last step. It cannot be a reusable workflow, because a called workflow runs
+as a separate job.
+
+## Use it
+
+```yaml
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4.2.2
+
+      - name: Connect Tailscale
+        uses: TirSystem/github-action/actions/connect-tailscale@v2
+        with:
+          oauth-secret: ${{ secrets.TS_OAUTH_SECRET }}
+          tags: tag:ci
+          version: 1.80.2
+          health-check-host: deploy-host
+
+      - name: Deploy
+        run: ssh deploy@deploy-host ./deploy.sh
+
+      - name: Disconnect Tailscale
+        if: always()
+        uses: TirSystem/github-action/actions/connect-tailscale@v2
+        with:
+          action: down
+```
+
+If the short form does not resolve on your instance (Gitea looks for the action
+on the host set in `DEFAULT_ACTIONS_URL`), use the full address:
+`https://git.tirsystem.com/TirSystem/github-action/actions/connect-tailscale@v2`.
+
+## Inputs
+
+| Input | Default | Meaning |
+| --- | --- | --- |
+| `action` | `up` | `up` or `down` |
+| `authkey` | | A Tailscale auth key, as a secret. Give this or `oauth-secret` |
+| `oauth-secret` | | The secret of an OAuth client with the scope `auth_keys`, as a secret. Needs `tags` |
+| `tags` | | ACL tags of the node, `tag:ci` or `tag:ci,tag:deploy`. Required with `oauth-secret` |
+| `hostname` | runner name | Name of the node in the tailnet |
+| `version` | | The exact version to install when the runner has no `tailscale`, for example `1.80.2`. Empty uses the installed one and fails when there is none |
+| `sha256` | | The SHA-256 of the downloaded archive `tailscale_<version>_<arch>.tgz`; the install fails when it differs. Recommended |
+| `userspace-networking` | `false` | `true` runs without a TUN device |
+| `args` | | Extra flags for `tailscale up`, for example `--accept-routes`. Never a secret |
+| `timeout` | `60` | Seconds to wait for the node |
+| `health-check-host` | | A tailnet host that must answer a Tailscale ping |
+
+## Set it up
+
+1. In the Tailscale admin console define a tag for CI (`tag:ci`) in the policy
+   file, with the owners that may use it, and an access rule that lets
+   `tag:ci` reach only the hosts and ports the deployment needs.
+2. Create either an **OAuth client** with the scope `auth_keys` (write) for that
+   tag, or an **auth key** that is reusable only when needed, ephemeral,
+   pre-authorized and tagged. The OAuth client is preferred: it does not expire
+   the way a key does, and each run gets a fresh ephemeral key.
+3. Store the secret as a secret of the organization, with a name that does not
+   start with `GITEA_` or `GITHUB_`.
+4. Rotate the secret when a person with access leaves.
+
+The state of the node is kept in memory. With an OAuth client the key is
+ephemeral, so the node disappears from the tailnet when the job ends, even if
+the last step does not run. With an auth key that is not ephemeral, a cancelled
+job can leave the node in the tailnet until `down` runs or it is removed in the
+admin console: create the key as ephemeral.
+
+## The runner
+
+- The job runs as root, or `sudo` is available (the action uses `sudo` only
+  when the job is not root). The action downloads the Tailscale binaries from
+  `pkgs.tailscale.com` when `tailscale` is not on the runner; `version` is then
+  required, and `sha256` makes the install check the archive. A runner image
+  that already contains Tailscale skips the download.
+- The action starts its own `tailscaled`. It refuses to run when a `tailscaled`
+  already answers on the runner, because that daemon belongs to the host and
+  `down` would log it out: use the action on job containers, not on a runner
+  that runs jobs directly on a host with its own Tailscale.
+- **TUN mode** (the default) needs the capability `NET_ADMIN` and the device
+  `/dev/net/tun` in the runner container: in the `act_runner` configuration set
+  under `container:` `options: "--cap-add=NET_ADMIN --device=/dev/net/tun"`.
+- **Userspace mode** (`userspace-networking: true`) needs neither, but the
+  tailnet is then reached only through a SOCKS5 proxy on `localhost:1055`:
+
+  ```bash
+  ssh -o ProxyCommand="nc -X 5 -x localhost:1055 %h %p" deploy@deploy-host
+  ```
+
+  Tools that cannot use a proxy do not work in this mode.
+- Use a dedicated runner with a label of its own (for example `vpn`) for jobs
+  that join a tailnet.
+- The daemon is started in the background of the "Run the Tailscale step". That
+  it stays alive for the following steps of the job has to be confirmed on the
+  runner in use; the first trial must do so.
+
+## What the action does
+
+- masks the secrets in the log first;
+- passes the auth key to `tailscale up` in a file of mode 600 (`--auth-key=file:`),
+  never on a command line, and deletes the file at once;
+- prints errors as `::error::[category] message`, with the categories
+  `configuration`, `environment` and `connection`;
+- waits until `tailscaled` answers before `tailscale up` (up to 30 seconds);
+- on `down` logs the node out, stops `tailscaled` and deletes its work folder,
+  and only when this action started that daemon.
+
+The `file:` form of `--auth-key` needs a recent Tailscale; with an old pinned
+version `tailscale up` reports an invalid key.
+
+## Troubleshooting
+
+| Message | Cause |
+| --- | --- |
+| `[configuration] give authkey or oauth-secret` | Neither was given, or both |
+| `[configuration] tags is required` | `oauth-secret` without `tags` |
+| `[environment] could not download` | The runner cannot reach `pkgs.tailscale.com`, or the version does not exist |
+| `[connection] tailscale up failed` | A wrong or expired key, a tag the client may not use, or a missing TUN device (try `userspace-networking`); the last lines of `tailscaled` follow |
+| `[connection] health-check-host ... does not answer` | The access rule does not let `tag:ci` reach the host |