@starci/hfs 4.5.1 → 4.7.0

package/runtime/scripts/hfs/lcov-merge.mjs

@@ -0,0 +1,89 @@
+// lcov-merge.mjs - the lcov reports of the sharded unit run merged into one (`starci app coverage merge`, the coverage job of the managed CI). Each shard of
+// `npm test -- --shard=i/N` writes its own lcov over the whole collectCoverageFrom scope (a file no test of that shard loads is a record of zeros), so the
+// merge sums every line, function and branch hit by its identity across the shards and writes ONE record per source file, with the summaries recomputed:
+// the coverage proof (`starci app check --coverage-from`), the Codecov upload and the Sonar import then read the one be/coverage/lcov.info they always read.
+// Pure over the texts; the file walk is lcovFilesUnder.
+import fs from 'node:fs';
+import path from 'node:path';
+import { byCodeUnit } from '../lib/list.mjs';
+import { addHits as add } from './rules/coverage-below.mjs';
+
+const count = (value) => (/^\d+$/.test(value) ? Number(value) : 0);
+
+function recordOf(records, source) {
+  if (!records.has(source)) records.set(source, { lines: new Map(), fnLines: new Map(), fnHits: new Map(), branches: new Map() });
+  return records.get(source);
+}
+
+/** Function data: FN:<line>[,<end>],<name> declares, FNDA:<hits>,<name> counts (a name may hold commas). */
+function functionLine(record, tag, value) {
+  const at = value.indexOf(',');
+  if (at < 0) return;
+  if (tag === 'FN') {
+    let name = value.slice(at + 1);
+    let line = value.slice(0, at);
+    if (/^\d+,/.test(name)) { line = `${line},${name.slice(0, name.indexOf(','))}`; name = name.slice(name.indexOf(',') + 1); }
+    if (!record.fnLines.has(name)) record.fnLines.set(name, line);
+    if (!record.fnHits.has(name)) record.fnHits.set(name, 0);
+  } else add(record.fnHits, value.slice(at + 1), count(value.slice(0, at)));
+}
+
+function dataLine(record, tag, value) {
+  if (tag === 'DA') {
+    const [line, hits] = value.split(',');
+    add(record.lines, Number(line), count(hits ?? ''));
+  } else if (tag === 'FN' || tag === 'FNDA') functionLine(record, tag, value);
+  else if (tag === 'BRDA') {
+    const parts = value.split(',');
+    if (parts.length === 4) add(record.branches, parts.slice(0, 3).join(','), parts[3] === '-' ? 0 : count(parts[3]));
+  }
+}
+
+/** Every record of every text, merged by source file (SF) and identity. */
+function parseAll(texts) {
+  const records = new Map();
+  for (const text of texts) {
+    let current = null;
+    for (const raw of String(text).replace(/^/, '').split(/\r?\n/)) {
+      const line = raw.trim();
+      if (line === 'end_of_record') { current = null; continue; }
+      const colon = line.indexOf(':');
+      if (colon < 0) continue;
+      const tag = line.slice(0, colon);
+      const value = line.slice(colon + 1);
+      if (tag === 'SF') current = recordOf(records, value);
+      else if (current) dataLine(current, tag, value);
+    }
+  }
+  return records;
+}
+
+const branchOrder = (a, b) => a.split(',').map(Number).reduce((order, part, index) => order || part - Number(b.split(',')[index]), 0);
+
+function serialize(source, record) {
+  const out = ['TN:', `SF:${source}`];
+  const functions = [...record.fnLines.keys()].sort((a, b) => Number(record.fnLines.get(a).split(',')[0]) - Number(record.fnLines.get(b).split(',')[0]) || byCodeUnit(a, b));
+  for (const name of functions) out.push(`FN:${record.fnLines.get(name)},${name}`);
+  for (const name of functions) out.push(`FNDA:${record.fnHits.get(name) ?? 0},${name}`);
+  out.push(`FNF:${functions.length}`, `FNH:${functions.filter((name) => (record.fnHits.get(name) ?? 0) > 0).length}`);
+  const lines = [...record.lines.keys()].sort((a, b) => a - b);
+  for (const line of lines) out.push(`DA:${line},${record.lines.get(line)}`);
+  out.push(`LF:${lines.length}`, `LH:${lines.filter((line) => record.lines.get(line) > 0).length}`);
+  const branches = [...record.branches.keys()].sort(branchOrder);
+  for (const branch of branches) out.push(`BRDA:${branch},${record.branches.get(branch)}`);
+  out.push(`BRF:${branches.length}`, `BRH:${branches.filter((branch) => record.branches.get(branch) > 0).length}`, 'end_of_record');
+  return out.join('\n');
+}
+
+/** One lcov text of the merged `texts`: a record per source file, sorted by path, hits summed by line, function name and branch identity. */
+export function mergeLcov(texts) {
+  const records = parseAll(texts);
+  return [...records.keys()].sort(byCodeUnit).map((source) => serialize(source, records.get(source))).join('\n') + (records.size ? '\n' : '');
+}
+
+/** The lcov files a path names: the file itself, or every `lcov.info` below a directory (sorted). */
+export function lcovFilesUnder(target) {
+  if (!fs.statSync(target).isDirectory()) return [target];
+  return fs.readdirSync(target, { recursive: true, withFileTypes: true }).filter((entry) => entry.isFile() && entry.name === 'lcov.info')
+    .map((entry) => path.join(entry.parentPath ?? entry.path, entry.name)).sort(byCodeUnit);
+}

package/runtime/scripts/hfs/rules/a15-findings.mjs

@@ -34,6 +34,7 @@ import { stackToolingFindings } from './stack-tooling.mjs';
 import { stacksDeployFindings } from './stacks-deploy.mjs';
 import { ciCustodyFindings } from './ci-custody.mjs';
 import { workflowContextsFindings } from './workflow-contexts.mjs';
+import { ciStandardAppFindings } from './ci-standard.mjs';
 import { feBuildArgsFindings } from './fe-build-args.mjs';
 // finders-import-end
 
@@ -42,6 +43,7 @@ export const A15_CODES = [
   // codes-begin
   'FE_PUBLIC_BUILD_ARG_MISSING',
   'HFS_WORKFLOW_CONTEXT',
+  'CI_STANDARD',
   'CI_SECRET_SEALED', 'APP_SECRET_IN_CI', 'CI_DECLARATION_DRIFT',
   'BACKUP_PROOF_MISSING', 'BACKUP_UNDECLARED', 'BE_APP_BOOT_PROOF_MISSING', 'BE_APP_ENV_REQUIRED', 'BE_APP_MODULE_LIST_INLINE', 'BE_LITE_PROOF_LANE_MISSING', 'DB_API_EXPOSED', 'DB_ARCHIVE_MUTATED', 'DB_BASELINE_SHAPE', 'DB_CRON_OWNED', 'DB_EXTENSION_ALLOWED', 'DB_MIGRATION_DESTRUCTIVE', 'DB_PGMQ_DECLARED', 'DB_VAULT_WRITE', 'ENV_DUPLICATE', 'ENV_EXAMPLE_DRIFT', 'ENV_PUBLIC_SEALED', 'ENV_REQUIRED_UNSET', 'ENV_SEALED_UNREAD', 'ENV_VALUE_SHAPE', 'FE_STACK_CORE_MISSING', 'FE_STACK_UNLISTED', 'HFS_AGE_KEY_CUSTODY', 'HFS_APP_LEXICON', 'HFS_APP_WORKFLOW_TRIGGER', 'HFS_ASSET_KIND', 'HFS_ASSET_OVERSIZE', 'HFS_AUDIT_STEP_MISSING', 'HFS_CANON_COPY_DRIFT', 'HFS_CI_TOOL_INSTALL', 'HFS_COVERAGE_BELOW', 'HFS_DB_DEPLOY_UNGUARDED', 'HFS_DEPENDABOT_MISSING', 'HFS_DEPLOY_COMPOSE_ON_VPS', 'HFS_DEPLOY_NO_LOGIC', 'HFS_DEPLOY_SCHEDULER', 'HFS_DEPLOY_WORKFLOW', 'HFS_DOC_COMMAND_UNKNOWN', 'HFS_DOC_ENV_UNKNOWN', 'HFS_DOC_PATH_MISSING', 'HFS_DOC_RULE_UNKNOWN', 'HFS_FEATURE_FILE_BUDGET', 'HFS_HOST_CRON', 'HFS_RELEASE_TAG_MISMATCH', 'HFS_SBOM_MISSING', 'HFS_SCHEDULE_UNDECLARED', 'HFS_SCRIPT_PLAINTEXT_LOAD', 'HFS_SCRIPT_XTRACE', 'HFS_SECRET_OUTSIDE_ENC', 'HFS_SECRET_PLAINTEXT_FILE', 'HFS_SEED_PII', 'HFS_SERVICE_ROLE_SCOPE', 'HFS_UNUSED_SYMBOL', 'HFS_WORKFLOW_PIN', 'STACKS_DEPLOY_CONFIG_INVALID', 'STACKS_DNS_UNDECLARED', 'STACKS_HEALTHCHECK_MISSING', 'STACKS_HOST_UNROUTED', 'STACKS_INGRESS_UNDECLARED', 'STACKS_INGRESS_UNKNOWN', 'STACKS_LITE_SELFHOSTED_DB', 'STACKS_MODEL_UNAVAILABLE', 'STACKS_PLACEMENT_MISSING', 'STACKS_PORT_PUBLISHED', 'STACKS_REALTIME_SCALED', 'STACKS_RELEASE_UNDECLARED', 'STACKS_SECOND_INGRESS', 'STACKS_SECRET_ENV_LITERAL', 'STACKS_SECRET_NOT_EXTERNAL', 'STACKS_SECRET_UNVERSIONED', 'STACKS_SIDECAR_DB_UNSUPPORTED', 'STACKS_SIDECAR_VOLUME_UNDECLARED', 'STACKS_TLS_UNDECLARED', 'STACKS_UPDATE_POLICY_MISSING', 'STACK_TOOLING_REIMPLEMENTED',
   // codes-end
@@ -51,6 +53,7 @@ const FINDERS = [
   // finders-begin
   feBuildArgsFindings,
   workflowContextsFindings,
+  ciStandardAppFindings,
   featureFileFindings,
   lexiconFindings,
   assetsFindings,

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/secrets.mjs

@@ -7,7 +7,7 @@
 // A finding names the file, the line and the pattern, never the value.
 import fs from 'node:fs';
 import path from 'node:path';
-import { FORBIDDEN_FILES, secretHits } from '../../lib/secret-patterns.mjs';
+import { FORBIDDEN_FILES, secretHitsInFile } from '../../lib/secret-patterns.mjs';
 import { isSopsEnvelope } from '../../lib/sops-envelope.mjs';
 import { found, readText } from './read.mjs';
 
@@ -34,20 +34,17 @@ export function untrackedSecretFindings({ repoRoot, files, repo }) {
  * no sops envelope, or a line that matches a secret pattern. `text` is the file's text, or null when it cannot be read (binary, too
  * large, absent). The whole-tree check reads the work tree and the commit hook (`starci app hygiene`) reads the staged blob: one judgement.
  */
-export function secretFileFindings({ file, text }) {
+export function secretFileFindings({ file, text, manifestText }) {
   const being = FORBIDDEN_FILES.find((rule) => rule.test(file));
   if (being) return [found(PLAINTEXT_SECRET, file, `${file} is a plaintext secret by being (${being.name}); a secret is committed only as a sops envelope at .starcistacks/<env>/secrets/<slug>.enc`, { pattern: being.name })];
   if (text === null || text === undefined || NOT_SCANNED.test(file)) return [];
   if (file.endsWith('.enc')) return isSopsEnvelope(text) ? [] : [found(PLAINTEXT_SECRET, file, `${file} is named like a sealed secret but is not a sops envelope; encrypt the value with sops and commit only the envelope`, { pattern: 'sops-not-envelope' })];
   const findings = [];
-  const lines = text.split(/\r?\n/);
   const seen = new Set();
-  for (const [index, line] of lines.entries()) {
-    for (const pattern of secretHits(file, line)) {
-      if (seen.has(pattern)) continue;
-      seen.add(pattern);
-      findings.push(found(PLAINTEXT_SECRET, file, `${file}:${index + 1} holds a plaintext secret (${pattern}); seal it with sops at .starcistacks/<env>/secrets/<slug>.enc and read it by *_FILE`, { line: index + 1, pattern }));
-    }
+  for (const { line, pattern } of secretHitsInFile(file, text, { manifestText })) {
+    if (seen.has(pattern)) continue;
+    seen.add(pattern);
+    findings.push(found(PLAINTEXT_SECRET, file, `${file}:${line} holds a plaintext secret (${pattern}); seal it with sops at .starcistacks/<env>/secrets/<slug>.enc and read it by *_FILE`, { line, pattern }));
   }
   return findings;
 }
@@ -62,7 +59,8 @@ export function secretFindings({ repoRoot, files, resolver }) {
       findings.push(found(PLAINTEXT_SECRET, file, `${file} is a plaintext secret file tracked in ${slot.slot}${destination}`, { slot: slot.slot, goesTo: slot.goesTo }));
       continue;
     }
-    findings.push(...secretFileFindings({ file, text: readText(repoRoot, file) }));
+    const manifestText = /(?:^|\/)README\.md$/.test(file) ? readText(repoRoot, path.posix.join(path.posix.dirname(file), '.starcistacks/application-stacks.yaml')) : undefined;
+    findings.push(...secretFileFindings({ file, text: readText(repoRoot, file), manifestText }));
   }
   return findings;
 }

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/runtime/scripts/lib/secret-patterns.mjs

@@ -1,3 +1,5 @@
+import { parseYaml } from '../../engine/yaml.mjs';
+
 // secret-patterns.mjs — the one list of secret shapes the runtime refuses to carry: the push secret scan
 // (scripts/supervisor/push-mains.mjs scanDiff) refuses an outgoing range that adds one, and the typed-log
 // redaction (scripts/kernel/typed-logs.mjs redactText) blanks the value before a log row is stored.
@@ -102,3 +104,78 @@ export function secretHits(file, text) {
   }
   return names;
 }
+
+const BADGE_BEGIN = '<!-- >>> starci app sync (managed block; do not edit) >>> -->';
+const BADGE_END = '<!-- <<< starci app sync <<< -->';
+
+/** Provider-shaped credentials remain refused even where the keyword heuristic admits public badge tokens. */
+function blankBadgeValue(value) {
+  return secretHits('badge.mjs', value).length ? value : ' '.repeat(value.length);
+}
+
+/** Only scalar values at the two block-mapping service paths qualify; every other YAML substring remains scanned. */
+function manifestBadgeText(text) {
+  try { parseYaml(text); } catch { return text; }
+  const parents = [];
+  return text.split('\n').map(line => {
+    if (/^\s*(?:#.*)?$/.test(line)) return line;
+    const indent = /^ */.exec(line)[0].length;
+    while (parents.length && parents.at(-1).indent >= indent) parents.pop();
+    const match = /^( *)(?:([A-Za-z0-9_-]+)|"([A-Za-z0-9_-]+)"|'([A-Za-z0-9_-]+)'):(.*)$/.exec(line);
+    if (!match) { parents.push({ indent, key: null }); return line; }
+    match[5] = match[5].trimStart();
+    const key = match[2] ?? match[3] ?? match[4];
+    const keys = [...parents.map(parent => parent.key), key].join('.');
+    const container = /^(?:#.*)?$/.test(match[5].trim());
+    const nestedScalar = parents.some(parent => parent.container === false);
+    parents.push({ indent, key, container });
+    if (nestedScalar) return line;
+    if (!['services.codecov.badgeToken', 'services.sonar.badgeToken'].includes(keys)) return line;
+    const scalar = /^(?:"([A-Za-z0-9_-]{6,128})"|'([A-Za-z0-9_-]{6,128})'|([A-Za-z0-9_-]{6,128}))(?=\s*(?:#|$))/.exec(match[5]);
+    if (!scalar) return line;
+    const start = line.length - match[5].length;
+    return line.slice(0, start) + blankBadgeValue(scalar[0]) + match[5].slice(scalar[0].length);
+  }).join('\n');
+}
+
+/** Unreadable manifests admit only the default badge hosts; readable Sonar declarations select their own hosts. */
+function badgeHosts(manifestText) {
+  const hosts = new Set(['codecov.io']);
+  let doc;
+  try { doc = parseYaml(manifestText); } catch { hosts.add('sonarcloud.io'); return hosts; }
+  const sonar = doc?.services?.sonar;
+  if (sonar?.provider === 'sonarcloud') hosts.add('sonarcloud.io');
+  else for (const host of [sonar?.host?.public, sonar?.host?.local]) {
+    try { hosts.add(new URL(host).host); } catch { /* Invalid hosts admit nothing. */ }
+  }
+  return hosts;
+}
+
+/** Only token query values in managed Markdown badge images on declared hosts are blanked; links and other parameters remain scanned. */
+function readmeBadgeText(text, manifestText) {
+  const begin = text.indexOf(BADGE_BEGIN), end = text.indexOf(BADGE_END, begin + BADGE_BEGIN.length);
+  if (begin < 0 || end < 0) return text;
+  const hosts = badgeHosts(manifestText);
+  const start = begin + BADGE_BEGIN.length;
+  const block = text.slice(start, end).replace(/!\[[^\]\n]*\]\((https?:\/\/[^\s)]+)\)/g, (image, address) => {
+    let url;
+    try { url = new URL(address); } catch { return image; }
+    if (!hosts.has(url.host) || url.username || url.password) return image;
+    const badgePath = url.host === 'codecov.io' ? /\/graph\/badge\.svg$/.test(url.pathname) : url.pathname === '/api/project_badges/measure';
+    if (!badgePath) return image;
+    const fragment = address.indexOf('#');
+    const queryEnd = fragment < 0 ? address.length : fragment;
+    const safe = address.slice(0, queryEnd).replace(/([?&]token=)([^&#)\s]*)/g, (_, prefix, value) => prefix + blankBadgeValue(value));
+    return image.replace(address, () => safe + address.slice(queryEnd));
+  });
+  return text.slice(0, start) + block + text.slice(end);
+}
+
+/** Whole-file secret judgement exempts only declared public badge values and preserves original line numbers and every provider shape. */
+export function secretHitsInFile(file, fullText, { manifestText } = {}) {
+  const normalized = file.replace(/\\/g, '/');
+  let text = fullText;
+  if (/(?:^|\/)\.starcistacks\/application-stacks\.yaml$/.test(normalized)) text = manifestBadgeText(text);
+  if (/(?:^|\/)README\.md$/.test(normalized)) text = readmeBadgeText(text, manifestText);
+  return text.split(/\r?\n/).flatMap((line, index) => secretHits(file, line).map(pattern => ({ line: index + 1, pattern })));
+}

package/scaffold/app.mjs

@@ -222,7 +222,7 @@ const FE_PACKAGES = Object.freeze({
 const PACKAGE_WORKSPACE_SCRIPTS = Object.freeze({ build: 'tsc -p tsconfig.build.json', lint: WORKSPACE_LINT, typecheck: 'tsc --noEmit -p tsconfig.json' });
 
 /** The app hfs.json of a new app called `name`; full remains the byte-for-byte default declaration. */
-const starterDeclaration = (name, manifest = loadSlotManifest(), edition = 'full') => ({
+export const starterDeclaration = (name, manifest = loadSlotManifest(), edition = 'full') => ({
   hfs: manifest.major,
   kind: 'app',
   ...(edition === 'full' ? {} : { edition }),
@@ -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
@@ -493,7 +494,7 @@ export function scaffoldWorkSeeds(project) {
  * be side (once per product app of the fe side, coreFeApps), the be `apps/cli/` folder once when the cli app is declared, an fe `apps/<name>/` folder
  * once for the declared fe app <name> (none other), `__project__` in a path replaced by the project name.
  */
-function skeletonOf(scope, app, vars) {
+export function skeletonOf(scope, app, vars) {
   const files = app.edition === 'lite'
     ? [...skeletonDirectory(scope, 'skeleton', app, vars, rel => liteBaseFile(scope, rel)), ...skeletonDirectory(scope, 'skeleton-lite', app, vars, rel => liteOverlayFile(scope, rel))]
     : skeletonDirectory(scope, 'skeleton', app, vars);

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) {