@starci/hfs 4.7.16 → 4.7.18

package/release/sonar-quality-gate.mjs

@@ -0,0 +1,68 @@
+// sonar-quality-gate.mjs - the verdict of the release gate's sonar row after the scanner exits 0. The scanner's exit code says only
+// that the report was uploaded; the server computes the analysis afterwards. This reads the task the scanner wrote
+// (`.scannerwork/report-task.txt`), polls `api/ce/task` until the compute-engine task ends, then reads the quality gate of that
+// analysis from `api/qualitygates/project_status` with the same token. OK passes; ERROR is red and names every failed condition;
+// a task that ends FAILED or CANCELED, an unreadable answer and a deadline passed are typed refusals in the row's detail.
+import fs from 'node:fs';
+import path from 'node:path';
+
+const SONAR_GATE_FAILED = 'RELEASE_SONAR_GATE_FAILED';
+const SONAR_GATE_TIMEOUT = 'RELEASE_SONAR_GATE_TIMEOUT';
+const SONAR_GATE_UNREADABLE = 'RELEASE_SONAR_GATE_UNREADABLE';
+const REPORT_TASK = path.join('.scannerwork', 'report-task.txt');
+const DONE = new Set(['SUCCESS', 'FAILED', 'CANCELED']);
+/** The bound of one compute-engine wait and the pause between polls (milliseconds). */
+const QUALITY_GATE_WAIT = Object.freeze({ deadline: 600_000, interval: 5_000 });
+
+/** The `key=value` lines of the scanner's report-task.txt under `cwd`, or null when the scanner wrote none. */
+function reportTask(cwd) {
+  let text;
+  try { text = fs.readFileSync(path.join(cwd, REPORT_TASK), 'utf8'); } catch { return null; }
+  return Object.fromEntries(text.split(/\r?\n/u).map((line) => line.split('=')).filter(([key, ...rest]) => key && rest.length).map(([key, ...rest]) => [key.trim(), rest.join('=').trim()]));
+}
+
+/** One authenticated JSON GET; a failed request or a non-JSON body throws. */
+async function getJson(ctx, url, token) {
+  const response = await ctx.fetch(url, { headers: { Authorization: `Basic ${Buffer.from(`${token}:`).toString('base64')}` }, signal: AbortSignal.timeout(30_000) });
+  if (!response.ok) throw new Error(`HTTP ${response.status} from ${url.split('?')[0]}`);
+  return response.json();
+}
+
+/** The failed conditions of a quality gate answer, as `metric comparator threshold (actual value)` lines. */
+const failedConditions = (status) => (status?.conditions ?? []).filter((condition) => condition.status === 'ERROR')
+  .map((condition) => `${condition.metricKey} ${condition.comparator ?? ''} ${condition.errorThreshold ?? ''} (actual ${condition.actualValue ?? '?'})`.replace(/\s+/gu, ' '));
+
+/**
+ * The quality-gate verdict of the analysis the scanner just uploaded from `cwd`: `{ pass, detail, conditions? }`. `token` is the
+ * scanner's token, `host` the declared server. `ctx.fetch`, `ctx.now` and `ctx.sleep` are the seams; `wait` bounds the poll.
+ */
+export async function sonarQualityGate(ctx, { cwd, host, token, wait = QUALITY_GATE_WAIT }) {
+  const task = reportTask(cwd);
+  if (!task?.ceTaskId) return { pass: false, detail: `${SONAR_GATE_UNREADABLE}: the scanner wrote no ${REPORT_TASK.replaceAll('\\', '/')} with a ceTaskId` };
+  const server = String(task.serverUrl || host).replace(/\/$/u, '');
+  const sleep = ctx.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const deadline = ctx.now() + wait.deadline;
+  let analysisId = null;
+  try {
+    for (;;) {
+      const state = (await getJson(ctx, `${server}/api/ce/task?id=${encodeURIComponent(task.ceTaskId)}`, token))?.task;
+      if (DONE.has(state?.status)) {
+        if (state.status !== 'SUCCESS') return { pass: false, detail: `${SONAR_GATE_FAILED}: compute-engine task ${task.ceTaskId} ended ${state.status}${state.errorMessage ? `: ${state.errorMessage}` : ''}` };
+        analysisId = state.analysisId;
+        break;
+      }
+      if (ctx.now() >= deadline) return { pass: false, detail: `${SONAR_GATE_TIMEOUT}: compute-engine task ${task.ceTaskId} is still ${state?.status ?? 'unknown'} after ${Math.round(wait.deadline / 1000)}s` };
+      await sleep(wait.interval);
+    }
+    const query = analysisId ? `analysisId=${encodeURIComponent(analysisId)}` : `projectKey=${encodeURIComponent(task.projectKey ?? '')}`;
+    const status = (await getJson(ctx, `${server}/api/qualitygates/project_status?${query}`, token))?.projectStatus;
+    if (status?.status === 'OK') return { pass: true, detail: 'exit 0, quality gate OK' };
+    if (status?.status === 'ERROR') {
+      const conditions = failedConditions(status);
+      return { pass: false, detail: `${SONAR_GATE_FAILED}: quality gate ERROR (${conditions.join('; ') || 'no condition listed'})${task.dashboardUrl ? ` ${task.dashboardUrl}` : ''}`, conditions };
+    }
+    return { pass: false, detail: `${SONAR_GATE_UNREADABLE}: quality gate status ${status?.status ?? 'missing'}` };
+  } catch (error) {
+    return { pass: false, detail: `${SONAR_GATE_UNREADABLE}: ${String(error?.message ?? error)}` };
+  }
+}

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.24
+    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.23
+    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.2
+    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.16
+    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.16
+    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/knowledge/hfs/rules.yaml

@@ -3754,7 +3754,7 @@ rules:
       - {path: packages/eslint/be/sonar-parity-editions.spec.mjs, edition: full}
       - {path: packages/eslint/fe/sonar-parity-editions.spec.mjs, edition: lite}
       - {path: packages/eslint/fe/sonar-parity-editions.spec.mjs, edition: full}
-    law: "Code carries none of the smells SonarCloud measures that a lint rule can decide: no `await` inside a loop (S9382; an endless loop is spared), no `charCodeAt`/`fromCharCode` (S7758), no string that only escapes backslashes (S7780; a Next `matcher` is spared, it is read statically), no nested conditional expression (S3358), no `void` on anything but a call (S3735), no unused import (S1128), no import that is only handed on instead of `export ... from` (S7763), no prop of a component's props type the component never reads (S6767, front end), and, through typescript-eslint with type information, no deprecated API (S1874), no object turned into text (S6551) and no `async` function that never awaits and returns no promise (S7503). The files a unit or an end-to-end spec names are outside the scan, so outside these rules."
+    law: "Code carries none of the smells SonarCloud measures that a lint rule can decide: no `await` inside a loop (S9382; an endless loop is spared), no `charCodeAt`/`fromCharCode` (S7758), no string that only escapes backslashes (S7780; a Next `matcher` is spared, it is read statically), no nested conditional expression (S3358), no `void` on anything but a call (S3735), no unused import (S1128), no import that is only handed on instead of `export ... from` (S7763), no prop of a component's props type the component never reads (S6767, front end), no `<video>` or `<audio>` without a captions track unless muted (S4084, front end), and, through typescript-eslint with type information, no deprecated API (S1874), no object turned into text (S6551) and no `async` function that never awaits and returns no promise (S7503). Every other rule of the Sonar way TypeScript profile with an ESLint equivalent (scripts/lib/sonar-way.mjs: eslint-plugin-sonarjs' Sonar way set, the core, typescript-eslint and unicorn rules it builds on) is on at error in both canons. The files a unit or an end-to-end spec names are outside the scan, so outside these rules."
     kinds: [lint, codemod]
     gates: [pre-commit, settle, land, ci]
     failureCodes: ["SCAN_SMELL"]
@@ -3774,6 +3774,7 @@ rules:
       - {kind: eslint-fe, id: no-unused-import}
       - {kind: eslint-fe, id: prefer-export-from}
       - {kind: eslint-fe, id: no-unused-prop-types}
+      - {kind: eslint-fe, id: media-has-caption}
   - id: R236
     code: "RT_GATE_LOOSENING"
     editions: [lite, full]

package/runtime/knowledge/hfs/slots.yaml

@@ -38,7 +38,7 @@ versioning:
 # or environment reads (BE_APP_OPTIONS_COMPOSITION). Secrets use EnvSource.secret(): <NAME>_FILE first, plain <NAME> only
 # when the file key is absent; .starcistacks owns custody. Capability <capability>.config.ts roles stay unchanged.
 # 3.3.0 is a minor (alpha.16): it ADDS the optional app.ci-stack-deploy slot, the managed workflow of the starci app stack verbs.
-# 3.4.0 is a minor (alpha.24): it ADDS the opt-in be.contract.mcp-tools slot, the committed MCP tool-catalog snapshot of an app.
+# 3.4.0 is a minor (alpha.25): it ADDS the opt-in be.contract.mcp-tools slot, the committed MCP tool-catalog snapshot of an app.
 
 # Field meaning, per slot.
 #   id          stable name, never changes meaning inside a major.

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": "c7ef5f72727b2b906b541669c413050b7abd34206c123a87fe90502330271856",
+  "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"
         },
@@ -1234,6 +1238,9 @@ export const CATALOG = {
             "declared release.gates gets audit appended if missing",
             "--sonar appends @sonar/scan@4.3.0 against services.sonar.host (host.public for a host mapping), plus organization for sonarcloud;",
             "disabled or unavailable Sonar or an unset token refuses RELEASE_SONAR_UNAVAILABLE",
+            "a scanner exit 0 is not a pass: the row polls api/ce/task until the analysis ends, then reads api/qualitygates/project_status with the same token",
+            "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-*)",
             "green moves the branch and the tag in one atomic push; red refuses RELEASE_CANDIDATE_CI_RED naming the failing jobs",
@@ -1246,7 +1253,7 @@ export const CATALOG = {
           "runtimeSide": "host"
         },
         "scaffold": {
-          "summary": "create a full or lite StarCi app, including an empty unborn main Git repository",
+          "summary": "create a full or lite StarCi app in its own Git repository (unborn main)",
           "owner": "@starci/hfs",
           "positional": [
             {

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

@@ -10,7 +10,8 @@
 // is in sync by construction. The lockfile is never written by hand: once the files are written, npm resolves the real one
 // (`npm install --package-lock-only`, no node_modules, no scripts), so `npm ci` installs the new app as it is. When npm cannot
 // resolve it the scaffold fails (HFS_SCAFFOLD_LOCK_FAILED), names the step and unlinks its own generated entries. Replaced or
-// occupied entries are retained with a cleanup message. The only existing root accepted is an empty unborn main Git repository.
+// occupied entries are retained with a cleanup message. The only existing root accepted is an empty unborn main Git repository; a
+// new path is made one first (git init, branch main).
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
@@ -27,6 +28,7 @@ import { initializeAppIdentity } from '../runtime/scripts/hfs/secret-init.mjs';
 import { declaredSealedMembers, materializeDeclaredPlaceholders } from '../runtime/scripts/hfs/sealed-members.mjs';
 import { revParseQuery } from '../runtime/scripts/api/git/rev-parse-query.mjs';
 import { lsFiles } from '../runtime/scripts/api/git/ls-files.mjs';
+import { init as gitInit } from '../runtime/scripts/api/git/init.mjs';
 import { insidePath, samePath } from '../runtime/scripts/lib/path-key.mjs';
 import { byCodeUnit } from '../report/order.mjs';
 import { sonarGateName } from '../sync/sonar-key.mjs';
@@ -629,8 +631,9 @@ function emitScaffoldDatabaseTypes(root, name, writes, emitTypes) {
 
 /**
  * `starci app scaffold <name>`: writes the new app under `into`, resolves its lockfile with npm (`lock`, npmLock), and returns
- * `{ root, files }` (app-relative paths, sorted). `presets` is what sync loads from the installed @starci/jest-preset (the Sonar
- * exclusions); the CLI passes the one it resolves. Failure removes only scaffold-owned entries, retaining an existing .git.
+ * `{ root, files }` (app-relative paths, sorted). A new path is first made an empty repository with unborn main (`initGit`), so the
+ * app always lives in its own Git repository. `presets` are the jest preset's Sonar exclusions; the CLI passes the copy @starci/hfs
+ * ships (bundledPresets). Failure removes only scaffold-owned entries, retaining the .git.
  */
 /** Seal declared starter members to a fresh app recipient through the scaffold rollback owner. */
 function initializeScaffoldSecrets(root, writes) {
@@ -641,13 +644,25 @@ function initializeScaffoldSecrets(root, writes) {
   return [...initialized.files, ...materialized.members];
 }
 
-export function scaffoldApp({ name, into, presets, edition = 'full', authCallback = false, registryVisibility = 'public', manifest = loadSlotManifest(), pins = bundledPins(), lock = npmLock, emitTypes = generateDbTypes, now = () => new Date() }) {
+/**
+ * A new app path becomes the one accepted existing root first: an empty repository with unborn main (git init), so the app is always
+ * created inside its own Git repository and `starci npm ci` can install the hooks. A failed init is a refusal before any file is written.
+ */
+function bornRepository(root, initGit) {
+  fs.mkdirSync(root, { recursive: true });
+  const made = initGit(root, { branch: 'main' });
+  if (!made?.ok) throw new ScaffoldError('HFS_SCAFFOLD_GIT_INIT_FAILED', `git init could not create the repository of ${root} (${String(made?.stderr ?? '').trim() || 'no output'}); remove ${root}, check git, then run starci app scaffold again`);
+  return fs.lstatSync(root);
+}
+
+export function scaffoldApp({ name, into, presets, edition = 'full', authCallback = false, registryVisibility = 'public', manifest = loadSlotManifest(), pins = bundledPins(), lock = npmLock, emitTypes = generateDbTypes, initGit = gitInit, now = () => new Date() }) {
   if (!NAME.test(String(name))) throw new ScaffoldError('HFS_SCAFFOLD_NAME_INVALID', `the app name ${name} must be kebab-case (a project name: ${NAME})`);
   const root = path.resolve(into, name);
-  const original = fs.lstatSync(root, { throwIfNoEntry: false });
-  if (original && !emptyUnbornGit(root, original)) throw new ScaffoldError('HFS_SCAFFOLD_EXISTS', `${root} already exists; only a plain directory containing solely .git with unborn main and an empty index can be scaffolded`);
+  const existing = fs.lstatSync(root, { throwIfNoEntry: false });
+  if (existing && !emptyUnbornGit(root, existing)) throw new ScaffoldError('HFS_SCAFFOLD_EXISTS', `${root} already exists; only a plain directory containing solely .git with unborn main and an empty index can be scaffolded`);
   if (!['public', 'private'].includes(registryVisibility)) throw new ScaffoldError('HFS_SCAFFOLD_REGISTRY_VISIBILITY', `--registry-visibility accepts public or private (got ${registryVisibility})`);
   if (typeof authCallback !== 'boolean') throw new ScaffoldError('HFS_SCAFFOLD_NAME_INVALID', 'authCallback must be a boolean');
+  const original = existing ?? bornRepository(root, initGit);
   const declaration = starterDeclaration(name, manifest, edition);
   if (authCallback) enableAuthCallback(declaration);
   const app = resolveRepoDeclaration(manifest, declaration);

package/src/main.mjs

@@ -69,7 +69,7 @@ import { formatCoverageReport } from '../runtime/scripts/hfs/coverage-from.mjs';
 import { HFS_DECLARATION_FILE, HfsSlotsError, loadSlotManifest, readRepoDeclaration } from '../runtime/scripts/hfs/slots.mjs';
 import { formatFindings } from '../sync/format.mjs';
 import { main as syncMain } from '../sync/cli.mjs';
-import { SyncError, loadPresets } from '../sync/index.mjs';
+import { SyncError, bundledPresets } from '../sync/index.mjs';
 import { managedFindings } from '../sync/managed.mjs';
 import { emitContracts } from '../emit/contracts.mjs';
 import { dbTypesEmitter } from '../emit/db-types.mjs';
@@ -282,14 +282,10 @@ async function lintMain(argv, { cwd, stdout, presets, prettier }) {
 }
 
 /**
- * The jest preset a new app renders its Sonar exclusions from: the one installed beside this @starci/hfs. None is a refusal,
- * never a render without it.
+ * The jest preset a new app renders its Sonar exclusions from: the copy this @starci/hfs ships (bundledPresets), the same version the
+ * scaffold pins, so `npx @starci/cli app scaffold` works before any dependency of the app is installed.
  */
-async function scaffoldPresets() {
-  try { return await loadPresets(path.dirname(fileURLToPath(import.meta.url))); } catch (error) {
-    throw new SyncError('HFS_SYNC_PRESET_MISSING', `${error.message.replace(/^[A-Z_]+: /, '')}; install @starci/jest-preset beside @starci/cli, then run starci app scaffold <name>`);
-  }
-}
+const scaffoldPresets = () => bundledPresets();
 
 function globalValueArgument(arg, args) {
   const inline = arg.startsWith('--cwd=') || arg.startsWith('--edition=');
@@ -389,7 +385,7 @@ function addMain(opts, { cwd: repoRoot, stdout: out }) {
 async function scaffoldMain(opts, { cwd, edition = 'full', presets, lock, stdout: out }) {
   const [name, ...extra] = opts.positional;
   if (!name || extra.length) throw new Error('starci app scaffold takes `<name> [--into <dir>] [--edition full|lite] [--registry-visibility public|private]`');
-  const { root: created, files } = scaffoldApp({ name, into: path.resolve(cwd, opts.into ?? '.'), edition, presets: presets ?? await scaffoldPresets(), ...(opts['registry-visibility'] === undefined ? {} : { registryVisibility: opts['registry-visibility'] }), ...(lock ? { lock } : {}) });
+  const { root: created, files } = scaffoldApp({ name, into: path.resolve(cwd, opts.into ?? '.'), edition, presets: presets ?? scaffoldPresets(), ...(opts['registry-visibility'] === undefined ? {} : { registryVisibility: opts['registry-visibility'] }), ...(lock ? { lock } : {}) });
   out(`starci app scaffold: created ${created} (${files.length} files); next: starci npm ci (the lockfile, then the git hooks through npm run prepare; after a raw npm ci --ignore-scripts run npm run prepare), then starci app lint\n`);
   return 0;
 }