@plainconceptsplatform/workflows 1.20.2 → 1.21.0

package/loops/actions/land-pull-request/land-pull-request.sh

@@ -34,6 +34,12 @@ if [ "$current" != "$HEAD_SHA" ]; then
   out ""
   exit 0
 fi
+reason=$(bash "$(dirname "${BASH_SOURCE[0]}")/side-checks.sh" "$REPO" "$HEAD_SHA")
+if [ -n "$reason" ]; then
+  echo "::warning::Not landing #$PR: $reason."
+  out ""
+  exit 0
+fi
 base=$(jq -r .baseRefName <<<"$pr_json")
 head_ref=$(jq -r .headRefName <<<"$pr_json")
 

package/loops/actions/land-pull-request/side-checks.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Managed by @plainconceptsplatform/workflows. Source: loops/actions/land-pull-request/side-checks.sh. Update with workflows update --force; consumer edits may be overwritten.
+#
+# Prints why a commit may not land yet, or nothing when it may. A side workflow
+# (SIDE_CHECK_WORKFLOWS, comma-separated, default "Agentics checks") runs only when its paths change,
+# so no ruleset can require it, and the CI verdict the train and the gate read leaves it out: a
+# release once merged into three apps with its workflow lint red. A side workflow that did not run
+# on the commit is no objection; one that is running, failed or cannot be read is.
+# Usage: side-checks.sh <owner/repo> <sha>
+set -euo pipefail
+repo="$1"
+sha="$2"
+IFS=',' read -ra names <<<"${SIDE_CHECK_WORKFLOWS-Agentics checks}"
+[ "${#names[@]}" -gt 0 ] || exit 0
+
+if ! runs=$(gh api "repos/$repo/actions/runs?head_sha=$sha&per_page=100" --jq '.workflow_runs' 2>/dev/null); then
+  echo "the workflow runs on ${sha:0:7} could not be read"
+  exit 0
+fi
+
+for name in "${names[@]}"; do
+  name=$(sed -E 's/^ +| +$//g' <<<"$name")
+  [ -n "$name" ] || continue
+  latest=$(jq -r --arg n "$name" '[.[] | select(.name == $n)] | sort_by(.created_at) | last // empty | "\(.status) \(.conclusion // "")"' <<<"$runs")
+  [ -n "$latest" ] || continue
+  status=${latest%% *}
+  conclusion=${latest#* }
+  if [ "$status" != completed ]; then
+    echo "$name is still running on ${sha:0:7}"
+    exit 0
+  fi
+  case "$conclusion" in
+    success | skipped | neutral) ;;
+    *) echo "$name ended ${conclusion:-without a conclusion} on ${sha:0:7}"; exit 0 ;;
+  esac
+done

package/loops/actions/merge-agent-pr/action.yml

@@ -34,6 +34,12 @@ runs:
 
           HEAD_REF=$(gh pr view "$PR_NUM" --repo "$REPO" --json headRefName --jq '.headRefName')
 
+          reason=$(bash ./.github/actions/land-pull-request/side-checks.sh "$REPO" "$HEAD_SHA")
+          if [ -n "$reason" ]; then
+            echo "::warning::Not merging #$PR_NUM: $reason."
+            continue
+          fi
+
           gh pr merge "$PR_NUM" --repo "$REPO" --squash --match-head-commit "$HEAD_SHA"
 
           # Delete the branch, because nothing else ever has: four repositories had accumulated

package/loops/actions/merge-train/merge-train.sh

@@ -520,6 +520,17 @@ for line in "${candidates[@]}"; do
     [ $((now_epoch - $(iso_epoch "$ci_created"))) -lt $((STUCK_HOURS * 3600)) ] || ci_stuck=true
   fi
 
+  # A green CI run is not the whole verdict: a side workflow (Agentics checks) on the same head may be
+  # red or still running, and the gate could then never land it. Held until that changes.
+  if [ "$ci_status" = completed ] && [ "$ci_conclusion" = success ] && [ "$park" = none ]; then
+    side=$(bash "$(dirname "${BASH_SOURCE[0]}")/../land-pull-request/side-checks.sh" "$REPO" "$head_sha")
+    if [ -n "$side" ]; then
+      echo "#$pr ($author): hold, $side."
+      summary "| #$pr | $author | hold | $side |"
+      continue
+    fi
+  fi
+
   mergeable=UNKNOWN
   behind_by=0
   if [ "$park" = none ] && [ "$hold" != true ] && [ "$review_decision" != CHANGES_REQUESTED ]; then

package/loops/actions/verify-route-matrix/verify-route-matrix.sh

@@ -3708,6 +3708,31 @@ if [ -f "$RTP_YML" ] && worker_installed release; then
   if [ "$RTP_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
 fi
 
+echo "── Required checks and side workflows ────────────────────────────────────"
+
+# The main ruleset requires one check, Full CI, so Full CI must need every blocking job, and the
+# side workflows no ruleset can require (Agentics checks runs only on its paths) must be checked
+# by both merge points and held by the train. Dropping any one of these lets a red job merge.
+RC_OK=1
+rc() { grep -qE "$1" "$2" || { RC_OK=0; echo "FAIL: required checks: $3" >&2; }; }
+CI_DOTNET="${HERE}/../../templates/ci/app-ci-dotnet-next.yml"
+CI_NODE="${HERE}/../../templates/ci/app-ci-node-monorepo.yml"
+RULESET="${HERE}/../../templates/rulesets/main-required-checks.json"
+for job in sast-scan secret-scan deps-and-iac-scan platform-conformance engineering-excellence api web; do
+  awk '/^  full-ci:$/{f=1} f&&/needs:/{print; exit}' "$CI_DOTNET" | grep -qE "[[ ]${job}[],]" || { RC_OK=0; echo "FAIL: required checks: the .NET template's Full CI does not need ${job}" >&2; }
+done
+for job in lint sast-scan secret-scan deps-and-iac-scan web; do
+  awk '/^  full-ci:$/{f=1} f&&/needs:/{print; exit}' "$CI_NODE" | grep -qE "[[ ]${job}[],]" || { RC_OK=0; echo "FAIL: required checks: the node template's Full CI does not need ${job}" >&2; }
+done
+rc '"context": "Full CI"' "$RULESET" 'the ruleset must require Full CI'
+rc '"include": \["~DEFAULT_BRANCH"\]' "$RULESET" 'the ruleset must target the default branch'
+rc 'side-checks\.sh' "${HERE}/../land-pull-request/land-pull-request.sh" 'land-pull-request must check the side workflows'
+rc 'side-checks\.sh' "${HERE}/../merge-agent-pr/action.yml" 'merge-agent-pr must check the side workflows'
+rc 'land-pull-request/side-checks\.sh' "${HERE}/../merge-train/merge-train.sh" 'the merge train must hold a pull request whose side workflow is red'
+rc 'test-timings\.mjs' "$CI_DOTNET" 'the .NET template must summarise the test timings'
+[ "$(grep -c -- '--logger trx' "$CI_DOTNET")" -ge 5 ] || { RC_OK=0; echo "FAIL: required checks: every .NET test step must write a trx report" >&2; }
+if [ "$RC_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
+
 echo "── App error privacy ─────────────────────────────────────────────────────"
 
 # The application error report files into the private repository rather than out of it, so

package/loops/templates/ci/app-ci-dotnet-next.yml

@@ -214,19 +214,19 @@ jobs:
       - name: Unit tests + coverage
         if: env.UNIT_TEST_PROJECT != ''
         run: dotnet test "$UNIT_TEST_PROJECT" --no-build -c Release
-          --collect:"XPlat Code Coverage" --settings "$COVERAGE_SETTINGS" --results-directory TestResults
+          --collect:"XPlat Code Coverage" --settings "$COVERAGE_SETTINGS" --results-directory TestResults --logger trx
       - name: Parity tests
         if: env.PARITY_TEST_PROJECT != ''
-        run: dotnet test "$PARITY_TEST_PROJECT" --no-build -c Release
+        run: dotnet test "$PARITY_TEST_PROJECT" --no-build -c Release --results-directory TestResults --logger trx
       - name: Architecture tests
         if: env.ARCHITECTURE_TEST_PROJECT != ''
-        run: dotnet test "$ARCHITECTURE_TEST_PROJECT" --no-build -c Release
+        run: dotnet test "$ARCHITECTURE_TEST_PROJECT" --no-build -c Release --results-directory TestResults --logger trx
       # Executable OpenSpec scenarios (Reqnroll). Each scenario is bound to a spec scenario by tag
       # and fails if that scenario disappears from openspec/.
       - name: Acceptance tests (Reqnroll) + coverage
         if: env.ACCEPTANCE_TEST_PROJECT != ''
         run: dotnet test "$ACCEPTANCE_TEST_PROJECT" --no-build -c Release
-          --collect:"XPlat Code Coverage" --settings "$COVERAGE_SETTINGS" --results-directory TestResults
+          --collect:"XPlat Code Coverage" --settings "$COVERAGE_SETTINGS" --results-directory TestResults --logger trx
       # APP_SQL_SERVER is the connection string without a database; each later step names its own.
       - name: Create test databases
         env:
@@ -259,11 +259,16 @@ jobs:
           export "$INTEGRATION_CONNECTION_ENV=$APP_SQL_SERVER;Database=$PRIMARY_DATABASE"
           for pair in $EXTRA_DATABASES; do export "${pair%%=*}=$APP_SQL_SERVER;Database=${pair#*=}"; done
           dotnet test "$INTEGRATION_TEST_PROJECT" --no-build -c Release \
-            --collect:"XPlat Code Coverage" --settings "$COVERAGE_SETTINGS" --results-directory TestResults
+            --collect:"XPlat Code Coverage" --settings "$COVERAGE_SETTINGS" --results-directory TestResults --logger trx
       # The coverage step runs a small node script; fresh runner VMs ship no node.
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: ${{ env.NODE_VERSION }}
+      # Where the run's time went, by test class: a class is what xUnit runs in parallel and where a
+      # fixture's setup is paid, so a slow class shows up the day it is added. Never fails the job.
+      - name: Test timings
+        if: ${{ !cancelled() }}
+        run: node "$GITHUB_WORKSPACE/scripts/test-timings.mjs" TestResults >> "$GITHUB_STEP_SUMMARY" || true
       # pipefail: without it the step reports tee's status and passes however low coverage is.
       - name: Coverage floor (merged)
         run: |
@@ -854,20 +859,22 @@ jobs:
           retention-days: 90
 
   # The merge train reads this job by its name to tell a full run from a light one: do not rename it.
+  # It is also the check the main ruleset requires (loops/templates/rulesets), so it needs every
+  # blocking job, the scans as well as the heavy ones: a red scan must stop a merge too.
   full-ci:
     name: Full CI
-    needs: [depth, api, web, e2e, engineering-excellence]
+    needs: [depth, api, web, e2e, engineering-excellence, markdown, repo-checks, platform-conformance, secret-scan, deps-and-iac-scan, sast-scan]
     if: ${{ always() && needs.depth.outputs.full == 'true' }}
     runs-on: ${{ vars.CI_RUNNER || 'agents-arc' }}
     timeout-minutes: 5
     steps:
-      - name: Every heavy job passed
+      - name: Every blocking job passed
         env:
           RESULTS: ${{ join(needs.*.result, ' ') }}
         run: |
           for result in $RESULTS; do
             case "$result" in
-              failure | cancelled | timed_out) echo "A heavy job ended $result."; exit 1 ;;
+              failure | cancelled | timed_out) echo "A blocking job ended $result."; exit 1 ;;
             esac
           done
           echo "Full CI passed."

package/loops/templates/ci/app-ci-node-monorepo.yml

@@ -209,21 +209,22 @@ jobs:
           # Same guard as above: a tag release needs contents: write, which this job lacks.
           upload-release-assets: false
 
-  # The merge queue requires this check. On a pull request with MERGE_QUEUE on, the heavy jobs are
+  # The merge queue and the main ruleset (loops/templates/rulesets) require this check, so it needs
+  # every blocking job, the scans too. On a pull request with MERGE_QUEUE on, the heavy jobs are
   # skipped and the full CI runs on the merge group instead; skipped counts as passed.
   full-ci:
     name: Full CI
-    needs: [web, e2e, desktop, mobile]
+    needs: [lint, web, e2e, desktop, mobile, secret-scan, deps-and-iac-scan, sast-scan]
     if: always()
     runs-on: agents-arc
     timeout-minutes: 5
     steps:
-      - name: Every heavy job passed
+      - name: Every blocking job passed
         env:
           RESULTS: ${{ join(needs.*.result, ' ') }}
         run: |
           for result in $RESULTS; do
-            case "$result" in failure | cancelled | timed_out) echo "A heavy job ended $result."; exit 1 ;; esac
+            case "$result" in failure | cancelled | timed_out) echo "A blocking job ended $result."; exit 1 ;; esac
           done
 
   # Hands this run's verdict to the router's merge train, which decides whether this pull request

package/loops/templates/quality-gates/scripts/lib/test-timings.mjs

@@ -0,0 +1,74 @@
+// Managed by @plainconceptsplatform/workflows. Source: loops/templates/quality-gates/scripts/lib/test-timings.mjs. Update with `workflows update --force`; consumer edits may be overwritten.
+
+// Reads VSTest .trx reports and says where a test run's time goes: by test class, since a class is
+// what xUnit runs in parallel and where a fixture's setup is paid once.
+
+const attr = (tag, name) => tag.match(new RegExp(`\\b${name}="([^"]*)"`))?.[1];
+
+function seconds(duration) {
+  const [h, m, s] = (duration ?? '0:0:0').split(':');
+  return Number(h) * 3600 + Number(m) * 60 + Number(s);
+}
+
+export function parseTrx(xml) {
+  const classes = new Map();
+  for (const [, id, body] of xml.matchAll(/<UnitTest\b[^>]*\bid="([^"]+)"[^>]*>([\s\S]*?)<\/UnitTest>/g)) {
+    const method = body.match(/<TestMethod\b[^>]*>/)?.[0];
+    if (method) classes.set(id, attr(method, 'className'));
+  }
+  const results = [];
+  for (const [tag] of xml.matchAll(/<UnitTestResult\b[^>]*>/g)) {
+    const className = classes.get(attr(tag, 'testId')) ?? 'unknown';
+    results.push({
+      className: className.split('.').pop(),
+      name: (attr(tag, 'testName') ?? '').replace(`${className}.`, ''),
+      seconds: seconds(attr(tag, 'duration')),
+      start: Date.parse(attr(tag, 'startTime') ?? ''),
+      end: Date.parse(attr(tag, 'endTime') ?? ''),
+      outcome: attr(tag, 'outcome') ?? 'Unknown',
+    });
+  }
+  const times = xml.match(/<Times\b[^>]*>/)?.[0] ?? '';
+  const wall = (Date.parse(attr(times, 'finish') ?? '') - Date.parse(attr(times, 'start') ?? '')) / 1000;
+  const runName = xml.match(/<TestRun\b[^>]*>/)?.[0];
+  const storage = xml.match(/<UnitTest\b[^>]*\bstorage="([^"]+)"/)?.[1] ?? attr(runName ?? '', 'name') ?? 'tests';
+  return { name: storage.split(/[\\/]/).pop().replace(/\.dll$/i, ''), wall: Number.isFinite(wall) ? wall : 0, results };
+}
+
+export function summarize(run, top = 15) {
+  const byClass = new Map();
+  for (const r of run.results) {
+    const c = byClass.get(r.className) ?? { name: r.className, tests: 0, seconds: 0, first: null };
+    c.tests += 1;
+    c.seconds += r.seconds;
+    if (!c.first || r.start < c.first.start) c.first = r;
+    byClass.set(r.className, c);
+  }
+  const total = run.results.reduce((sum, r) => sum + r.seconds, 0);
+  const classes = [...byClass.values()].sort((a, b) => b.seconds - a.seconds);
+  return {
+    name: run.name,
+    tests: run.results.length,
+    wall: run.wall,
+    total,
+    concurrency: run.wall > 0 ? total / run.wall : 0,
+    classes: classes.slice(0, top).map(({ name, tests, seconds, first }) => ({ name, tests, seconds, firstTest: first?.seconds ?? 0 })),
+    slowest: [...run.results].sort((a, b) => b.seconds - a.seconds).slice(0, top).map(({ className, name, seconds }) => ({ className, name, seconds })),
+  };
+}
+
+const s = (n) => `${n.toFixed(1)} s`;
+
+export function toMarkdown(summaries) {
+  const lines = ['### Test timings', ''];
+  for (const t of summaries) {
+    lines.push(`**${t.name}**: ${t.tests} tests, ${s(t.wall)} wall, ${s(t.total)} of test time, ${t.concurrency.toFixed(1)} running at once on average.`, '');
+    if (t.tests < 20) continue;
+    lines.push('| Class | Tests | Time | First test |', '|---|--:|--:|--:|');
+    for (const c of t.classes) lines.push(`| ${c.name} | ${c.tests} | ${s(c.seconds)} | ${s(c.firstTest)} |`);
+    lines.push('', '<details><summary>Slowest tests</summary>', '');
+    for (const r of t.slowest) lines.push(`- ${s(r.seconds)} ${r.className}: ${r.name.replace(/\|/g, '\\|')}`);
+    lines.push('', '</details>', '');
+  }
+  return lines.join('\n');
+}

package/loops/templates/quality-gates/scripts/lib/test-timings.test.mjs

@@ -0,0 +1,46 @@
+// Managed by @plainconceptsplatform/workflows. Source: loops/templates/quality-gates/scripts/lib/test-timings.test.mjs. Update with `workflows update --force`; consumer edits may be overwritten.
+// Run: node --test scripts/lib/test-timings.test.mjs
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { parseTrx, summarize, toMarkdown } from './test-timings.mjs';
+
+const unit = (id, cls, name) =>
+  `<UnitTest name="${name}" storage="/w/App.IntegrationTests.dll" id="${id}"><Execution id="e${id}" /><TestMethod codeBase="x" className="App.Tests.${cls}" name="${name}" /></UnitTest>`;
+const result = (id, duration, start, end) =>
+  `<UnitTestResult executionId="e${id}" testId="${id}" testName="${id} name" duration="${duration}" startTime="${start}" endTime="${end}" outcome="Passed" />`;
+
+const trx = `<?xml version="1.0"?><TestRun id="r" name="run">
+<Times creation="2026-01-01T00:00:00Z" start="2026-01-01T00:00:00.000Z" finish="2026-01-01T00:00:10.000Z" />
+<Results>
+${result('a', '00:00:06.0000000', '2026-01-01T00:00:00Z', '2026-01-01T00:00:06Z')}
+${result('b', '00:00:01.0000000', '2026-01-01T00:00:06Z', '2026-01-01T00:00:07Z')}
+${result('c', '00:00:08.0000000', '2026-01-01T00:00:01Z', '2026-01-01T00:00:09Z')}
+</Results>
+<TestDefinitions>${unit('a', 'OrdersTests', 'First')}${unit('b', 'OrdersTests', 'Second')}${unit('c', 'StockTests', 'Only')}</TestDefinitions>
+</TestRun>`;
+
+test('parseTrx_resultsAndDefinitions_joinsClassAndDurationAndWallTime', () => {
+  const run = parseTrx(trx);
+  assert.equal(run.name, 'App.IntegrationTests');
+  assert.equal(run.wall, 10);
+  assert.deepEqual(run.results.map((r) => [r.className, r.seconds]), [['OrdersTests', 6], ['OrdersTests', 1], ['StockTests', 8]]);
+});
+
+test('summarize_classesBySummedTime_reportsConcurrencyAndTheFirstTestCost', () => {
+  const t = summarize(parseTrx(trx));
+  assert.equal(t.total, 15);
+  assert.equal(t.concurrency, 1.5);
+  assert.deepEqual(t.classes.map((c) => [c.name, c.tests, c.seconds, c.firstTest]), [['StockTests', 1, 8, 8], ['OrdersTests', 2, 7, 6]]);
+  assert.equal(t.slowest[0].className, 'StockTests');
+});
+
+test('toMarkdown_smallRun_givesTheTotalsWithoutTables', () => {
+  const md = toMarkdown([summarize(parseTrx(trx))]);
+  assert.match(md, /\*\*App\.IntegrationTests\*\*: 3 tests, 10\.0 s wall, 15\.0 s of test time, 1\.5 running at once on average\./);
+  assert.doesNotMatch(md, /\| Class \|/);
+});
+
+test('parseTrx_fullyQualifiedTestName_dropsTheClassPrefix', () => {
+  const xml = `<TestRun><UnitTestResult testId="x" testName="App.Tests.OrdersTests.Saves(total: 1.5)" duration="00:00:01" outcome="Passed" />${unit('x', 'OrdersTests', 'Saves')}</TestRun>`;
+  assert.equal(parseTrx(xml).results[0].name, 'Saves(total: 1.5)');
+});

package/loops/templates/quality-gates/scripts/test-timings.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// Managed by @plainconceptsplatform/workflows. Source: loops/templates/quality-gates/scripts/test-timings.mjs. Update with `workflows update --force`; consumer edits may be overwritten.
+
+// Usage: node scripts/test-timings.mjs <dir-with-trx> [--top 15]
+// Prints where the test run's time went as Markdown, for the job summary. Never fails the job.
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseTrx, summarize, toMarkdown } from './lib/test-timings.mjs';
+
+const [dir = 'TestResults', ...rest] = process.argv.slice(2);
+const top = Number(rest[rest.indexOf('--top') + 1]) || 15;
+
+function trxFiles(root) {
+  try {
+    return readdirSync(root).flatMap((entry) => {
+      const full = join(root, entry);
+      return statSync(full).isDirectory() ? trxFiles(full) : entry.endsWith('.trx') ? [full] : [];
+    });
+  } catch {
+    return [];
+  }
+}
+
+const runs = trxFiles(dir).map((file) => summarize(parseTrx(readFileSync(file, 'utf8')), top)).filter((t) => t.tests > 0);
+console.log(runs.length ? toMarkdown(runs.sort((a, b) => b.wall - a.wall)) : `### Test timings\n\nNo .trx reports under ${dir}.`);

package/loops/templates/rulesets/main-required-checks.json

@@ -0,0 +1,17 @@
+{
+  "name": "Default branch: Full CI required",
+  "target": "branch",
+  "enforcement": "active",
+  "conditions": { "ref_name": { "include": ["~DEFAULT_BRANCH"], "exclude": [] } },
+  "rules": [
+    {
+      "type": "required_status_checks",
+      "parameters": {
+        "strict_required_status_checks_policy": false,
+        "do_not_enforce_on_create": false,
+        "required_status_checks": [{ "context": "Full CI" }]
+      }
+    }
+  ],
+  "bypass_actors": [{ "actor_id": 5, "actor_type": "RepositoryRole", "bypass_mode": "always" }]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plainconceptsplatform/workflows",
-  "version": "1.20.2",
+  "version": "1.21.0",
   "description": "Install and update Platform GitHub agentic workflows.",
   "keywords": [
     "github-actions",