@starci/hfs 4.7.17 → 4.7.18

package/CHANGELOG.md

@@ -1,11 +1,15 @@
 # Changelog
 
-## 4.7.17 - 2026-10-21
+## 4.7.18 - 2026-10-21
+- Changed: supersedes 4.7.17, published from a lane whose history the owner refused (an unapproved allowlist entry) and therefore a superseded orphan that is not used; this version carries the same work plus the standalone scaffold fix.
+- Fixed: the managed CI's coverage job runs `starci app coverage verify <lcov>`, the coverage judgement alone over the merged report, instead of `npm run codegen && starci app check --coverage-from` (the whole app check the fast and lint jobs already ran); its default timeout is 15 minutes (`knowledge/hfs/ci-standard.yaml`). NIVO v0.3.0's coverage job took 18m43s of 20 and the tag run was cancelled.
 - Fixed: the sonar row of `starci app release gate --sonar` no longer passes on the scanner's exit code alone: it reads `.scannerwork/report-task.txt`, polls `api/ce/task` until the analysis ends and reads `api/qualitygates/project_status` with the same token; ERROR is red as `RELEASE_SONAR_GATE_FAILED` naming each failed condition, a 600-second wait is `RELEASE_SONAR_GATE_TIMEOUT` and an unreadable answer `RELEASE_SONAR_GATE_UNREADABLE`; canon pins follow the matching package cohort.
 
-- Fixed: `npx @starci/cli app scaffold` works from the published packages alone: the Sonar exclusions come from the jest preset copy @starci/hfs ships (`runtime/packages/jest-preset/sonar-exclusions.json`, `bundledPresets`), not from a @starci/jest-preset installed beside the CLI (it was `HFS_SYNC_PRESET_MISSING`); `starci app upgrade` reads the same copy instead of a hand-kept list.
+- Fixed: `npx @starci/cli app scaffold` works from the published packages alone: the Sonar exclusions come from the jest preset copy @starci/hfs ships (`runtime/packages/jest-preset/sonar-exclusions.cjs`, `bundledPresets`), not from a @starci/jest-preset installed beside the CLI (it was `HFS_SYNC_PRESET_MISSING`); `starci app upgrade` reads the same copy instead of a hand-kept list.
 - Fixed: a new scaffold path is git-initialised with an unborn main before any file is written (`HFS_SCAFFOLD_GIT_INIT_FAILED` when git cannot), as the verb promised, so `starci npm ci` can install the hooks; an existing empty unborn main repository is still accepted.
 
+- Fixed: `BE_UNIT_SPEC_NOT_STAGED` exempts a measured file with nothing to execute (constants and types only), which has nothing a spec could call and whose spec the spec rules refuse; every measured file with a function, method, constructor or accessor still needs its spec staged beside it. It refused the scaffold's own first commit on the constant-only `http-status.policy.ts`; the scaffold now also ships `migrate-connections.client.spec.ts`.
+
 ## 4.7.16 - 2026-10-21
 - Fixed: `DB_MIGRATION_DESTRUCTIVE` counts a be/src source as a reference of a dropped or altered column only when the source names the column's table too, so a same-named column of another table (`public.brain_lessons.origin` beside a drop of `transactions.origin`) no longer blocks a contract migration; table and other object drops keep the leaf match; canon pins follow the matching package cohort.
 

package/coverage/cli.mjs

@@ -3,14 +3,18 @@
 // coverage proof, the Codecov upload and the Sonar import read. The merge is the app's installed @starci/jest-preset (`@starci/jest-preset/merge`):
 // istanbul-lib-coverage merges the shard maps by source location, and the preset's own lcov reporter writes the result exactly as an unsharded run
 // would. A path is a coverage-final.json or a directory searched for every one below it; no report found refuses (exit 2), never an empty report.
+// `starci app coverage verify <lcov>`: the coverage proof alone (scripts/hfs/coverage-from.mjs, the judgement `starci app check --coverage-from`
+// adds to the whole check): every measured logic file is in the merged lcov at 100 per file. The managed CI's coverage job runs it after the merge,
+// so the job re-runs none of the rules the fast and lint jobs already judged. Exit 0 proved, 1 refused (the report lists every finding), 2 bad usage.
 import path from 'node:path';
 import { createRequire } from 'node:module';
+import { coverageFrom, formatCoverageReport } from '../runtime/scripts/hfs/coverage-from.mjs';
 
-const USAGE = 'usage: starci app coverage merge --out <lcov> <coverage-final.json-or-dir>... [--cwd <dir>]';
+const USAGE = 'usage: starci app coverage merge --out <lcov> <coverage-final.json-or-dir>... [--cwd <dir>] | starci app coverage verify <lcov> [--cwd <dir>]';
 
 function parse(argv) {
   const [action, ...rest] = argv;
-  if (action !== 'merge') throw new Error(USAGE);
+  if (action !== 'merge' && action !== 'verify') throw new Error(USAGE);
   const opts = { inputs: [] };
   for (let index = 0; index < rest.length; index += 1) {
     const arg = rest[index];
@@ -22,6 +26,11 @@ function parse(argv) {
     } else if (arg.startsWith('--')) throw new Error(`unknown flag ${arg}; ${USAGE}`);
     else opts.inputs.push(arg);
   }
+  opts.action = action;
+  if (action === 'verify') {
+    if (opts.out !== undefined || opts.inputs.length !== 1) throw new Error(USAGE);
+    return opts;
+  }
   if (!opts.out || !opts.inputs.length) throw new Error(USAGE);
   if (path.basename(opts.out) !== 'lcov.info') throw new Error(`--out names the lcov.info the coverage proof reads; ${USAGE}`);
   return opts;
@@ -34,11 +43,27 @@ function installedMerge(cwd) {
   }
 }
 
-/** Exit 0 merged, 2 bad usage, no preset or no report found. `merge` replaces the installed preset merge in a spec. */
-export async function coverageMain(argv, { cwd: baseCwd = process.cwd(), stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), merge } = {}) {
+/** The coverage proof of the app at `cwd` over the lcov `report`: exit 0 proved, 1 refused, 2 when the proof cannot run. */
+function verifyCoverage(cwd, report, { stdout, stderr, prove }) {
+  try {
+    const result = prove({ repoRoot: cwd, coverageFrom: report });
+    stdout(formatCoverageReport(result));
+    return result.ok ? 0 : 1;
+  } catch (error) {
+    stderr(`starci app coverage verify: ${String(error?.message ?? error).split('\n')[0]}\n`);
+    return 2;
+  }
+}
+
+/**
+ * Exit 0 merged or proved, 1 a refused proof, 2 bad usage, no preset or no report found. `merge` replaces the installed preset merge and
+ * `prove` the coverage proof in a spec.
+ */
+export async function coverageMain(argv, { cwd: baseCwd = process.cwd(), stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), merge, prove = coverageFrom } = {}) {
   let opts;
   try { opts = parse(argv); } catch (error) { stderr(`starci app coverage: ${error.message}\n`); return 2; }
   const cwd = path.resolve(baseCwd, opts.cwd ?? '.');
+  if (opts.action === 'verify') return verifyCoverage(cwd, opts.inputs[0], { stdout, stderr, prove });
   try {
     const run = merge ?? installedMerge(cwd);
     const outDir = path.dirname(path.resolve(cwd, opts.out));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.7.17",
+  "version": "4.7.18",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -29,14 +29,14 @@ pins:
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.4.25
+    version: 3.4.26
     group: starci
     install: registry
     side: be
     source: packages/eslint/be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 8.4.24
+    version: 8.4.25
     group: starci
     install: registry
     side: fe
@@ -62,7 +62,7 @@ pins:
     side: both
     source: packages/prettier-config/package.json
   '@starci/jest-preset':
-    version: 2.3.3
+    version: 2.3.4
     group: starci
     install: registry
     side: be
@@ -76,14 +76,14 @@ pins:
     source: packages/test-world/package.json
     why: 'the shared e2e library of every back end (R47, R48), a devDependency of every back end: the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs and the outage lock. Kafka is real own infra (the one digest-pinned apache/kafka KRaft image, a broker listener and proxy per slot, slot-prefixed topics, consumer groups and client ids) and Postgres is schema-per-context (a schema and a login role per context in a shared database). Each worker has its own data slot (<ns>_w<k>) with its own databases, Keycloak realm, leased Redis DB, bucket/collection/topic prefixes, fakes host, toxiproxy proxies and outage lock; a run provisions min(jest workers, workers cap, default 2) slots, and state file protocol 2 pairs exactly with @starci/jest-preset (TEST_WORLD_PAIR_MISMATCH otherwise). A modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client, world.keycloak.events/sessions read the realm user events and live sessions, world.infra.postgresql.connection(name) takes one database connection down while the others serve, and world.resolve and scope.resolve take any Nest token. Every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json); the globalSetup registers the path aliases as TypeScript resolves them. Its CLI main is exported at ./cli for starci app stack.'
   '@starci/cli':
-    version: 1.7.17
+    version: 1.7.18
     group: starci
     install: registry
     side: both
     source: packages/cli/package.json
     why: 'the only StarCi command package; product repositories install it for starci app, while @starci/hfs remains its pinned transitive implementation.'
   '@starci/hfs':
-    version: 4.7.17
+    version: 4.7.18
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/ci-standard.yaml

@@ -19,15 +19,17 @@ jobs:
 # The per-job settings the managed CI renders when .starcistacks/application-stacks.yaml ci.jobs leaves them out (ci.jobs.<job>.timeoutMinutes,
 # ci.jobs.test.shards). Sized from a real run (NIVO v0.2.3 on the 2-vCPU GitHub runner, 2026-10-18): the be lint with the Sonar import took 11.5 minutes and the
 # fe lint more than 8 in one 20-minute job, and ~900 unit suites ran at ~4 s each (670 of 904 in 45 minutes). One lint job per side, and 6 shards of ~150 suites
-# (~10 minutes each plus the install) leave each job well inside its timeout.
+# (~10 minutes each plus the install) leave each job well inside its timeout. The coverage job installs, downloads the shards, merges them and runs
+# the coverage judgement alone (starci app coverage verify, seconds): ~5 minutes, so 15 leaves three times that. Its earlier whole app check took
+# 18m43s on NIVO v0.3.0 and the 20-minute bound cancelled the tag run (39592175266).
 defaults:
   shards: 6
-  timeoutMinutes: {fast: 20, lint: 30, test: 25, coverage: 20, build: 30, sonar: 20, db-types: 30}
+  timeoutMinutes: {fast: 20, lint: 30, test: 25, coverage: 15, build: 30, sonar: 20, db-types: 30}
 
 # The steps that need a raised Node heap on the GitHub runner, matched on their `run` text, and the least heap they must declare in NODE_OPTIONS.
 heap:
   minMiB: 6144
-  steps: ['npm run typecheck', 'npm run lint', 'app lint', 'app check --coverage-from', 'npm run db:lint']
+  steps: ['npm run typecheck', 'npm run lint', 'app lint', 'app coverage verify', 'npm run db:lint']
 
 items:
   - id: candidate-trigger

package/runtime/modules/kernel/failure-codes.yaml

@@ -1608,7 +1608,7 @@ BE_TYPE_ESCAPE:
 BE_UNIT_SPEC_NOT_STAGED:
   title: "A new back-end logic file is committed without its unit spec"
   title_vi: "Tệp logic back-end mới được commit mà không có unit spec"
-  meaning_vi: "Commit thêm `<file>`, một tệp `<name>.<role>.ts` có vai trò logic mà unit coverage đo ở mức 100 mỗi tệp, nhưng index không có `<name>.<role>.spec.ts` bên cạnh nó: mã được viết trước, spec để sau."
+  meaning_vi: "Commit thêm `<file>`, một tệp `<name>.<role>.ts` có vai trò logic mà unit coverage đo ở mức 100 mỗi tệp, nhưng index không có `<name>.<role>.spec.ts` bên cạnh nó: mã được viết trước, spec để sau. Tệp chỉ có hằng số và kiểu (không có hàm, phương thức nào để chạy) không cần spec riêng."
   causes_vi:
     - "Agent viết mã trước rồi định sửa lint và spec sau, thay vì chạy vòng op `starci gate read` → mã + spec → `starci gate run`"
     - "Spec đã viết nhưng chưa được stage cùng tệp"

package/runtime/packages/cli/src/catalog.generated.mjs

@@ -1,7 +1,7 @@
 // GENERATED by scripts/cli/gen-catalog.mjs — do not edit
 export const CATALOG = {
   "schema": "starci/cli-catalog@1",
-  "hash": "ce01a03c949f8154644bec5d1068bf0b5316478f328b2231b2369c937f89e118",
+  "hash": "2ad45b29a66fee7ac961e8546613e0455d23cc47e28a5070bd15b86154755dd8",
   "global": [
     {
       "name": "json",
@@ -790,13 +790,14 @@ export const CATALOG = {
           "runtimeSide": "host"
         },
         "coverage": {
-          "summary": "merge the coverage of the sharded unit run into one lcov report",
+          "summary": "merge the sharded unit coverage into one lcov report, or prove that report at 100 per file",
           "owner": "@starci/hfs",
           "positional": [
             {
               "name": "action",
               "enum": [
-                "merge"
+                "merge",
+                "verify"
               ],
               "required": true,
               "variadic": false
@@ -820,12 +821,14 @@ export const CATALOG = {
             }
           ],
           "exit": {
-            "0": "merged",
+            "0": "merged or proved",
+            "1": "the coverage proof refused a measured file",
             "2": "bad usage, no installed preset or no report found"
           },
           "json": "none",
           "examples": [
-            "starci app coverage merge --out be/coverage/lcov.info be/coverage/shards"
+            "starci app coverage merge --out be/coverage/lcov.info be/coverage/shards",
+            "starci app coverage verify be/coverage/lcov.info"
           ],
           "editions": [
             "full",
@@ -838,7 +841,8 @@ export const CATALOG = {
             "merge runs the app's installed @starci/jest-preset/merge: istanbul-lib-coverage joins the shard maps by source location",
             "the merged lcov is written by the preset's own lcov reporter, as an unsharded run writes it",
             "a path is a coverage-final.json or a directory searched for every one below it; no report found refuses (exit 2)",
-            "the coverage proof (starci app check --coverage-from) refuses a measured file the merge does not hold"
+            "verify <lcov> is the coverage proof alone: every measured logic file in the report at 100 per file, a missing one refused",
+            "verify runs none of the other rules of starci app check; the managed CI coverage job runs it after the merge"
           ],
           "runtimeSide": "host"
         },

package/runtime/packages/jest-preset/sonar-exclusions.cjs

@@ -0,0 +1,8 @@
+"use strict"
+
+/**
+ * Sonar `sonar.exclusions`: specs, e2e specs, dist and coverage output are not analysed at all. A plain list with no require, so
+ * @starci/hfs ships this file byte for byte (packages/hfs/runtime, scripts/hfs/sync-runtime.mjs) and `starci app scaffold` renders
+ * the same exclusions before any app dependency is installed.
+ */
+module.exports = Object.freeze(["**/*.spec.ts", "**/*.e2e-spec.ts", "**/dist/**", "**/coverage/**"])

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

@@ -28,6 +28,9 @@ const DIGEST_PIN = /@sha256:[0-9a-f]{64}$/;
 
 let cached = null;
 /** The standard (knowledge/hfs/ci-standard.yaml), read once. */
+/** The coverage proof step: the coverage judgement over the merged lcov (`starci app coverage verify`), never the whole app check. */
+const COVERAGE_PROOF = /app coverage verify\b/;
+
 function ciStandard() {
   if (!cached) {
     const doc = parseYaml(fs.readFileSync(STANDARD_FILE, 'utf8'));
@@ -56,7 +59,7 @@ function jobShape(doc, edition, standard, say) {
   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)));
+  const proof = withStep((step) => COVERAGE_PROOF.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(', ')}`));
@@ -79,7 +82,7 @@ function testSharding(doc, say) {
   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)));
+  const proof = coverage.findIndex((step) => COVERAGE_PROOF.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;
 }

package/runtime/scripts/hfs/rules/staged-specs.mjs

@@ -1,8 +1,11 @@
 // staged-specs.mjs - BE_UNIT_SPEC_NOT_STAGED (R47): the commit that adds a back-end logic file adds its unit spec beside it. A new
 // file `be/<path>/<name>.<role>.ts` that the coverage scope measures (scripts/hfs/coverage-scope.mjs isMeasured: a role of
-// ruleParams.be.logicRoles below a measured root, outside its none folders) needs `<name>.<role>.spec.ts` in the same index.
-// `starci app hygiene` judges the files the index adds (packages/hfs/sync/hygiene.mjs, run by the managed pre-commit hook), so a
-// coding agent cannot commit the code first and its spec afterwards. A file that already exists is the coverage gate's.
+// ruleParams.be.logicRoles below a measured root, outside its none folders) and that holds executable logic (a function, a method, a
+// constructor, an accessor) needs `<name>.<role>.spec.ts` in the same index. A measured file with nothing to execute (constants and
+// types only, such as an error-kind to HTTP-status table) has nothing a spec could call, and the spec rules refuse a spec of it
+// (spec-infra-double-from-kit); the coverage gate still reaches it through its callers. `starci app hygiene` judges the files the
+// index adds (packages/hfs/sync/hygiene.mjs, run by the managed pre-commit hook), so a coding agent cannot commit the code first and
+// its spec afterwards. A file that already exists is the coverage gate's.
 import { isMeasured } from '../coverage-scope.mjs';
 
 const SPEC_NOT_STAGED = 'BE_UNIT_SPEC_NOT_STAGED';
@@ -11,13 +14,30 @@ const BE = 'be/';
 /** The unit spec beside an app-relative `<name>.<role>.ts`: `<name>.<role>.spec.ts`. */
 const siblingSpec = (file) => file.replace(/\.ts$/u, '.spec.ts');
 
+/** The syntax kinds that execute: a body a spec can call. */
+const EXECUTABLE_KINDS = ['FunctionDeclaration', 'FunctionExpression', 'ArrowFunction', 'MethodDeclaration', 'Constructor', 'GetAccessor', 'SetAccessor'];
+
+/**
+ * Whether TypeScript `text` holds executable logic. Without a TypeScript parser (`ts` null) or without the text, the file counts as
+ * logic: the gate never relaxes on what it cannot read.
+ */
+function holdsLogic(ts, text) {
+  if (!ts || typeof text !== 'string') return true;
+  const kinds = new Set(EXECUTABLE_KINDS.map((name) => ts.SyntaxKind[name]));
+  const source = ts.createSourceFile('subject.ts', text, ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);
+  const visit = (node) => kinds.has(node.kind) || ts.forEachChild(node, visit) === true;
+  return ts.forEachChild(source, visit) === true;
+}
+
 /**
  * The findings `{ file, code, message }` of the app-relative files the index adds (`added`) whose sibling spec is not among the
- * paths the index holds (`indexed`, a Set). `manifest` is the slot manifest the coverage scope reads.
+ * paths the index holds (`indexed`, a Set). `manifest` is the slot manifest the coverage scope reads; `staged(file)` answers the
+ * staged text of a file and `ts` the TypeScript parser, which tell a logic file from a constants-only one.
  */
-export function stagedSpecFindings(manifest, added, indexed) {
+export function stagedSpecFindings(manifest, added, indexed, { ts = null, staged = () => null } = {}) {
   return added
     .filter((file) => file.startsWith(BE) && !file.endsWith('.spec.ts') && isMeasured(manifest, file.slice(BE.length)) && !indexed.has(siblingSpec(file)))
+    .filter((file) => holdsLogic(ts, staged(file)))
     .map((file) => ({
       file,
       code: SPEC_NOT_STAGED,

package/sync/ci-commands.mjs

@@ -1,275 +1,276 @@
-import fs from 'node:fs';
-import { parseYaml } from '../runtime/engine/yaml.mjs';
-import { refusal } from '../stack/errors.mjs';
-import { byCodeUnit } from '../report/order.mjs';
-
-// One command vocabulary for managed CI rendering and the runtime coverage gate.
-const exampleCommand = (source, command) => source?.runtimeExample
-  ? 'node node_modules/@starci/hfs/runtime/scripts/hfs/example-secrets.mjs --run . -- ' + command
-  : command;
-
-const UPLOAD_ARTIFACT = 'actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2';
-const DOWNLOAD_ARTIFACT = 'actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0';
-const SONAR_CONDITION = "${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') && env.SONAR_TOKEN != '' }}";
-
-/** Optional uploads require reachable upload and authentication endpoints without exposing identity tokens. */
-function codecovProbe(codecov, condition) {
-  if (!codecov.optional) return [];
-  return [
-    '      - name: Codecov availability',
-    '        id: codecov-availability',
-    `        if: ${condition}`,
-    '        env:',
-    `          CODECOV_AUTH: ${codecov.auth}`,
-    '        run: |',
-    "          node --input-type=module <<'NODE'",
-    "          import fs from 'node:fs';",
-    '          let available = false;',
-    '          try {',
-    "            const upload = await fetch('https://ingest.codecov.io/upload/v4', { signal: AbortSignal.timeout(10000) });",
-    '            available = upload.status < 500;',
-    "            if (available && process.env.CODECOV_AUTH === 'oidc') {",
-    "              const url = new URL(process.env.ACTIONS_ID_TOKEN_REQUEST_URL);",
-    "              url.searchParams.set('audience', 'https://codecov.io');",
-    "              const identity = await fetch(url, { headers: { Authorization: 'Bearer ' + process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN }, signal: AbortSignal.timeout(10000) });",
-    '              available = identity.ok && Boolean((await identity.json()).value);',
-    '            }',
-    '          } catch { available = false; }',
-    "          fs.appendFileSync(process.env.GITHUB_OUTPUT, 'up=' + available + '\\n');",
-    "          if (!available) console.log('::notice::codecov upload skipped: upload endpoint or OIDC token unavailable (services.codecov.optional)');",
-    '          NODE',
-  ];
-}
-
-/** Optional Sonar only runs analysis when the provider reports UP within ten seconds. */
-function sonarProbe(sonar) {
-  if (!sonar.optional) return [];
-  return [
-    '      - name: Sonar availability',
-    '        id: sonar-availability',
-    `        if: ${SONAR_CONDITION}`,
-    '        run: |',
-    `          if curl -fsS --max-time 10 "$SONAR_HOST_URL/api/system/status" | node -e "let s='';process.stdin.on('data',c=>s+=c);process.stdin.on('end',()=>{try{process.exit(JSON.parse(s).status==='UP'?0:1)}catch{process.exit(1)}})"; then`,
-    '            echo "up=true" >> "$GITHUB_OUTPUT"',
-    '          else',
-    '            echo "up=false" >> "$GITHUB_OUTPUT"',
-    '            echo "::notice::sonar skipped: $SONAR_HOST_URL not reachable (services.sonar.optional)"',
-    '          fi',
-  ];
-}
-
-/** Codecov reports missing coverage without failing twice; uploads retain the release-tag condition and required authentication. */
-function codecovSteps(lcovReport, codecov) {
-  if (codecov.enabled === false || codecov.wiring === 'not-used') return [
-    '      - name: coverage upload',
-    '        run: echo "codecov disabled in .starcistacks/application-stacks.yaml"',
-  ].join('\n');
-  const condition = `\${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') && hashFiles('${lcovReport}') != '' }}`;
-  const uploadCondition = codecov.optional ? condition.replace(' }}', " && steps.codecov-availability.outputs.up == 'true' }}") : condition;
-  return [
-    '      - name: coverage upload skipped',
-    `        if: \${{ !cancelled() && hashFiles('${lcovReport}') == '' }}`,
-    '        run: |',
-    `          echo "::notice::codecov upload skipped: no coverage file at ${lcovReport} (the test step failed or produced none)"`,
-    '          exit 0',
-    ...codecovProbe(codecov, condition),
-    '      - name: coverage upload',
-    ...(codecov.optional ? ['        id: codecov-upload', '        continue-on-error: true'] : []),
-    '        uses: codecov/codecov-action@0fb7174895f61a3b6b78fc075e0cd60383518dac # v5.5.5',
-    `        if: ${uploadCondition}`,
-    '        with:',
-    codecov.auth === 'token' ? `          token: \${{ secrets.${codecov.token} }}` : '          use_oidc: true',
-    `          files: ${lcovReport}`,
-    '          disable_search: true',
-    `          fail_ci_if_error: ${!codecov.optional}`,
-    ...(codecov.optional ? [
-      '      - name: Codecov upload unavailable',
-      "        if: ${{ !cancelled() && steps.codecov-upload.outcome == 'failure' }}",
-      '        run: |',
-      '          echo "::notice::codecov upload skipped: upload unavailable (services.codecov.optional)"',
-    ] : []),
-  ].join('\n');
-}
-
-/** Sonar consumes the test coverage and fast lint artifacts only on release tags with a configured token. */
-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: [lint, coverage]',
-    `    timeout-minutes: ${timeout}`,
-    '    runs-on: ubuntu-latest',
-    '    env:',
-    `      SONAR_TOKEN: \${{ secrets.${sonar.token} }}`,
-    `      SONAR_HOST_URL: ${host}`,
-    '    steps:',
-  ].join('\n');
-  const steps = [
-    ...sonarProbe(sonar),
-    `      - uses: ${DOWNLOAD_ARTIFACT}`,
-    `        if: ${condition}`,
-    '        with:',
-    `          name: ${lcovArtifact}`,
-    `          path: ${lcovReport.split('/').slice(0, -1).join('/') || '.'}`,
-    `      - uses: ${DOWNLOAD_ARTIFACT}`,
-    `        if: ${condition}`,
-    '        with:',
-    '          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',
-    `        if: ${condition}`,
-    '        timeout-minutes: 10',
-  ].join('\n');
-  // Variable strings are inserted after render() expands partials, so resolve Sonar's shared install partial before insertion.
-  const read = name => fs.readFileSync(new URL('../templates/app/ci-workflows/' + name, import.meta.url), 'utf8').replaceAll('\r\n', '\n');
-  return read('sonar-steps.yml')
-    .replace('{{> app/ci-workflows/install-steps.yml}}', () => read('install-steps.yml').trimEnd())
-    .replaceAll('{{nodeMajor}}', nodeMajor)
-    .replace('{{sonarJobHeader}}', () => header)
-    .replace('{{sonarJobSteps}}', () => steps)
-    .trimEnd() + '\n';
-}
-
-/** The app source reader is be-relative; the authored manifest lives one directory above that side. */
-function buildDeclaration(source) {
-  if (!source?.read) return {};
-  try {
-    return parseYaml(source.read('../.starcistacks/application-stacks.yaml')) ?? {};
-  } catch (error) {
-    if (error.code === 'ENOENT') return {};
-    throw error;
-  }
-}
-
-/** Static CI values are strings with valid environment names; expressions cannot turn public config into runtime secret reads. */
-function mergeBuildValues(values, entries) {
-  for (const [key, value] of Object.entries(entries ?? {})) {
-    if (!/^[A-Z][A-Z0-9_]*$/u.test(key) || typeof value !== 'string' || value.includes('${{')) {
-      throw refusal('STACK_BUILD_ARG_INVALID', 'CI build values must map environment names to literal strings');
-    }
-    if (values.has(key) && values.get(key) !== value) {
-      throw refusal('STACK_BUILD_ARG_INVALID', 'CI build values disagree for ' + key);
-    }
-    values.set(key, value);
-  }
-}
-
-/** Image values own their keys; the build-fe gate supplies only missing keys, and sealed members stay unopened. */
-function imageBuildEnv(image, gates) {
-  const values = new Map();
-  mergeBuildValues(values, image?.buildArgs?.values);
-  const fallback = new Map();
-  for (const gate of gates.filter(entry => entry.name === 'build-fe')) mergeBuildValues(fallback, gate.env);
-  for (const [key, value] of fallback) if (!values.has(key)) values.set(key, value);
-  if (!values.size) return '';
-  return ['        env:', ...[...values.keys()].sort(byCodeUnit).map(key => '          ' + key + ': ' + JSON.stringify(values.get(key)))].join('\n');
-}
-
-/** Multiple deployed front ends build separately through the installed turbo (a run step has no node_modules/.bin on PATH), so each fe/apps/<app> and its dependencies see its own public values. */
-function frontendBuild(source, app) {
-  const declaration = buildDeclaration(source);
-  const environments = Object.keys(source?.stack?.imageEnvironments ?? {});
-  const environment = environments.length > 1 ? 'production' : environments[0];
-  const images = Object.values(declaration.environments?.[environment]?.deploy?.images ?? {});
-  const frontend = images.filter(image => app?.sides.fe.apps.some(entry => entry.name === image.app));
-  const gates = declaration.release?.gates ?? [];
-  const singleEnv = imageBuildEnv(frontend[0], gates);
-  if (frontend.length <= 1) return { env: singleEnv, steps: ['      - name: build fe', '        run: npm run build:fe', singleEnv].filter(Boolean).join('\n') };
-  const steps = frontend.map(image => [
-    '      - name: build fe ' + image.app,
-    '        run: npm run codegen --silent && npx --no-install turbo run build --filter=./fe/apps/' + image.app,
-    imageBuildEnv(image, gates),
-  ].filter(Boolean).join('\n')).join('\n');
-  return { env: singleEnv, steps };
-}
-
-/** 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. The local release gate writes the same file with mergeSonarReports (release/lint-report.mjs): keep both identical. */
-function sonarMergeSteps(condition) {
-  return [
-    '      - name: merge Sonar lint reports',
-    `        if: ${condition}`,
-    '        run: |',
-    "          node --input-type=module <<'NODE'",
-    "          import fs from 'node:fs';",
-    "          const files = ['reports/lint.be.sonar.json', 'reports/lint.fe.sonar.json'];",
-    "          const reports = files.filter(file => fs.existsSync(file)).map(file => JSON.parse(fs.readFileSync(file, 'utf8')));",
-    '          const rules = [...new Map(reports.flatMap(report => report.rules).map(rule => [rule.id, rule])).values()];',
-    '          const issues = reports.flatMap(report => report.issues);',
-    "          fs.mkdirSync('reports', { recursive: true });",
-    "          fs.writeFileSync('reports/lint.sonar.json', JSON.stringify({ rules, issues }, null, 2) + '\\n');",
-    '          NODE',
-  ];
-}
-
-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, heap } = parseYaml(fs.readFileSync(STANDARD, 'utf8'));
-  const jobs = declaration?.ci?.jobs ?? {};
-  const timeout = (job) => String(jobs[job]?.timeoutMinutes ?? defaults.timeoutMinutes[job]);
-  const shards = Number(jobs.test?.shards ?? defaults.shards);
-  return {
-    nodeOptions: `--max-old-space-size=${heap.minMiB}`,
-    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;
-  const sonar = configuredSonar?.wiring === 'not-used' || configuredSonar?.mode === 'disabled' ? null : configuredSonar;
-  const codecov = quality?.codecov ?? { enabled: true, auth: 'oidc' };
-  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('/'),
-    // The istanbul JSON a shard writes beside the lcov (STARCI_COVERAGE_SHARD=1): what the coverage job merges.
-    shardCoverageReport: lcovReport.split('/').slice(0, -1).concat('coverage-final.json').join('/'),
-    ciBuildEnv: build.env,
-    ciBuildSteps: build.steps,
-    ciLint: exampleCommand(source, 'npm run lint'),
-    ciLintSonar: exampleCommand(source, 'npm run lint -- --sonar reports/lint.sonar.json'),
-    ciCoverageProof: 'npm run codegen --silent && ' + exampleCommand(source, 'npx starci app check --coverage-from ' + lcovReport),
-    ciDatabaseLint: exampleCommand(source, 'npm run db:lint'),
-    auditCommand: `npm audit${audit.omitDev ? ' --omit=dev' : ''} --audit-level=${audit.level}`,
-    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: [
-      '      - name: lint',
-      ...(sonar ? ["        if: env.SONAR_TOKEN == ''"] : []),
-      `        run: ${exampleCommand(source, 'npm run lint -- --side ' + side)}`,
-      '        env:',
-      `          NODE_OPTIONS: ${settings.nodeOptions}`,
-      ...(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: ${settings.nodeOptions}`,
-        `      - uses: ${UPLOAD_ARTIFACT}`,
-        // 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-${side}`,
-        `          path: reports/lint.${side}.sonar.json`,
-      ] : []),
-    ].join('\n'),
-    codecovSteps: codecovSteps(lcovReport, codecov),
-    sonarJob: sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor, settings.timeoutSonar),
-    lcovArtifact,
-  };
-}
+import fs from 'node:fs';
+import { parseYaml } from '../runtime/engine/yaml.mjs';
+import { refusal } from '../stack/errors.mjs';
+import { byCodeUnit } from '../report/order.mjs';
+
+// One command vocabulary for managed CI rendering and the runtime coverage gate.
+const exampleCommand = (source, command) => source?.runtimeExample
+  ? 'node node_modules/@starci/hfs/runtime/scripts/hfs/example-secrets.mjs --run . -- ' + command
+  : command;
+
+const UPLOAD_ARTIFACT = 'actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2';
+const DOWNLOAD_ARTIFACT = 'actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0';
+const SONAR_CONDITION = "${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') && env.SONAR_TOKEN != '' }}";
+
+/** Optional uploads require reachable upload and authentication endpoints without exposing identity tokens. */
+function codecovProbe(codecov, condition) {
+  if (!codecov.optional) return [];
+  return [
+    '      - name: Codecov availability',
+    '        id: codecov-availability',
+    `        if: ${condition}`,
+    '        env:',
+    `          CODECOV_AUTH: ${codecov.auth}`,
+    '        run: |',
+    "          node --input-type=module <<'NODE'",
+    "          import fs from 'node:fs';",
+    '          let available = false;',
+    '          try {',
+    "            const upload = await fetch('https://ingest.codecov.io/upload/v4', { signal: AbortSignal.timeout(10000) });",
+    '            available = upload.status < 500;',
+    "            if (available && process.env.CODECOV_AUTH === 'oidc') {",
+    "              const url = new URL(process.env.ACTIONS_ID_TOKEN_REQUEST_URL);",
+    "              url.searchParams.set('audience', 'https://codecov.io');",
+    "              const identity = await fetch(url, { headers: { Authorization: 'Bearer ' + process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN }, signal: AbortSignal.timeout(10000) });",
+    '              available = identity.ok && Boolean((await identity.json()).value);',
+    '            }',
+    '          } catch { available = false; }',
+    "          fs.appendFileSync(process.env.GITHUB_OUTPUT, 'up=' + available + '\\n');",
+    "          if (!available) console.log('::notice::codecov upload skipped: upload endpoint or OIDC token unavailable (services.codecov.optional)');",
+    '          NODE',
+  ];
+}
+
+/** Optional Sonar only runs analysis when the provider reports UP within ten seconds. */
+function sonarProbe(sonar) {
+  if (!sonar.optional) return [];
+  return [
+    '      - name: Sonar availability',
+    '        id: sonar-availability',
+    `        if: ${SONAR_CONDITION}`,
+    '        run: |',
+    `          if curl -fsS --max-time 10 "$SONAR_HOST_URL/api/system/status" | node -e "let s='';process.stdin.on('data',c=>s+=c);process.stdin.on('end',()=>{try{process.exit(JSON.parse(s).status==='UP'?0:1)}catch{process.exit(1)}})"; then`,
+    '            echo "up=true" >> "$GITHUB_OUTPUT"',
+    '          else',
+    '            echo "up=false" >> "$GITHUB_OUTPUT"',
+    '            echo "::notice::sonar skipped: $SONAR_HOST_URL not reachable (services.sonar.optional)"',
+    '          fi',
+  ];
+}
+
+/** Codecov reports missing coverage without failing twice; uploads retain the release-tag condition and required authentication. */
+function codecovSteps(lcovReport, codecov) {
+  if (codecov.enabled === false || codecov.wiring === 'not-used') return [
+    '      - name: coverage upload',
+    '        run: echo "codecov disabled in .starcistacks/application-stacks.yaml"',
+  ].join('\n');
+  const condition = `\${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') && hashFiles('${lcovReport}') != '' }}`;
+  const uploadCondition = codecov.optional ? condition.replace(' }}', " && steps.codecov-availability.outputs.up == 'true' }}") : condition;
+  return [
+    '      - name: coverage upload skipped',
+    `        if: \${{ !cancelled() && hashFiles('${lcovReport}') == '' }}`,
+    '        run: |',
+    `          echo "::notice::codecov upload skipped: no coverage file at ${lcovReport} (the test step failed or produced none)"`,
+    '          exit 0',
+    ...codecovProbe(codecov, condition),
+    '      - name: coverage upload',
+    ...(codecov.optional ? ['        id: codecov-upload', '        continue-on-error: true'] : []),
+    '        uses: codecov/codecov-action@0fb7174895f61a3b6b78fc075e0cd60383518dac # v5.5.5',
+    `        if: ${uploadCondition}`,
+    '        with:',
+    codecov.auth === 'token' ? `          token: \${{ secrets.${codecov.token} }}` : '          use_oidc: true',
+    `          files: ${lcovReport}`,
+    '          disable_search: true',
+    `          fail_ci_if_error: ${!codecov.optional}`,
+    ...(codecov.optional ? [
+      '      - name: Codecov upload unavailable',
+      "        if: ${{ !cancelled() && steps.codecov-upload.outcome == 'failure' }}",
+      '        run: |',
+      '          echo "::notice::codecov upload skipped: upload unavailable (services.codecov.optional)"',
+    ] : []),
+  ].join('\n');
+}
+
+/** Sonar consumes the test coverage and fast lint artifacts only on release tags with a configured token. */
+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: [lint, coverage]',
+    `    timeout-minutes: ${timeout}`,
+    '    runs-on: ubuntu-latest',
+    '    env:',
+    `      SONAR_TOKEN: \${{ secrets.${sonar.token} }}`,
+    `      SONAR_HOST_URL: ${host}`,
+    '    steps:',
+  ].join('\n');
+  const steps = [
+    ...sonarProbe(sonar),
+    `      - uses: ${DOWNLOAD_ARTIFACT}`,
+    `        if: ${condition}`,
+    '        with:',
+    `          name: ${lcovArtifact}`,
+    `          path: ${lcovReport.split('/').slice(0, -1).join('/') || '.'}`,
+    `      - uses: ${DOWNLOAD_ARTIFACT}`,
+    `        if: ${condition}`,
+    '        with:',
+    '          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',
+    `        if: ${condition}`,
+    '        timeout-minutes: 10',
+  ].join('\n');
+  // Variable strings are inserted after render() expands partials, so resolve Sonar's shared install partial before insertion.
+  const read = name => fs.readFileSync(new URL('../templates/app/ci-workflows/' + name, import.meta.url), 'utf8').replaceAll('\r\n', '\n');
+  return read('sonar-steps.yml')
+    .replace('{{> app/ci-workflows/install-steps.yml}}', () => read('install-steps.yml').trimEnd())
+    .replaceAll('{{nodeMajor}}', nodeMajor)
+    .replace('{{sonarJobHeader}}', () => header)
+    .replace('{{sonarJobSteps}}', () => steps)
+    .trimEnd() + '\n';
+}
+
+/** The app source reader is be-relative; the authored manifest lives one directory above that side. */
+function buildDeclaration(source) {
+  if (!source?.read) return {};
+  try {
+    return parseYaml(source.read('../.starcistacks/application-stacks.yaml')) ?? {};
+  } catch (error) {
+    if (error.code === 'ENOENT') return {};
+    throw error;
+  }
+}
+
+/** Static CI values are strings with valid environment names; expressions cannot turn public config into runtime secret reads. */
+function mergeBuildValues(values, entries) {
+  for (const [key, value] of Object.entries(entries ?? {})) {
+    if (!/^[A-Z][A-Z0-9_]*$/u.test(key) || typeof value !== 'string' || value.includes('${{')) {
+      throw refusal('STACK_BUILD_ARG_INVALID', 'CI build values must map environment names to literal strings');
+    }
+    if (values.has(key) && values.get(key) !== value) {
+      throw refusal('STACK_BUILD_ARG_INVALID', 'CI build values disagree for ' + key);
+    }
+    values.set(key, value);
+  }
+}
+
+/** Image values own their keys; the build-fe gate supplies only missing keys, and sealed members stay unopened. */
+function imageBuildEnv(image, gates) {
+  const values = new Map();
+  mergeBuildValues(values, image?.buildArgs?.values);
+  const fallback = new Map();
+  for (const gate of gates.filter(entry => entry.name === 'build-fe')) mergeBuildValues(fallback, gate.env);
+  for (const [key, value] of fallback) if (!values.has(key)) values.set(key, value);
+  if (!values.size) return '';
+  return ['        env:', ...[...values.keys()].sort(byCodeUnit).map(key => '          ' + key + ': ' + JSON.stringify(values.get(key)))].join('\n');
+}
+
+/** Multiple deployed front ends build separately through the installed turbo (a run step has no node_modules/.bin on PATH), so each fe/apps/<app> and its dependencies see its own public values. */
+function frontendBuild(source, app) {
+  const declaration = buildDeclaration(source);
+  const environments = Object.keys(source?.stack?.imageEnvironments ?? {});
+  const environment = environments.length > 1 ? 'production' : environments[0];
+  const images = Object.values(declaration.environments?.[environment]?.deploy?.images ?? {});
+  const frontend = images.filter(image => app?.sides.fe.apps.some(entry => entry.name === image.app));
+  const gates = declaration.release?.gates ?? [];
+  const singleEnv = imageBuildEnv(frontend[0], gates);
+  if (frontend.length <= 1) return { env: singleEnv, steps: ['      - name: build fe', '        run: npm run build:fe', singleEnv].filter(Boolean).join('\n') };
+  const steps = frontend.map(image => [
+    '      - name: build fe ' + image.app,
+    '        run: npm run codegen --silent && npx --no-install turbo run build --filter=./fe/apps/' + image.app,
+    imageBuildEnv(image, gates),
+  ].filter(Boolean).join('\n')).join('\n');
+  return { env: singleEnv, steps };
+}
+
+/** 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. The local release gate writes the same file with mergeSonarReports (release/lint-report.mjs): keep both identical. */
+function sonarMergeSteps(condition) {
+  return [
+    '      - name: merge Sonar lint reports',
+    `        if: ${condition}`,
+    '        run: |',
+    "          node --input-type=module <<'NODE'",
+    "          import fs from 'node:fs';",
+    "          const files = ['reports/lint.be.sonar.json', 'reports/lint.fe.sonar.json'];",
+    "          const reports = files.filter(file => fs.existsSync(file)).map(file => JSON.parse(fs.readFileSync(file, 'utf8')));",
+    '          const rules = [...new Map(reports.flatMap(report => report.rules).map(rule => [rule.id, rule])).values()];',
+    '          const issues = reports.flatMap(report => report.issues);',
+    "          fs.mkdirSync('reports', { recursive: true });",
+    "          fs.writeFileSync('reports/lint.sonar.json', JSON.stringify({ rules, issues }, null, 2) + '\\n');",
+    '          NODE',
+  ];
+}
+
+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, heap } = parseYaml(fs.readFileSync(STANDARD, 'utf8'));
+  const jobs = declaration?.ci?.jobs ?? {};
+  const timeout = (job) => String(jobs[job]?.timeoutMinutes ?? defaults.timeoutMinutes[job]);
+  const shards = Number(jobs.test?.shards ?? defaults.shards);
+  return {
+    nodeOptions: `--max-old-space-size=${heap.minMiB}`,
+    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;
+  const sonar = configuredSonar?.wiring === 'not-used' || configuredSonar?.mode === 'disabled' ? null : configuredSonar;
+  const codecov = quality?.codecov ?? { enabled: true, auth: 'oidc' };
+  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('/'),
+    // The istanbul JSON a shard writes beside the lcov (STARCI_COVERAGE_SHARD=1): what the coverage job merges.
+    shardCoverageReport: lcovReport.split('/').slice(0, -1).concat('coverage-final.json').join('/'),
+    ciBuildEnv: build.env,
+    ciBuildSteps: build.steps,
+    ciLint: exampleCommand(source, 'npm run lint'),
+    ciLintSonar: exampleCommand(source, 'npm run lint -- --sonar reports/lint.sonar.json'),
+    // The coverage judgement alone over the merged report: the fast and lint jobs already ran every other rule of the app check.
+    ciCoverageProof: exampleCommand(source, 'npx starci app coverage verify ' + lcovReport),
+    ciDatabaseLint: exampleCommand(source, 'npm run db:lint'),
+    auditCommand: `npm audit${audit.omitDev ? ' --omit=dev' : ''} --audit-level=${audit.level}`,
+    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: [
+      '      - name: lint',
+      ...(sonar ? ["        if: env.SONAR_TOKEN == ''"] : []),
+      `        run: ${exampleCommand(source, 'npm run lint -- --side ' + side)}`,
+      '        env:',
+      `          NODE_OPTIONS: ${settings.nodeOptions}`,
+      ...(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: ${settings.nodeOptions}`,
+        `      - uses: ${UPLOAD_ARTIFACT}`,
+        // 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-${side}`,
+        `          path: reports/lint.${side}.sonar.json`,
+      ] : []),
+    ].join('\n'),
+    codecovSteps: codecovSteps(lcovReport, codecov),
+    sonarJob: sonarJob(sonar, lcovReport, lcovArtifact, nodeMajor, settings.timeoutSonar),
+    lcovArtifact,
+  };
+}

package/sync/hygiene.mjs

@@ -5,7 +5,7 @@
 // being, an .enc that is no sops envelope, a line that matches a secret pattern), so no plaintext secret reaches the history whatever
 // .gitignore says (`git add -f`, a path tracked before a rule tightened). There is no override. At an HFS app root (hfs.json) it also
 // refuses a back-end logic file the index adds without its unit spec beside it (BE_UNIT_SPEC_NOT_STAGED,
-// scripts/hfs/rules/staged-specs.mjs over the coverage scope), naming the file. The pre-commit hook judges the staged files;
+// scripts/hfs/rules/staged-specs.mjs over the coverage scope; a constants-only file has nothing to test), naming the file. The pre-commit hook judges the staged files;
 // scripts/gates/hfs-sync.mjs judges every tracked file.
 //
 // Run inside a full runtime checkout — the repository under judgment is the checkout — it also reports the
@@ -19,6 +19,7 @@ import { secretFileFindings } from '../runtime/scripts/hfs/rules/secrets.mjs';
 import { stagedSpecFindings } from '../runtime/scripts/hfs/rules/staged-specs.mjs';
 import { loadSlotManifest } from '../runtime/scripts/hfs/slots.mjs';
 import { runGit } from '../runtime/scripts/api/git/lib.mjs';
+import { loadTypescript } from '../runtime/scripts/lib/package-at.mjs';
 
 // One git call through the runtime's git owner (scripts/api/git/lib.mjs): stdout, or the failure thrown the way execFileSync threw it (error.status carries the exit code). The caller's own env is passed on unchanged: a hook runs with GIT_INDEX_FILE set, which the staged reads must keep seeing.
 const git = (cwd, args, options = {}) => {
@@ -75,7 +76,12 @@ const addedFiles = cwd => gitList(cwd, ['diff', '--cached', '--name-only', '--di
 /** The new back-end logic files staged without their unit spec, at an HFS app root only (a repository without hfs.json has no slots). */
 function missingSpecFindings(cwd, { added = addedFiles(cwd), indexed, manifest } = {}) {
   if (!fs.existsSync(path.join(cwd, 'hfs.json')) || !added.some(file => file.startsWith('be/'))) return [];
-  return stagedSpecFindings(manifest ?? loadSlotManifest(), added, indexed ?? new Set(trackedFiles(cwd)));
+  const staged = (file) => {
+    try { return git(cwd, ['show', `:${file}`]); } catch { return null; }
+  };
+  let ts = null;
+  try { ts = loadTypescript(cwd, import.meta.dirname); } catch { ts = null; }
+  return stagedSpecFindings(manifest ?? loadSlotManifest(), added, indexed ?? new Set(trackedFiles(cwd)), { ts, staged });
 }
 
 const MAX_STAGED_BYTES = 1024 * 1024;

package/sync/index.mjs

@@ -19,6 +19,7 @@ import { createHash } from 'node:crypto';
 import { createRequire } from 'node:module';
 import fs from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { braceVariants } from '../runtime/scripts/lib/glob.mjs';
 import { codecovPaths, coverageComponents, jestCoverage, sonarCoverageExclusions } from '../runtime/scripts/hfs/coverage-scope.mjs';
 import { APP_SCOPE, SIDES, litePresenceOf, loadSlotManifest, resolveRepoDeclaration, slotInEdition } from '../runtime/scripts/hfs/slots.mjs';
@@ -159,19 +160,19 @@ export async function loadPresets(root) {
 }
 
 /**
- * The jest preset's Sonar exclusions as @starci/hfs ships them: `@starci/jest-preset/sonar-exclusions.json`, copied byte for byte into
- * packages/hfs/runtime by scripts/hfs/sync-runtime.mjs, so a fresh `starci app scaffold` (nothing installed yet) and an upgrade render the
- * same list the app's installed preset answers. A missing copy is a refusal, never a render without it.
+ * The jest preset's Sonar exclusions as @starci/hfs ships them: `@starci/jest-preset/sonar-exclusions.cjs` (a require-free module),
+ * copied byte for byte into packages/hfs/runtime by scripts/hfs/sync-runtime.mjs, so a fresh `starci app scaffold` (nothing installed
+ * yet) and an upgrade render the same list the app's installed preset answers. A missing copy is a refusal, never a render without it.
  */
-const BUNDLED_SONAR_EXCLUSIONS = new URL('../runtime/packages/jest-preset/sonar-exclusions.json', import.meta.url);
+const BUNDLED_SONAR_EXCLUSIONS = new URL('../runtime/packages/jest-preset/sonar-exclusions.cjs', import.meta.url);
 
 /** The presets ({ sonarExclusions }) of the jest preset version this @starci/hfs pins, read from its bundled copy. */
 export function bundledPresets() {
   let list;
   try {
-    list = JSON.parse(fs.readFileSync(BUNDLED_SONAR_EXCLUSIONS, 'utf8'));
+    list = createRequire(import.meta.url)(fileURLToPath(BUNDLED_SONAR_EXCLUSIONS));
   } catch {
-    throw new SyncError('HFS_SYNC_PRESET_MISSING', '@starci/hfs ships no runtime/packages/jest-preset/sonar-exclusions.json; reinstall @starci/hfs at its published version');
+    throw new SyncError('HFS_SYNC_PRESET_MISSING', '@starci/hfs ships no runtime/packages/jest-preset/sonar-exclusions.cjs; reinstall @starci/hfs at its published version');
   }
   return { sonarExclusions: list.join(',') };
 }

package/templates/be/skeleton/src/modules/platform/database/migrate-connections.client.spec.ts

@@ -0,0 +1,60 @@
+import { Test } from "@nestjs/testing"
+import { mock } from "@starci/jest-preset"
+import { Secret } from "@modules/platform/config"
+import type { DatabaseConnectionOptions } from "./database.options"
+import type { ConnectionOpener, ConnectionSource } from "./database.port"
+import { migrateConnections } from "./migrate-connections.client"
+
+const MIGRATE_CLIENT = Symbol("migrate-connections")
+
+const setup = async () => {
+    const moduleRef = await Test.createTestingModule({
+        providers: [{ provide: MIGRATE_CLIENT, useFactory: () => ({ migrateConnections }) }],
+    }).compile()
+    return moduleRef.get<{ readonly migrateConnections: typeof migrateConnections }>(MIGRATE_CLIENT)
+}
+
+const connection = (name: string): DatabaseConnectionOptions => ({
+    name,
+    url: new Secret(`postgres://localhost:5432/${name}`),
+    entities: [],
+    migrations: [],
+})
+
+describe("migrateConnections", () => {
+    it("runs the pending migrations of each connection in order and answers their names by connection", async () => {
+        const client = await setup()
+        const primary = mock<ConnectionSource>()
+        primary.runMigrations.mockResolvedValue([{ id: 1, timestamp: 1, name: "Init1" }])
+        const archive = mock<ConnectionSource>()
+        archive.runMigrations.mockResolvedValue([])
+        const sources = new Map([
+            ["primary", primary],
+            ["archive", archive],
+        ])
+        const opener = mock<ConnectionOpener>()
+        opener.open.mockImplementation(
+            (target: DatabaseConnectionOptions) => sources.get(target.name) ?? mock<ConnectionSource>(),
+        )
+
+        const applied = await client.migrateConnections([connection("primary"), connection("archive")], opener)
+
+        expect(applied).toEqual({ primary: ["Init1"], archive: [] })
+        expect(primary.initialize).toHaveBeenCalledTimes(1)
+        expect(primary.destroy).toHaveBeenCalledTimes(1)
+        expect(archive.destroy).toHaveBeenCalledTimes(1)
+    })
+
+    it("destroys the data source of a connection whose migration fails, and fails", async () => {
+        const client = await setup()
+        const failing = mock<ConnectionSource>()
+        failing.runMigrations.mockRejectedValue(new TypeError("relation already exists"))
+        const opener = mock<ConnectionOpener>()
+        opener.open.mockReturnValue(failing)
+
+        await expect(client.migrateConnections([connection("primary")], opener)).rejects.toThrow(
+            "relation already exists",
+        )
+        expect(failing.destroy).toHaveBeenCalledTimes(1)
+    })
+})

package/runtime/packages/jest-preset/sonar-exclusions.json

@@ -1 +0,0 @@
-["**/*.spec.ts", "**/*.e2e-spec.ts", "**/dist/**", "**/coverage/**"]