@starci/hfs 4.6.0 → 4.7.1

package/runtime/scripts/hfs/rules/ci-standard.mjs

@@ -0,0 +1,202 @@
+// ci-standard.mjs - R301 CI_STANDARD: the one StarCi CI standard (knowledge/hfs/ci-standard.yaml, OWNER RULING ci-standard 2026-10-18: ".claude defines ONE standard CI
+// ruleset, its own CI and the examples follow it, and apps inherit it"). This file checks the items the standard marks `check: ci-standard`:
+//   job-shape              the managed ci.yml holds exactly the edition's jobs; the unit run is in `test`, the proof and the Codecov upload in `coverage` (the one OIDC job)
+//   full-history-base-ref  every actions/checkout fetches the full history; a job that lints writes STARCI_BASE_REF before it lints
+//   heap-per-step          every heavy step (heap.steps) declares NODE_OPTIONS --max-old-space-size >= heap.minMiB on the step
+//   sonar-lint-per-side    a lint with --sonar names --side
+//   optional-providers     an optional (continue-on-error) Codecov or Sonar step follows its availability probe in the same job
+//   test-sharding          the test job is a shard matrix; each shard runs --shard=i/N without the per-file threshold; the coverage job merges, then proves
+//   lint-parallel          the lint job is a matrix over side [be, fe]
+//   cache-saved-always     no cache keyed by the commit sha; actions/cache/save runs under if: always()
+//   timeouts               every job declares timeout-minutes
+//   sha-pinned-actions     every remote `uses:` names a 40-hex commit sha (docker:// a sha256 digest; ./ local actions allowed)
+// `ciStandardFindings({doc, file, scope})` is the pure core: scope `app-ci` (an app's managed .github/workflows/ci.yml: the example apps and every app through the
+// app check) or `runtime` (the runtime repository's own workflows, scripts/hfs/runtime-rules/runtime-ci-standard.mjs), each checking the items whose `covers` names it.
+import fs from 'node:fs';
+import { parseYaml } from '../../../engine/yaml.mjs';
+import { parseWorkflow } from '../runtime-rules/workflow-source.mjs';
+import { found } from './read.mjs';
+import { appWorkflowFindings } from './app-workflow-findings.mjs';
+import { isPlainObject as record } from '../../../engine/plain-object.mjs';
+import { byCodeUnit } from '../../lib/list.mjs';
+
+export const CI_STANDARD = 'CI_STANDARD';
+const STANDARD_FILE = new URL('../../../knowledge/hfs/ci-standard.yaml', import.meta.url);
+const APP_CI = '.github/workflows/ci.yml';
+const SHA_PIN = /@[0-9a-f]{40}$/;
+const DIGEST_PIN = /@sha256:[0-9a-f]{64}$/;
+
+let cached = null;
+/** The standard (knowledge/hfs/ci-standard.yaml), read once. */
+function ciStandard() {
+  if (!cached) {
+    const doc = parseYaml(fs.readFileSync(STANDARD_FILE, 'utf8'));
+    if (doc?.schema !== 'starci/ci-standard@1' || !Array.isArray(doc.items)) throw new Error('knowledge/hfs/ci-standard.yaml is not a starci/ci-standard@1 standard');
+    cached = doc;
+  }
+  return cached;
+}
+
+const jobsOf = (doc) => (record(doc?.jobs) ? Object.entries(doc.jobs).filter(([, job]) => record(job)) : []);
+const stepsOf = (job) => (Array.isArray(job.steps) ? job.steps.filter(record) : []);
+const usesOf = (step) => String(step.uses ?? '').trim();
+const runOf = (step) => (typeof step.run === 'string' ? step.run : '');
+
+/** The items of the standard this file checks for `scope`: their ids. */
+const checkedItems = (standard, scope) => new Set(standard.items.filter((item) => item.check === 'ci-standard' && item.covers.includes(scope)).map((item) => item.id));
+
+function jobShape(doc, edition, standard, say) {
+  const shape = standard.jobs[edition] ?? standard.jobs.full;
+  const ids = jobsOf(doc).map(([id]) => id);
+  const out = [];
+  const missing = shape.required.filter((id) => !ids.includes(id));
+  const extra = ids.filter((id) => !shape.required.includes(id) && !shape.optional.includes(id));
+  const gaps = [missing.length ? 'missing ' + missing.join(', ') : '', extra.length ? 'not in the standard ' + extra.join(', ') : ''].filter(Boolean).join('; ');
+  if (gaps) out.push(say('job-shape', `the jobs must be ${shape.required.join(', ')} (optional ${shape.optional.join(', ')}); ${gaps}`));
+  const withStep = (match) => jobsOf(doc).filter(([, job]) => stepsOf(job).some((step) => match(step))).map(([id]) => id);
+  const unit = withStep((step) => step.name === 'unit');
+  const upload = withStep((step) => usesOf(step).startsWith('codecov/codecov-action@'));
+  const proof = withStep((step) => /app check --coverage-from/.test(runOf(step)));
+  if (unit.join() !== 'test') out.push(say('job-shape', `the unit run must be a step of the test job alone, not of ${unit.join(', ') || 'no job'}`));
+  if (proof.join() !== 'coverage') out.push(say('job-shape', `the coverage proof must be a step of the coverage job alone, not of ${proof.join(', ') || 'no job'}`));
+  if (upload.length && upload.join() !== 'coverage') out.push(say('job-shape', `the Codecov upload must be a step of the coverage job alone, not of ${upload.join(', ')}`));
+  const oidc = jobsOf(doc).filter(([, job]) => job.permissions?.['id-token'] === 'write').map(([id]) => id);
+  if (upload.length && oidc.join() !== 'coverage') out.push(say('job-shape', `only the coverage job holds the OIDC id-token (id-token: write), not ${oidc.join(', ') || 'no job'}`));
+  return out;
+}
+
+function testSharding(doc, say) {
+  const test = record(doc.jobs?.test) ? doc.jobs.test : null;
+  if (!test) return [];
+  const out = [];
+  const shards = test.strategy?.matrix?.shard;
+  if (!Array.isArray(shards) || !shards.length) out.push(say('test-sharding', 'the test job must be a matrix over shard (ci.jobs.test.shards)'));
+  const unit = stepsOf(test).find((step) => step.name === 'unit');
+  const total = /--shard=\$\{\{\s*matrix\.shard\s*\}\}\/(\d+)/.exec(unit ? runOf(unit) : '');
+  if (unit && !total) out.push(say('test-sharding', 'the unit run must pass --shard=${{ matrix.shard }}/<N>'));
+  if (total && Array.isArray(shards) && Number(total[1]) !== shards.length) out.push(say('test-sharding', `the unit run's shard total ${total[1]} must equal the ${shards.length} matrix shards`));
+  if (unit && !runOf(unit).includes('--coverageThreshold={}')) out.push(say('test-sharding', 'a shard measures without the per-file threshold (--coverageThreshold={}); the coverage job proves it on the merged report'));
+  const coverage = record(doc.jobs?.coverage) ? stepsOf(doc.jobs.coverage) : [];
+  const merge = coverage.findIndex((step) => /app coverage merge\b/.test(runOf(step)));
+  const proof = coverage.findIndex((step) => /app check --coverage-from/.test(runOf(step)));
+  if (merge < 0 || (proof >= 0 && merge > proof)) out.push(say('test-sharding', 'the coverage job must merge the shard reports (starci app coverage merge) before the coverage proof'));
+  return out;
+}
+
+function lintParallel(doc, say) {
+  const sides = record(doc.jobs?.lint) ? doc.jobs.lint.strategy?.matrix?.side : null;
+  return Array.isArray(sides) && sides.map(String).sort(byCodeUnit).join() === 'be,fe' ? [] : [say('lint-parallel', 'the lint job must be a matrix over side [be, fe]')];
+}
+
+function cacheSavedAlways(doc, say) {
+  const out = [];
+  for (const [id, job] of jobsOf(doc)) {
+    for (const step of stepsOf(job)) {
+      const uses = usesOf(step);
+      if (/^actions\/cache(?:\/restore)?@/.test(uses) && String(step.with?.key ?? '').includes('github.sha')) out.push(say('cache-saved-always', `job ${id}: a cache keyed by the commit sha never warms; key it by the lockfile hash (and the run) with restore-keys`));
+      if (uses.startsWith('actions/cache/save@') && !/^(?:\$\{\{\s*)?always\(\)/.test(String(step.if ?? '').trim())) out.push(say('cache-saved-always', `job ${id}: actions/cache/save runs under if: always(), so a red run still warms the cache`));
+    }
+  }
+  return out;
+}
+
+function fullHistory(doc, say) {
+  const out = [];
+  for (const [id, job] of jobsOf(doc)) {
+    for (const step of stepsOf(job)) {
+      if (usesOf(step).startsWith('actions/checkout@') && String(step.with?.['fetch-depth']) !== '0') out.push(say('full-history-base-ref', `job ${id}: actions/checkout must fetch the full history (fetch-depth: 0)`));
+    }
+  }
+  for (const [id, job] of jobsOf(doc)) {
+    const steps = stepsOf(job);
+    const base = steps.findIndex((step) => /STARCI_BASE_REF=.*>>\s*"?\$GITHUB_ENV"?/.test(runOf(step)));
+    const lint = steps.findIndex((step) => /\bnpm run lint\b|\bstarci app lint\b/.test(runOf(step)));
+    if (lint >= 0 && (base < 0 || base > lint)) out.push(say('full-history-base-ref', `job ${id} must write STARCI_BASE_REF to GITHUB_ENV before its first lint step`));
+  }
+  return out;
+}
+
+function heapPerStep(doc, standard, say) {
+  const out = [];
+  for (const [id, job] of jobsOf(doc)) {
+    for (const step of stepsOf(job)) {
+      const run = runOf(step);
+      if (!standard.heap.steps.some((needle) => run.includes(needle))) continue;
+      const heap = /--max-old-space-size=(\d+)/.exec(String(step.env?.NODE_OPTIONS ?? ''));
+      if (!heap || Number(heap[1]) < standard.heap.minMiB) out.push(say('heap-per-step', `job ${id}, step ${step.name ?? run.split('\n')[0].slice(0, 60)}: a heavy step declares NODE_OPTIONS --max-old-space-size=${standard.heap.minMiB} (or more) on the step`));
+    }
+  }
+  return out;
+}
+
+function sonarLintPerSide(doc, say) {
+  const out = [];
+  for (const [id, job] of jobsOf(doc)) {
+    for (const step of stepsOf(job)) {
+      const run = runOf(step);
+      if (/\b(?:npm run lint|starci(?:\.mjs)?["']?\s+app lint|app lint)\b/.test(run) && /\s--sonar\b/.test(run) && !/\s--side\s+(?:be\b|fe\b|\$\{\{\s*matrix\.side\s*\}\})/.test(run)) {
+        out.push(say('sonar-lint-per-side', `job ${id}, step ${step.name ?? 'lint'}: a lint with a Sonar import must name its side (--side be|fe) and the reports are merged afterwards; a combined lint with Sonar breaks the standard`));
+      }
+    }
+  }
+  return out;
+}
+
+function optionalProviders(doc, say) {
+  const out = [];
+  const probes = [['codecov/codecov-action@', 'codecov-availability'], ['SonarSource/sonarqube-scan-action@', 'sonar-availability']];
+  for (const [id, job] of jobsOf(doc)) {
+    const steps = stepsOf(job);
+    steps.forEach((step, index) => {
+      const probe = probes.find(([prefix]) => usesOf(step).startsWith(prefix));
+      if (!probe || step['continue-on-error'] !== true) return;
+      if (!steps.slice(0, index).some((earlier) => earlier.id === probe[1])) out.push(say('optional-providers', `job ${id}: the optional ${usesOf(step).split('@')[0]} step must follow its availability probe (id ${probe[1]})`));
+    });
+  }
+  return out;
+}
+
+function timeouts(doc, say) {
+  return jobsOf(doc).filter(([, job]) => !Number.isFinite(Number(job['timeout-minutes'])) || job['timeout-minutes'] === null || job['timeout-minutes'] === '')
+    .filter(([, job]) => job.uses === undefined).map(([id]) => say('timeouts', `job ${id} must declare timeout-minutes`));
+}
+
+function shaPinned(doc, say) {
+  const out = [];
+  for (const [id, job] of jobsOf(doc)) {
+    for (const uses of [job.uses, ...stepsOf(job).map((step) => step.uses)].filter((value) => typeof value === 'string')) {
+      const ref = uses.trim();
+      if (ref.startsWith('./')) continue;
+      const pinned = ref.startsWith('docker://') ? DIGEST_PIN.test(ref) : SHA_PIN.test(ref);
+      if (!pinned) out.push(say('sha-pinned-actions', `job ${id}: ${ref} must be pinned to a commit sha (a docker:// action to a sha256 digest)`));
+    }
+  }
+  return out;
+}
+
+/** The R301 findings of one workflow document: scope `app-ci` (with the app's edition) or `runtime`. Pure over the document and the standard. */
+export function ciStandardFindings({ doc, file, scope, edition = 'full', standard = ciStandard() }) {
+  if (!record(doc)) return [];
+  const items = checkedItems(standard, scope);
+  const say = (item, why) => found(CI_STANDARD, file, `${CI_STANDARD} ${file}: [${item}] ${why} (knowledge/hfs/ci-standard.yaml)`, { item });
+  const checks = {
+    'job-shape': () => jobShape(doc, edition, standard, say),
+    'full-history-base-ref': () => fullHistory(doc, say),
+    'heap-per-step': () => heapPerStep(doc, standard, say),
+    'sonar-lint-per-side': () => sonarLintPerSide(doc, say),
+    'optional-providers': () => optionalProviders(doc, say),
+    'test-sharding': () => testSharding(doc, say),
+    'lint-parallel': () => lintParallel(doc, say),
+    'cache-saved-always': () => cacheSavedAlways(doc, say),
+    timeouts: () => timeouts(doc, say),
+    'sha-pinned-actions': () => shaPinned(doc, say),
+  };
+  return Object.entries(checks).filter(([id]) => items.has(id)).flatMap(([, check]) => check());
+}
+
+/** R301 over an app: its managed .github/workflows/ci.yml (the app check, and the runtime check over every example app). */
+export function ciStandardAppFindings(ctx) {
+  const edition = ctx.repo?.edition === 'lite' ? 'lite' : 'full';
+  return appWorkflowFindings({ ...ctx, inScope: (file) => file === APP_CI && (ctx.inScope ?? (() => true))(file) },
+    ({ path: file, text }) => ciStandardFindings({ doc: parseWorkflow(text), file, scope: 'app-ci', edition }), { dedupe: true });
+}

package/runtime/scripts/hfs/rules/coverage-below.mjs

@@ -18,7 +18,7 @@ const countOf = (value) => /^\d+$/.test(value) && Number.isSafeInteger(Number(va
 const slash = (value) => path.posix.normalize(String(value).replaceAll('\\', '/'));
 
 const emptyRecord = (source) => ({ source, lines: new Map(), functions: new Map(), branches: new Map(), summary: {}, problems: [] });
-const addHits = (map, key, hits) => map.set(key, Math.min(Number.MAX_SAFE_INTEGER, (map.get(key) ?? 0) + hits));
+export const addHits = (map, key, hits) => map.set(key, Math.min(Number.MAX_SAFE_INTEGER, (map.get(key) ?? 0) + hits));
 const parseProblem = (record, line, tag) => record.problems.push(`invalid ${tag} at lcov line ${line}`);
 
 function lineData(record, value, line) {

package/runtime/scripts/hfs/rules/deploy-workflow.mjs

@@ -68,18 +68,27 @@ function hasAgeIdentity(job, doc) {
   return steps.some((step) => strings(step.with).some((value) => reference.test(value)) || (typeof step.run === 'string' && reference.test(executable(step.run))));
 }
 
-function triggerFindings(doc, refuse) {
+/** The release candidate branches (OWNER RULING candidate-ci, 2026-10-18): `starci app release push` waits for the ci.yml run of the release sha there. */
+const CANDIDATE_BRANCHES = 'release/candidate-*';
+const pushFilterValid = (options) => record(options) && Object.keys(options).length > 0 && Object.keys(options).every((key) => key === 'tags' || key === 'branches')
+  && (options.tags === undefined || (Array.isArray(options.tags) && options.tags.length === 1 && options.tags[0] === 'v*'))
+  && (options.branches === undefined || (Array.isArray(options.branches) && options.branches.length === 1 && options.branches[0] === CANDIDATE_BRANCHES));
+
+function triggerFindings(doc, refuse, file = '') {
   const on = workflowEventOptions(doc.on);
   if (!record(on) || !Object.keys(on).length) return [refuse(TRIGGER, 'declare release tags [v*] and/or workflow_dispatch')];
   const findings = [];
+  if (/(^|\/)ci\.ya?ml$/.test(file) && !(record(on.push) && Array.isArray(on.push.branches) && on.push.branches.includes(CANDIDATE_BRANCHES))) {
+    findings.push(refuse(TRIGGER, `the release CI must run on push of branches ['${CANDIDATE_BRANCHES}']: starci app release push waits for that run (starci app sync renders it)`));
+  }
   for (const [event, options] of Object.entries(on)) {
     if (event === 'workflow_dispatch') continue;
     if (event !== 'push') {
-      findings.push(refuse(TRIGGER, `trigger ${event} is forbidden; app CI starts only on release tags [v*] or workflow_dispatch`));
+      findings.push(refuse(TRIGGER, `trigger ${event} is forbidden; app CI starts only on release tags [v*], the release candidate branches or workflow_dispatch`));
       continue;
     }
-    if (!record(options) || !Array.isArray(options.tags) || options.tags.length !== 1 || options.tags[0] !== 'v*' || Object.keys(options).some((key) => key !== 'tags')) {
-      findings.push(refuse(TRIGGER, 'push must contain only tags: [v*]; branch and path filters are forbidden'));
+    if (!pushFilterValid(options)) {
+      findings.push(refuse(TRIGGER, `push may contain only tags: [v*] and branches: ['${CANDIDATE_BRANCHES}']; other branch and path filters are forbidden`));
     }
   }
   return findings;
@@ -197,7 +206,7 @@ function perWorkflow({ path: file, text }) {
   const refuse = (code, message) => found(code, file, `${code} ${file}: ${message}`);
   const doc = parseWorkflow(text);
   if (!record(doc)) return [refuse(TRIGGER, 'the workflow must be valid YAML with a release-only on block'), ...(deployName(file) ? [refuse(DEPLOY, 'the deploy workflow must be valid YAML')] : [])];
-  return [...triggerFindings(doc, refuse), ...deploymentFindings(doc, file, refuse), ...toolFindings(doc, refuse)];
+  return [...triggerFindings(doc, refuse, file), ...deploymentFindings(doc, file, refuse), ...toolFindings(doc, refuse)];
 }
 
 /** Synchronous R251 findings over the tracked workflows of a lite/full app. */

package/runtime/scripts/hfs/rules/workflow-contexts.mjs

@@ -75,7 +75,7 @@ function expressions(value) {
 }
 
 /** Source markers travel inside parsed scalar expressions, preserving flow maps, quoted keys and repeated values without matching comments. */
-function workflowContextFindings({ path: file, text }) {
+export function workflowContextFindings({ path: file, text }) {
   const marked = text.replace(/\$\{\{/g, (match, offset) => `${match} __hfs_context_line_${text.slice(0, offset).split('\n').length}__ `);
   const findings = [];
   function inspect(value, keys) {

package/scaffold/app.mjs

@@ -300,9 +300,10 @@ export function peerDependencies(pkg, pins, pairs = parseYaml(fs.readFileSync(PE
 /**
  * The fe-stack core packages one version of which the whole install resolves (npm `overrides`, at their canon pins): a
  * transitive dependency otherwise brings its own (zustand 4 under @xyflow/react, dayjs under typeorm, a hoisted newer zod
- * that breaks the zodResolver types), and @xyflow/react itself stays the grammar's one version.
+ * that breaks the zodResolver types), and @xyflow/react itself stays the grammar's one version. @graphql-tools/utils is the one security override: @nestjs/graphql 13.x
+ * pulls <=12.0.0 (GHSA-7mx3-vvmw-hjmv), and the pin's fixed 12.x closes the advisory until @nestjs/graphql 14 is adopted (then drop it; canon-pins.yaml says why).
  */
-const ROOT_OVERRIDES = Object.freeze(['@xyflow/react', 'dayjs', 'zod', 'zustand']);
+const ROOT_OVERRIDES = Object.freeze(['@graphql-tools/utils', '@xyflow/react', 'dayjs', 'zod', 'zustand']);
 
 /**
  * The root package.json of a new app, the monorepo root: name, workspaces, npm, its edition's dependencies with their runtime

package/src/main.mjs

@@ -29,6 +29,7 @@
 //   starci app sync (--check | --write) [--cwd <dir>]  the managed files of the root (scripts, husky, CI, .gitignore block, sonar, prettier) and
 //                                            of each side (tsconfig, eslint, jest, stylelint); sync/cli.mjs
 //   starci app hygiene                             the pre-commit guard: staged .starciwork and .starcistacks paths, and the secrets guard over every staged file (read from the index); sync/cli.mjs
+//   starci app coverage merge --out <lcov> <lcov-or-dir>...  the lcov reports of the sharded unit run merged into one (coverage/cli.mjs; the managed CI coverage job)
 //   starci app new service <dir> <name> [--inject <Decorator>=<module>:<Type> | <Class>=<module>]... [--cwd <dir>]
 //                                            a back-end `<name>.service.ts` and its `<name>.service.spec.ts` skeleton (scaffold/service.mjs; <dir> is
 //                                            relative to be/): the spec is built
@@ -89,7 +90,7 @@ import { dbPostCutoverMain } from '../db/post-cutover.mjs';
 import { dbDumpMain } from '../db/dump.mjs';
 import { dbResetMain } from '../db/reset.mjs';
 
-export const VERBS = Object.freeze(['scaffold', 'add', 'lint', 'sync', 'check', 'upgrade', 'stack', 'release', 'explain', 'emit', 'new', 'secret', 'ci', 'db', 'hygiene']);
+export const VERBS = Object.freeze(['scaffold', 'add', 'lint', 'sync', 'check', 'upgrade', 'stack', 'release', 'explain', 'emit', 'new', 'secret', 'ci', 'db', 'hygiene', 'coverage']);
 const DATABASE_VERBS = new Map([['baseline', dbBaselineMain], ['restamp', dbRestampMain], ['plan', dbPlanMain], ['migrate', dbMigrateMain], ['post-cutover', dbPostCutoverMain], ['dump', dbDumpMain], ['reset', dbResetMain]]);
 
 const USAGE = `starci app scaffold <name> [--into <dir>] [--edition full|lite] [--registry-visibility public|private] [--cwd <dir>]
@@ -128,6 +129,7 @@ starci app ci var set <NAME> [--env E] [--value v] [--repo owner/name] [--cwd <d
 starci app ci var sync [--execute] [--repo owner/name] [--cwd <dir>]
 starci app ci verify [--json] [--repo owner/name] [--cwd <dir>]
 starci app hygiene [--cwd <dir>]
+starci app coverage merge --out <lcov> <lcov-or-dir>... [--cwd <dir>]
 `;
 const PER_CODE_LIMIT = 25;
 const VALUE_FLAGS = new Set(['--base', '--inject', '--into', '--event', '--from', '--service', '--connection', '--owner', '--failed', '--done', '--coverage-from', '--registry-visibility']);
@@ -419,7 +421,7 @@ async function stackAppMain(argv, { cwd, edition, stackMain, stdout: out, stderr
   return run(argv, { cwd, out, err });
 }
 
-const DIRECT_VERBS = new Map([['ci', async (argv, io) => (await import('../ci/cli.mjs')).ciMain(argv, io)], ['lint', lintMain], ['secret', secretMain], ['db', databaseMain], ['upgrade', upgradeAppMain], ['stack', stackAppMain], ['release', releaseMain]]);
+const DIRECT_VERBS = new Map([['ci', async (argv, io) => (await import('../ci/cli.mjs')).ciMain(argv, io)], ['lint', lintMain], ['secret', secretMain], ['db', databaseMain], ['upgrade', upgradeAppMain], ['stack', stackAppMain], ['release', releaseMain], ['coverage', async (argv, io) => (await import('../coverage/cli.mjs')).coverageMain(argv, io)]]);
 const PARSED_VERBS = new Map([['check', checkMain], ['emit', emitMain], ['new', newMain], ['add', addMain], ['scaffold', scaffoldMain], ['explain', explainMain]]);
 
 function dispatchMain(verb, argv, io) {

package/sync/ci-commands.mjs

@@ -92,14 +92,14 @@ function codecovSteps(lcovReport, codecov) {
 }
 
 /** Sonar consumes the test coverage and fast lint artifacts only on release tags with a configured token. */
-function sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor) {
+function sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor, timeout) {
   if (!sonar) return '';
   const condition = sonar.optional ? SONAR_CONDITION.replace(' }}', " && steps.sonar-availability.outputs.up == 'true' }}") : SONAR_CONDITION;
   const host = sonar.provider === 'sonarcloud' ? 'https://sonarcloud.io' : `\${{ vars.${sonar.hostVar} }}`;
   const header = [
     '  sonar:',
-    '    needs: [fast, test]',
-    '    timeout-minutes: 20',
+    '    needs: [lint, coverage]',
+    `    timeout-minutes: ${timeout}`,
     '    runs-on: ubuntu-latest',
     '    env:',
     `      SONAR_TOKEN: \${{ secrets.${sonar.token} }}`,
@@ -116,8 +116,10 @@ function sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor) {
     `      - uses: ${DOWNLOAD_ARTIFACT}`,
     `        if: ${condition}`,
     '        with:',
-    '          name: sonar-lint',
+    '          pattern: sonar-lint-*',
     '          path: reports',
+    '          merge-multiple: true',
+    ...sonarMergeSteps(condition),
     '      - uses: SonarSource/sonarqube-scan-action@c7ee0f9df90b7aa20e8dcf9695dcfe2e7da5b4f2 # v7.2.1',
     `        if: ${condition}`,
     '      - uses: SonarSource/sonarqube-quality-gate-action@7a5fffe8e523c40e0c740b6bc2712ab503e52efa # v1.2.1',
@@ -187,11 +189,11 @@ function frontendBuild(source, app) {
   return { env: singleEnv, steps };
 }
 
-/** Side lint reports join into the single Sonar artifact even when one side could not write its report. */
-function sonarMergeSteps() {
+/** The per-side lint reports (one artifact per lint matrix side) join into the one reports/lint.sonar.json the Sonar import reads, even when one side wrote none. */
+function sonarMergeSteps(condition) {
   return [
     '      - name: merge Sonar lint reports',
-    "        if: always() && env.SONAR_TOKEN != ''",
+    `        if: ${condition}`,
     '        run: |',
     "          node --input-type=module <<'NODE'",
     "          import fs from 'node:fs';",
@@ -205,6 +207,20 @@ function sonarMergeSteps() {
   ];
 }
 
+const STANDARD = new URL('../runtime/knowledge/hfs/ci-standard.yaml', import.meta.url);
+/** The per-job settings of the managed CI: ci.jobs.<job>.timeoutMinutes and ci.jobs.test.shards of the manifest over the defaults of the CI standard. */
+function ciJobSettings(declaration) {
+  const defaults = parseYaml(fs.readFileSync(STANDARD, 'utf8')).defaults;
+  const jobs = declaration?.ci?.jobs ?? {};
+  const timeout = (job) => String(jobs[job]?.timeoutMinutes ?? defaults.timeoutMinutes[job]);
+  const shards = Number(jobs.test?.shards ?? defaults.shards);
+  return {
+    timeoutFast: timeout('fast'), timeoutLint: timeout('lint'), timeoutTest: timeout('test'), timeoutCoverage: timeout('coverage'),
+    timeoutBuild: timeout('build'), timeoutSonar: timeout('sonar'), timeoutDbTypes: timeout('db-types'),
+    testShards: `[${Array.from({ length: shards }, (_, index) => index + 1).join(', ')}]`, testShardTotal: String(shards),
+  };
+}
+
 /** An omitted quality declaration preserves hosted Sonar, required OIDC Codecov, and the high production dependency audit. */
 export function ciWorkflowCommands(source, lcovReport = 'be/coverage/lcov.info', quality = undefined, { nodeMajor = '22', app } = {}) {
   const configuredSonar = quality === undefined ? { token: 'SONAR_TOKEN', hostVar: 'SONAR_HOST_URL' } : quality.sonar;
@@ -213,7 +229,11 @@ export function ciWorkflowCommands(source, lcovReport = 'be/coverage/lcov.info',
   const audit = quality?.audit ?? { level: 'high', omitDev: true };
   const lcovArtifact = 'coverage-lcov';
   const build = frontendBuild(source, app);
+  const settings = ciJobSettings(buildDeclaration(source));
+  const side = '${{ matrix.side }}';
   return {
+    ...settings,
+    lcovShardsDir: lcovReport.split('/').slice(0, -1).concat('shards').join('/'),
     ciBuildEnv: build.env,
     ciBuildSteps: build.steps,
     ciLint: exampleCommand(source, 'npm run lint'),
@@ -224,32 +244,29 @@ export function ciWorkflowCommands(source, lcovReport = 'be/coverage/lcov.info',
     sonarTokenSecret: sonar?.token ?? 'SONAR_TOKEN',
     sonarHostVar: sonar?.hostVar ?? 'SONAR_HOST_URL',
     sonarEnv: sonar ? `    env:\n      SONAR_TOKEN: \${{ secrets.${sonar.token} }}` : '',
+    // One lint job per side (the lint matrix): with a Sonar token each side writes its own report, uploaded as sonar-lint-<side> and merged by the sonar job.
     ciLintSteps: [
-      ...['be', 'fe'].flatMap((side) => [
-        '      - name: lint ' + side,
-        ...(sonar ? ["        if: env.SONAR_TOKEN == ''"] : []),
-        `        run: ${exampleCommand(source, 'npm run lint -- --side ' + side)}`,
+      '      - name: lint',
+      ...(sonar ? ["        if: env.SONAR_TOKEN == ''"] : []),
+      `        run: ${exampleCommand(source, 'npm run lint -- --side ' + side)}`,
+      '        env:',
+      '          NODE_OPTIONS: --max-old-space-size=6144',
+      ...(sonar ? [
+        '      - name: lint with Sonar import',
+        "        if: env.SONAR_TOKEN != ''",
+        `        run: ${exampleCommand(source, 'npm run lint -- --side ' + side + ' --sonar reports/lint.' + side + '.sonar.json')}`,
         '        env:',
         '          NODE_OPTIONS: --max-old-space-size=6144',
-      ]),
-      ...(sonar ? [
-        ...['be', 'fe'].flatMap((side) => [
-          '      - name: lint ' + side + ' with Sonar import',
-          "        if: env.SONAR_TOKEN != ''",
-          `        run: ${exampleCommand(source, 'npm run lint -- --side ' + side + ' --sonar reports/lint.' + side + '.sonar.json')}`,
-          '        env:',
-          '          NODE_OPTIONS: --max-old-space-size=6144',
-        ]),
-        ...sonarMergeSteps(),
         `      - uses: ${UPLOAD_ARTIFACT}`,
-        "        if: always() && env.SONAR_TOKEN != '' && hashFiles('reports/lint.sonar.json') != ''",
+        // Inside an if: expression the matrix value is an argument of format(), never a nested ${{ }} (actionlint: a nested expression makes the condition always true).
+        "        if: always() && env.SONAR_TOKEN != '' && hashFiles(format('reports/lint.{0}.sonar.json', matrix.side)) != ''",
         '        with:',
-        '          name: sonar-lint',
-        '          path: reports/lint.sonar.json',
+        `          name: sonar-lint-${side}`,
+        `          path: reports/lint.${side}.sonar.json`,
       ] : []),
     ].join('\n'),
     codecovSteps: codecovSteps(lcovReport, codecov),
-    sonarJob: sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor),
+    sonarJob: sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor, settings.timeoutSonar),
     lcovArtifact,
   };
 }

package/templates/app/ci-workflows/build-cache-save.yml

@@ -0,0 +1,8 @@
+      - name: build cache save
+        if: always()
+        uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        with:
+          path: |
+            .turbo
+            fe/apps/*/.next/cache
+          key: ${{ runner.os }}-node{{nodeMajor}}-build-${{ hashFiles('package-lock.json') }}-${{ github.run_id }}

package/templates/app/ci-workflows/github/workflows/ci.yml

@@ -1,8 +1,10 @@
 {{header}}
 name: ci
 
+# The release candidate ref first (starci app release push waits for this run of the release sha before the branch and the tag move), then the tag.
 on:
   push:
+    branches: ["release/candidate-*"]
     tags: ["v*"]
   workflow_dispatch:
 
@@ -14,24 +16,58 @@ concurrency:
   group: ci-${{ github.ref }}
   cancel-in-progress: false
 
+# The job shape of the StarCi CI standard (knowledge/hfs/ci-standard.yaml): fast, lint per side, the unit run in shards, one coverage merge, build,
+# and sonar. Timeouts and the shard count come from ci.jobs of .starcistacks/application-stacks.yaml (defaults in the standard).
 jobs:
   fast:
-    timeout-minutes: 20
+    timeout-minutes: {{timeoutFast}}
     runs-on: ubuntu-latest
-{{sonarEnv}}
     steps:
 {{> app/ci-workflows/install-steps.yml}}
-{{> app/ci-workflows/lint-base.yml}}
       - name: production dependency audit
         run: {{auditCommand}}
-{{ciLintSteps}}
       - name: format
         run: npm run format:check
       - name: typecheck
         run: npm run typecheck
 
+  lint:
+    timeout-minutes: {{timeoutLint}}
+    runs-on: ubuntu-latest
+{{sonarEnv}}
+    strategy:
+      fail-fast: false
+      matrix:
+        side: [be, fe]
+    steps:
+{{> app/ci-workflows/install-steps.yml}}
+{{> app/ci-workflows/lint-base.yml}}
+{{ciLintSteps}}
+
   test:
-    timeout-minutes: 45
+    timeout-minutes: {{timeoutTest}}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: {{testShards}}
+    steps:
+{{> app/ci-workflows/install-steps.yml}}
+{{> app/ci-workflows/jest-cache.yml}}
+      # Each shard measures without the per-file threshold (a shard loads only its share of the specs, and a small suite may leave a shard empty);
+      # the coverage job proves 100 per file on the merged report.
+      - name: unit
+        run: npm test -- --ci --forceExit --cacheDirectory .jest-cache --shard=${{ matrix.shard }}/{{testShardTotal}} --passWithNoTests --coverageThreshold={}
+{{> app/ci-workflows/jest-cache-save.yml}}
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        if: always() && hashFiles('{{lcovReport}}') != ''
+        with:
+          name: coverage-shard-${{ matrix.shard }}
+          path: {{lcovReport}}
+
+  coverage:
+    needs: test
+    timeout-minutes: {{timeoutCoverage}}
     runs-on: ubuntu-latest
     # Codecov OIDC authentication requires a job-scoped identity token.
     permissions:
@@ -39,9 +75,12 @@ jobs:
       id-token: write
     steps:
 {{> app/ci-workflows/install-steps.yml}}
-{{> app/ci-workflows/jest-cache.yml}}
-      - name: unit
-        run: npm test -- --ci --forceExit --cacheDirectory .jest-cache
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          pattern: coverage-shard-*
+          path: {{lcovShardsDir}}
+      - name: merge coverage
+        run: npx starci app coverage merge --out {{lcovReport}} {{lcovShardsDir}}
       - name: coverage proof
         run: {{ciCoverageProof}}
         env:
@@ -54,12 +93,13 @@ jobs:
 {{codecovSteps}}
 
   build:
-    timeout-minutes: 30
+    timeout-minutes: {{timeoutBuild}}
     runs-on: ubuntu-latest
     steps:
 {{> app/ci-workflows/install-steps.yml}}
       - name: build be
         run: npm run build:be
 {{ciBuildSteps}}
+{{> app/ci-workflows/build-cache-save.yml}}
 
 {{sonarJob}}

package/templates/app/ci-workflows/install-steps.yml

@@ -10,12 +10,13 @@
         with:
           path: node_modules
           key: ${{ runner.os }}-node{{nodeMajor}}-modules-${{ hashFiles('package-lock.json') }}
-      - uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+      # The build cache is restored in every job and saved by the build job always (build-cache-save.yml), keyed by the lockfile and the run.
+      - uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
         with:
           path: |
             .turbo
             fe/apps/*/.next/cache
-          key: ${{ runner.os }}-node{{nodeMajor}}-build-${{ hashFiles('package-lock.json') }}-${{ github.sha }}
+          key: ${{ runner.os }}-node{{nodeMajor}}-build-${{ hashFiles('package-lock.json') }}-${{ github.run_id }}
           restore-keys: |
             ${{ runner.os }}-node{{nodeMajor}}-build-${{ hashFiles('package-lock.json') }}-
             ${{ runner.os }}-node{{nodeMajor}}-build-

package/templates/app/ci-workflows/jest-cache-save.yml

@@ -0,0 +1,6 @@
+      - name: Jest cache save
+        if: always()
+        uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        with:
+          path: .jest-cache
+          key: ${{ runner.os }}-node{{nodeMajor}}-jest-${{ hashFiles('package-lock.json') }}-shard${{ matrix.shard }}-${{ github.run_id }}

package/templates/app/ci-workflows/jest-cache.yml

@@ -1,8 +1,8 @@
-      - name: Jest cache
-        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+      - name: Jest cache restore
+        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
         with:
           path: .jest-cache
-          key: ${{ runner.os }}-node{{nodeMajor}}-jest-${{ hashFiles('package-lock.json') }}-${{ github.sha }}
+          key: ${{ runner.os }}-node{{nodeMajor}}-jest-${{ hashFiles('package-lock.json') }}-shard${{ matrix.shard }}-${{ github.run_id }}
           restore-keys: |
+            ${{ runner.os }}-node{{nodeMajor}}-jest-${{ hashFiles('package-lock.json') }}-shard${{ matrix.shard }}-
             ${{ runner.os }}-node{{nodeMajor}}-jest-${{ hashFiles('package-lock.json') }}-
-            ${{ runner.os }}-node{{nodeMajor}}-jest-