@starci/hfs 4.7.17 → 4.7.19

package/CHANGELOG.md

@@ -1,11 +1,22 @@
 # Changelog
 
-## 4.7.17 - 2026-10-21
+## 4.7.19 - 2026-10-21
+- Changed: supersedes 4.7.18 (app lint broken: the canons' Sonar way block carries its own ignores, which `starci app lint` refused as an unsupported source scope, so it exited 2 without running ESLint and reported 0 findings); 4.7.18 is not used.
+- Fixed: `starci app lint` reads the canons' flat config as flat config defines it: global ignores prune the source walk and a block's own ignores narrow only that block, so the Sonar way block no longer makes the source scope unavailable (exit 2 without ESLint); a file is a source when some block's files match it and that block's ignores do not.
+- Fixed: the full scaffold's ui package pins react-dom at the react version beside react.
+- Fixed: the scaffolded `migrate-connections.client.spec.ts` mocks an applied migration with only its `name` (the `AppliedMigration` port), so the full scaffold typechecks again.
+- Added: `release.requireCi` (default false, owner ruling release-require-ci-per-project): `starci app release push` waits for the candidate CI only for an app that sets it true; with false it needs the annotated tag and the green L4 record, runs the dry run and pushes atomically, and the L4 record and the output state that CI was not required; canon pins follow the matching package cohort.
+
+## 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/lint/run.mjs

@@ -137,8 +137,35 @@ const onSide = (changed, side) => changed.filter((file) => file.startsWith(`${si
 const fileKey = (file) => process.platform === 'win32' ? path.resolve(file).toLowerCase() : path.resolve(file);
 const inside = (root, file) => { const rel = path.relative(root, file); return rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel); };
 
+/**
+ * The lint scope a flat config declares: `ignored(file)` for its global ignores (a block holding only `ignores` and `name`), which prune
+ * the walk, and `source(file)` for a file some block's `files` select while that block's own `ignores` do not (standard flat-config
+ * semantics: the Sonar-way block of the canons narrows itself to the scanned files). Negated or non-string selectors cannot prove a
+ * scope and are refused.
+ */
+export function canonScope(config) {
+  const blocks = [], ignored = [];
+  for (const block of config) {
+    if (!block || typeof block !== 'object') throw new Error('the installed canon returned an invalid config block');
+    for (const field of ['files', 'ignores']) {
+      if (block[field] === undefined) continue;
+      if (!Array.isArray(block[field]) || block[field].some((glob) => typeof glob !== 'string' || glob.startsWith('!'))) throw new Error(`unsupported canon ${field} selectors`);
+    }
+    const patterns = (globs) => (globs ?? []).flatMap((glob) => braceVariants(glob).map(globExpression));
+    const global = block.ignores !== undefined && Object.keys(block).every((key) => ['ignores', 'name'].includes(key));
+    if (global) ignored.push(...patterns(block.ignores));
+    else if (block.files !== undefined) blocks.push({ files: patterns(block.files), ignores: patterns(block.ignores) });
+  }
+  if (!blocks.length) throw new Error('the installed canon has no source selectors');
+  const matches = (list, file) => list.some((pattern) => pattern.test(file));
+  return {
+    ignored: (file) => matches(ignored, file),
+    source: (file) => blocks.some((block) => matches(block.files, file) && !matches(block.ignores, file)),
+  };
+}
+
 /** Read the installed canon's source selectors, then enumerate that scope; unavailable or unsupported selectors cannot prove coverage. */
-async function sourceFiles({ repoRoot, cwd, side, scope }) {
+async function sourceFiles({ repoRoot, cwd, side, scope: folderScope }) {
   const entry = createRequire(path.join(cwd, 'package.json')).resolve(`@starci/eslint-canon-${side}`);
   // The canon must be the app's own install: resolved inside the app root, or inside the app's node_modules when that folder is a link to the install
   // (the runtime's examples lint in a sealed copy whose node_modules links the example's own install, scripts/hfs/example-secrets.mjs).
@@ -149,30 +176,19 @@ async function sourceFiles({ repoRoot, cwd, side, scope }) {
   if (typeof factory !== 'function' || typeof canon.loadHfs !== 'function') throw new Error('the installed canon has no supported config factory');
   const config = await factory({ hfs: canon.loadHfs(pathToFileURL(path.join(cwd, 'eslint.config.mjs')).href) });
   if (!Array.isArray(config)) throw new Error('the installed canon did not return a flat config');
-  const selectors = [], ignored = [];
-  for (const block of config) {
-    if (!block || typeof block !== 'object') throw new Error('the installed canon returned an invalid config block');
-    for (const [field, target] of [['files', selectors], ['ignores', ignored]]) {
-      if (block[field] === undefined) continue;
-      if (!Array.isArray(block[field]) || block[field].some((glob) => typeof glob !== 'string' || glob.startsWith('!'))) throw new Error(`unsupported canon ${field} selectors`);
-      if (field === 'ignores' && Object.keys(block).some((key) => !['ignores', 'name'].includes(key))) throw new Error('unsupported non-global canon ignores');
-      target.push(...block[field].flatMap((glob) => braceVariants(glob).map(globExpression)));
-    }
-  }
-  if (!selectors.length) throw new Error('the installed canon has no source selectors');
-  const matches = (patterns, file) => patterns.some((pattern) => pattern.test(file));
+  const scope = canonScope(config);
   const files = [];
   const visit = (folder) => {
     for (const child of fs.readdirSync(path.join(cwd, folder), { withFileTypes: true })) {
       const file = posix(path.join(folder, child.name));
       // Ask the canon's global ignore patterns before entering output or installed-package trees.
-      if (matches(ignored, file) || matches(ignored, `${file}/__starci_scope_probe__`)) continue;
+      if (scope.ignored(file) || scope.ignored(`${file}/__starci_scope_probe__`)) continue;
       if (child.isSymbolicLink()) throw new Error(`cannot enumerate symlink ${file}`);
       if (child.isDirectory()) visit(file);
-      else if (child.isFile() && matches(selectors, file)) files.push(file);
+      else if (child.isFile() && scope.source(file)) files.push(file);
     }
   };
-  visit(scope ?? '');
+  visit(folderScope ?? '');
   return files.sort(byCodeUnit);
 }
 

package/package.json

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

package/release/gate.mjs

@@ -16,7 +16,9 @@ import { sonarQualityGate } from './sonar-quality-gate.mjs';
 export const RELEASE_CODE = 'RELEASE_CONFIG_INVALID';
 const SONAR_UNREACHABLE = 'SONAR_UNREACHABLE';
 
-const FIELDS = new Set(['gates', 'tagPrefix', 'defaultBranch', 'tagMatchesVersion']);
+const FIELDS = new Set(['gates', 'tagPrefix', 'defaultBranch', 'tagMatchesVersion', 'requireCi']);
+/** The note a release that does not wait for CI carries in its L4 record and its push output (owner ruling release-require-ci-per-project). */
+export const CI_NOT_REQUIRED = 'CI not required by release.requireCi=false (owner ruling release-require-ci-per-project): the local release gate, this L4 record and the annotated tag, is the release proof';
 const GATE_FIELDS = new Set(['name', 'command', 'summary', 'env']);
 const GATE_NAME = /^[a-z][a-z0-9-]*$/u;
 const TOKEN = /^[A-Za-z0-9_@%+=:,./\\-]+$/u;
@@ -117,14 +119,17 @@ export function normalizeRelease(block, scripts = {}, services = {}, options = {
   const tagPrefix = raw.tagPrefix ?? 'v';
   const defaultBranch = raw.defaultBranch ?? 'main';
   const tagMatchesVersion = raw.tagMatchesVersion ?? false;
+  // The candidate CI of `release push` is an app's choice and off by default (owner ruling release-require-ci-per-project); the local gate never is.
+  const requireCi = raw.requireCi ?? false;
   if (typeof tagPrefix !== 'string' || !PREFIX.test(tagPrefix)) problems.push(`release.tagPrefix: must match ${PREFIX}`);
   if (!refName(defaultBranch)) problems.push(`release.defaultBranch: must match ${REF_NAME}`);
   if (typeof tagMatchesVersion !== 'boolean') problems.push('release.tagMatchesVersion: must be true or false');
+  if (typeof requireCi !== 'boolean') problems.push('release.requireCi: must be true or false');
   const quality = releaseServices(services, options);
   const audit = auditGate(quality.audit);
   const gates = raw.gates === undefined ? defaultGates(scripts, audit) : gatesOf(raw.gates, problems);
   if (raw.gates !== undefined && audit && !gates.some((gate) => gate.name === 'audit')) gates.push(audit);
-  return problems.length === 0 ? { config: { gates, tagPrefix, defaultBranch, tagMatchesVersion, services: quality } } : { problems };
+  return problems.length === 0 ? { config: { gates, tagPrefix, defaultBranch, tagMatchesVersion, requireCi, services: quality } } : { problems };
 }
 
 /* ---- git through the seam */
@@ -345,10 +350,11 @@ function assertUnmoved(ctx, head) {
   if (dirty.length > 0) throw failure('RELEASE_TREE_DIRTY', `the gates left ${dirty.length} changed or untracked path(s) (first: ${dirty[0].slice(0, 100)}): generated files differ from HEAD. Commit or ignore them properly, then rerun. No record.`);
 }
 
-function writeRecord(ctx, { head, tag, results, recordPath }) {
+function writeRecord(ctx, { head, tag, results, recordPath, requireCi }) {
   const record = {
     schema: 'starci-app-l4-record/1', head, tag, createdAt: new Date(ctx.now()).toISOString(), producedBy: 'starci app release gate',
     note: 'Required gates passed on a clean HEAD; optional provider skips are explicit and every entry links its log and sha256.',
+    ci: requireCi === true ? { required: true, note: 'starci app release push waits for the candidate CI of this sha (release.requireCi=true)' } : { required: false, note: CI_NOT_REQUIRED },
     gates: results,
   };
   fs.mkdirSync(path.dirname(recordPath), { recursive: true });
@@ -394,7 +400,7 @@ export async function releaseGate(ctx, config, options = {}) {
   const failed = results.filter((result) => !result.pass && !result.skipped);
   if (failed.length > 0) return { ok: false, lines: [...plan, ...report, `gate(s) red: ${failed.map((item) => item.name).join(', ')}. No L4 record, no tag.`], data: { ...base, executed: true, results } };
   assertUnmoved(ctx, facts.head);
-  writeRecord(ctx, { head: facts.head, tag: facts.chosen.tag, results, recordPath });
+  writeRecord(ctx, { head: facts.head, tag: facts.chosen.tag, results, recordPath, requireCi: config.requireCi });
   const created = facts.chosen.state !== 'on-head';
   if (created) git(ctx, ['tag', '-a', facts.chosen.tag, '-m', `release ${facts.chosen.tag}: required gates passed on ${facts.head.slice(0, 12)} (L4 record ${path.basename(recordPath)})`, facts.head]);
   const tagged = created ? `annotated tag ${facts.chosen.tag} created on ${facts.head.slice(0, 10)}` : `annotated tag ${facts.chosen.tag} already on ${facts.head.slice(0, 10)}`;

package/release/index.mjs

@@ -53,7 +53,7 @@ function readPackage(root) {
   try { return JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')); } catch { throw refusal('RELEASE_PACKAGE_UNREADABLE', 'package.json is not readable JSON'); }
 }
 
-/** The normalised `release:` block (tolerant of absence) with the package version: { root, version, gates, tagPrefix, defaultBranch, tagMatchesVersion }. */
+/** The normalised `release:` block (tolerant of absence) with the package version: { root, version, gates, tagPrefix, defaultBranch, tagMatchesVersion, requireCi }. */
 function loadReleaseConfig(root) {
   const pkg = readPackage(root);
   if (typeof pkg.version !== 'string' || !VERSION.test(pkg.version)) throw refusal(RELEASE_CODE, 'package.json needs a version like 1.2.3 (the release tag derives from it)');

package/release/push.mjs

@@ -3,11 +3,13 @@
 // head and tag. `git push --dry-run --atomic` always runs first (the hook's verdict is the proof) and any failure refuses the push.
 // With --execute the exact sha first goes to its candidate ref refs/heads/release/candidate-<version> and the push waits for the ci.yml run of that sha
 // (candidate-ci.mjs, OWNER RULING candidate-ci 2026-10-18): only a green candidate (or the owner's sha-bound override record) moves the branch and the tag.
+// That wait runs only for an app that sets release.requireCi: true; the default false (owner ruling release-require-ci-per-project) pushes after the
+// local gate and the dry run alone and says so. The tag, the L4 record and the dry run are never skipped.
 import fs from 'node:fs';
 import path from 'node:path';
 import { firstLine } from '../stack/context.mjs';
 import { failure, refusal } from '../stack/errors.mjs';
-import { annotatedOnHead, git, refName, releaseDir } from './gate.mjs';
+import { CI_NOT_REQUIRED, annotatedOnHead, git, refName, releaseDir } from './gate.mjs';
 import { candidateRef, candidateStep } from './candidate-ci.mjs';
 
 const VERDICT = /RIGHTS_PUSH_NOT_RELEASE|pre-push|failed to push|Everything up|->/u;
@@ -98,8 +100,10 @@ export async function releasePush(ctx, config, options = {}) {
   const red = [];
   const refs = [...branchRefs(ctx, { head, remote, branch }, red).refs, ...tagRefs(ctx, { remote, tag: gate.tag }, red)];
   data.refs = refs;
-  const candidate = refs.length > 0 ? candidateRef(gate.tag, config.tagPrefix) : null;
+  const requireCi = config.requireCi === true;
+  const candidate = refs.length > 0 && requireCi ? candidateRef(gate.tag, config.tagPrefix) : null;
   if (candidate) out.push(`plan           git push ${remote} +${head.slice(0, 10)}:${candidate}, wait for its ci.yml run to be green, then git push --atomic ${remote} ${refs.join(' ')}`);
+  else if (refs.length > 0) out.push(`plan           git push --atomic ${remote} ${refs.join(' ')}`, `ci             ${CI_NOT_REQUIRED}`);
   else out.push(`plan           git push --atomic ${remote} (nothing)`);
   if (refs.length === 0 && red.length === 0) return { ok: true, lines: [...out, `already pushed: ${remote}/${branch} holds HEAD and ${gate.tag} is on ${remote}. Nothing to do.`], data };
   if (refs.length > 0) {
@@ -109,10 +113,12 @@ export async function releasePush(ctx, config, options = {}) {
   }
   if (red.length > 0) return refuse(out, red, data, options.execute === true ? 'nothing pushed.' : 'dry run: nothing pushed.');
   if (options.execute !== true) return { ok: true, lines: [...out, 'dry run: nothing pushed. ready; re-run with --execute.'], data };
-  const judged = await candidateStep(ctx, { head, tag: gate.tag, prefix: config.tagPrefix, remote, wait: options.candidateWait });
-  data.candidate = judged.data;
-  out.push(...judged.lines);
-  if (!judged.ok) return { ok: false, lines: [...out, `nothing pushed to ${branch} or ${gate.tag}.`], data };
+  if (requireCi) {
+    const judged = await candidateStep(ctx, { head, tag: gate.tag, prefix: config.tagPrefix, remote, wait: options.candidateWait });
+    data.candidate = judged.data;
+    out.push(...judged.lines);
+    if (!judged.ok) return { ok: false, lines: [...out, `nothing pushed to ${branch} or ${gate.tag}.`], data };
+  } else data.candidate = { required: false, note: CI_NOT_REQUIRED };
   const run = git(ctx, ['push', '--atomic', remote, ...refs], { allowFail: true });
   if (run.code !== 0) return { ok: false, lines: [...out, `push failed: ${firstLine(run.stderr)}`], data };
   return { ok: true, lines: [...out, `pushed to ${remote}: ${refs.join(' ')}`], data: { ...data, pushed: true } };

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.27
     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.26
     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.19
     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.19
     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": "fb2a551d3cb254cc42fa5c95dc1a32af973df14313385f03703bc209b2badb8a",
   "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"
         },
@@ -1238,7 +1242,9 @@ export const CATALOG = {
             "OK passes; ERROR is red as RELEASE_SONAR_GATE_FAILED naming each failed condition, as is a FAILED or CANCELED task",
             "a task still running after 600 s is RELEASE_SONAR_GATE_TIMEOUT; no report-task, an HTTP error or no gate is RELEASE_SONAR_GATE_UNREADABLE",
             "OWNER RULING candidate-ci (2026-10-18): the gate no longer reads the default-branch CI; the verdict is the candidate run of the sha",
-            "push --execute sends HEAD to refs/heads/release/candidate-<version> first and waits for its ci.yml run (it triggers on release/candidate-*)",
+            "release.requireCi (default false, owner ruling release-require-ci-per-project) decides whether push waits for CI; the local gate is never skipped",
+            "requireCi false: push needs the tag and the green L4 record, runs the dry run, pushes atomically and states CI was not required",
+            "requireCi true: push --execute sends HEAD to refs/heads/release/candidate-<version> first and waits for its ci.yml run",
             "green moves the branch and the tag in one atomic push; red refuses RELEASE_CANDIDATE_CI_RED naming the failing jobs",
             "no run, or no end in time, refuses RELEASE_CANDIDATE_CI_TIMEOUT; unreadable GitHub refuses RELEASE_CI_UNKNOWN; nothing reaches the branch",
             "only the owner's starci release ci-override --sha <sha> --reason <text> record lets a red candidate through; there is no --no-ci-check flag",

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/scaffold/app.mjs

@@ -216,7 +216,7 @@ const LITE_FE_APP_DEPENDENCIES = Object.freeze({
  * ./routing, client-safe: the default locale a client boundary reads).
  */
 const FE_PACKAGES = Object.freeze({
-  ui: { exports: ['.'], dependencies: { '@heroui/react': null, '@starci/grammar': null, '@starci/heroicons': null, '@xyflow/react': null, 'next-intl': null, react: null } },
+  ui: { exports: ['.'], dependencies: { '@heroui/react': null, '@starci/grammar': null, '@starci/heroicons': null, '@xyflow/react': null, 'next-intl': null, react: null, 'react-dom': null } },
   i18n: { exports: ['.', './proxy', './routing'], dependencies: { next: null, 'next-intl': null, 'server-only': null } },
 });