@starci/hfs 4.7.16 → 4.7.17

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 4.7.17 - 2026-10-21
+- 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: 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.
+
 ## 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/package.json

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

package/release/gate.mjs

@@ -1,388 +1,402 @@
-// gate.mjs - `starci app release gate`: the honest release gate. It runs the app's own gates on a clean HEAD and when all required gates pass it
-// writes the L4 record <git-common-dir>/starci-release/<HEAD sha>.l4.json (head, tag, per-gate log path and sha256) and creates the annotated tag.
-// The canon pre-push hook lets main and v* tags through only for a HEAD with that tag and that record. Nothing is pushed here (see push.mjs).
-// The gate list comes from the optional `release:` block of .starcistacks/application-stacks.yaml, else from the app's managed package scripts.
-// Commands are argument arrays (never shell strings) run through ctx.spawn; a git tool call always goes through the same seam.
-import { createHash } from 'node:crypto';
-import fs from 'node:fs';
-import path from 'node:path';
-import { isPlainObject as plain } from '../runtime/engine/plain-object.mjs';
-import { qualityServices } from '../runtime/scripts/hfs/ci-declaration.mjs';
-import { firstLine, lines, tool } from '../stack/context.mjs';
-import { failure, refusal } from '../stack/errors.mjs';
-import { produceLintReports } from './lint-report.mjs';
-
-export const RELEASE_CODE = 'RELEASE_CONFIG_INVALID';
-const SONAR_UNREACHABLE = 'SONAR_UNREACHABLE';
-
-const FIELDS = new Set(['gates', 'tagPrefix', 'defaultBranch', 'tagMatchesVersion']);
-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;
-const ENV_KEY = /^[A-Z][A-Z0-9_]*$/u;
-const REF_NAME = /^[A-Za-z0-9._/][A-Za-z0-9._/-]*$/u;
-const PREFIX = /^[A-Za-z][A-Za-z0-9._-]{0,19}$/u;
-export const VERSION = /^(\d+)\.(\d+)\.(\d+)$/u;
-const THRESHOLD_MISS = /coverage threshold .* not met/gu;
-const WRAPPED = new Set(['npm', 'npx']);
-const SCRIPT_GATES = ['typecheck', 'build:be', 'lint', 'build:fe', 'test'];
-const MAX_PATCH = 100;
-
-/** True for a branch or remote name git can take as one argument (no leading dash, only path-like characters). */
-export const refName = (value) => typeof value === 'string' && REF_NAME.test(value);
-
-const scriptGate = (script) => ({
-  name: script.replaceAll(':', '-'),
-  command: ['npm', 'run', script],
-  summary: script === 'test' ? 'jest' : null,
-  env: {},
-});
-
-/** Default gates run app-check, the enabled audit, then every managed script present in the app. */
-function defaultGates(scripts, audit) {
-  const present = SCRIPT_GATES.filter((script) => typeof scripts?.[script] === 'string');
-  return [{ name: 'app-check', command: ['npx', 'starci', 'app', 'check'], summary: null, env: {} }, ...(audit ? [audit] : []), ...present.map(scriptGate)];
-}
-
-/** Shared quality settings retain the release reader's audit validation, disabled mode and legacy string host compatibility. */
-function releaseServices(services, options) {
-  const audit = services?.audit ?? {};
-  if (!plain(audit) || (audit.in !== undefined && (!Array.isArray(audit.in) || !audit.in.every((scope) => typeof scope === 'string'))) || (audit.omitDev !== undefined && typeof audit.omitDev !== 'boolean')) throw refusal(RELEASE_CODE, 'services.audit must be a mapping with a string-list in and boolean omitDev');
-  const sonar = services?.sonar;
-  const compatible = typeof sonar?.host === 'string' ? { ...sonar, host: { public: sonar.host } } : sonar;
-  const quality = qualityServices({ services: { ...services, sonar: compatible } }, options);
-  if (audit.mode === 'disabled') quality.audit = null;
-  return quality;
-}
-
-/** The shared audit settings preserve release scope, level and development-dependency selection. */
-function auditGate(audit) {
-  if (!audit || !audit.in.includes('release-gate')) return null;
-  if (!['info', 'low', 'moderate', 'high', 'critical'].includes(audit.level)) throw refusal(RELEASE_CODE, 'services.audit.level must be an npm audit level');
-  return { name: 'audit', command: ['npm', 'audit', ...(audit.omitDev ? ['--omit=dev'] : []), `--audit-level=${audit.level}`], summary: null, env: {} };
-}
-
-/** A requested local Sonar scan uses only the declared host and token variable; the token never enters argv. */
-function sonarGate(services, env) {
-  const configured = services?.sonar;
-  const sonar = configured?.provider === 'sonarcloud' ? { ...configured, host: 'https://sonarcloud.io' } : configured;
-  const tokenName = sonar?.token;
-  if (!sonar?.host || !ENV_KEY.test(tokenName) || !env[tokenName]) throw refusal('RELEASE_SONAR_UNAVAILABLE', 'declare an enabled services.sonar host and set its ci.token environment variable');
-  const command = ['npx', '--yes', '@sonar/scan@4.3.0', `-Dsonar.host.url=${sonar.host}`];
-  const organization = sonar.organization ?? (sonar.organizationVar ? env[sonar.organizationVar] : null);
-  if (organization) command.push(`-Dsonar.organization=${organization}`);
-  if (!command.every((word) => TOKEN.test(word))) throw refusal('RELEASE_SONAR_UNAVAILABLE', 'Sonar host and organization must be plain command arguments');
-  return { name: 'sonar', command, summary: null, env: { SONAR_TOKEN: env[tokenName] }, provider: sonar,
-    credentialNames: [...new Set(['SONAR_TOKEN', tokenName])] };
-}
-
-function gateProblems(entry, at, seen) {
-  const found = [];
-  for (const key of Object.keys(entry)) if (!GATE_FIELDS.has(key)) found.push(`${at}.${key}: is not a field of a gate`);
-  if (typeof entry.name !== 'string' || !GATE_NAME.test(entry.name)) found.push(`${at}.name: must match ${GATE_NAME}`);
-  else if (seen.has(entry.name)) found.push(`${at}.name: ${entry.name} is declared twice`);
-  const command = entry.command;
-  if (!Array.isArray(command) || command.length === 0 || !command.every((word) => typeof word === 'string' && TOKEN.test(word))) found.push(`${at}.command: must be a non-empty list of plain words (no shell strings)`);
-  if (entry.summary !== undefined && entry.summary !== 'jest') found.push(`${at}.summary: must be jest`);
-  const env = entry.env ?? {};
-  if (!plain(env) || !Object.entries(env).every(([key, value]) => ENV_KEY.test(key) && typeof value === 'string')) found.push(`${at}.env: must map UPPER_CASE names to string values`);
-  return found;
-}
-
-function gatesOf(list, problems) {
-  if (!Array.isArray(list) || list.length === 0) {
-    problems.push('release.gates: must be a non-empty list');
-    return [];
-  }
-  const seen = new Set();
-  const gates = [];
-  list.forEach((entry, index) => {
-    const at = `release.gates[${index}]`;
-    const found = plain(entry) ? gateProblems(entry, at, seen) : [`${at}: must be a mapping`];
-    problems.push(...found);
-    if (found.length === 0) {
-      seen.add(entry.name);
-      gates.push({ name: entry.name, command: entry.command, summary: entry.summary ?? null, env: entry.env ?? {} });
-    }
-  });
-  return gates;
-}
-
-/** Judges the optional `release:` block. Absence is fine (defaults). Returns { config } or { problems }. */
-export function normalizeRelease(block, scripts = {}, services = {}, options = {}) {
-  const raw = block ?? {};
-  if (!plain(raw)) return { problems: ['release: must be a mapping'] };
-  const problems = Object.keys(raw).filter((key) => !FIELDS.has(key)).map((key) => `release.${key}: is not a field of the release block`);
-  const tagPrefix = raw.tagPrefix ?? 'v';
-  const defaultBranch = raw.defaultBranch ?? 'main';
-  const tagMatchesVersion = raw.tagMatchesVersion ?? 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');
-  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 };
-}
-
-/* ---- git through the seam */
-
-/** Runs git in the app root; a missing git or (unless allowFail) a non-zero exit is a failure whose message names the first stderr line. */
-export function git(ctx, args, { allowFail = false } = {}) {
-  const run = tool(ctx, 'git', args, { cwd: ctx.cwd, env: ctx.env });
-  if (run.error) throw failure('RELEASE_GIT_MISSING', `cannot run git (${run.error.message})`);
-  if (run.status !== 0 && !allowFail) throw failure('RELEASE_GIT_FAILED', `git ${args.slice(0, 2).join(' ')}: ${firstLine(run.stderr)}`);
-  return { code: run.status, stdout: String(run.stdout ?? '').trim(), stderr: String(run.stderr ?? '') };
-}
-
-/** The directory that holds the L4 records: <git common dir>/starci-release. */
-export const releaseDir = (ctx) => path.join(path.resolve(ctx.cwd, git(ctx, ['rev-parse', '--git-common-dir']).stdout), 'starci-release');
-
-/** Annotated tags `<prefix><digit>*` that point at HEAD (lightweight tags do not count: the hook ignores them). */
-export function annotatedOnHead(ctx, prefix) {
-  const names = lines(git(ctx, ['tag', '--points-at', 'HEAD', '--list', `${prefix}[0-9]*`]).stdout);
-  return names.filter((name) => git(ctx, ['cat-file', '-t', `refs/tags/${name}`], { allowFail: true }).stdout === 'tag');
-}
-
-const dirtyPaths = (ctx) => lines(git(ctx, ['status', '--porcelain', '--untracked-files=normal']).stdout);
-
-/** Tag names that exist locally or on the remote. */
-function takenTags(ctx, prefix, remote) {
-  const local = lines(git(ctx, ['tag', '--list', `${prefix}*`]).stdout);
-  const listed = lines(git(ctx, ['ls-remote', '--tags', remote], { allowFail: true }).stdout);
-  const remoteNames = listed.map((line) => line.split('refs/tags/')[1]?.replace(/\^\{\}$/u, '')).filter(Boolean);
-  return new Set([...local, ...remoteNames]);
-}
-
-/** Next free `<prefix><major>.<minor>.<n>` for the package version. */
-function nextFree(prefix, version, taken) {
-  const [, major, minor] = VERSION.exec(version);
-  for (let patch = 0; patch < MAX_PATCH; patch += 1) {
-    const candidate = `${prefix}${major}.${minor}.${patch}`;
-    if (!taken.has(candidate)) return candidate;
-  }
-  throw refusal('RELEASE_NO_FREE_TAG', `no free tag ${prefix}${major}.${minor}.0 to ${prefix}${major}.${minor}.${MAX_PATCH - 1}`);
-}
-
-/** The tag this release uses and its state: on-head (reused), free (will be created) or taken (exists on another commit). */
-function chooseTag(ctx, config, { prefix, remote }) {
-  const onHead = annotatedOnHead(ctx, prefix);
-  const taken = takenTags(ctx, prefix, remote);
-  const exact = `${prefix}${config.version}`;
-  const tag = config.tagMatchesVersion ? exact : (onHead[0] ?? nextFree(prefix, config.version, taken));
-  if (onHead.includes(tag)) return { tag, state: 'on-head' };
-  return { tag, state: taken.has(tag) ? 'taken' : 'free' };
-}
-
-/* ---- gate results */
-
-const sha256 = (file) => createHash('sha256').update(fs.readFileSync(file)).digest('hex');
-
-const lineAfter = (text, label) => {
-  const found = text.split('\n').find((line) => line.startsWith(label));
-  return found === undefined ? null : found.slice(label.length).trim();
-};
-
-/** The jest summary lines of a log: { suites, failedSuites, tests, failed, passed } or null when jest printed none. */
-function jestSummary(text) {
-  const suites = lineAfter(text, 'Test Suites:');
-  const tests = lineAfter(text, 'Tests:');
-  if (suites === null || tests === null) return null;
-  const count = (line, word) => Number(new RegExp(String.raw`(\d+) ${word}`, 'u').exec(line)?.[1] ?? 0);
-  return {
-    suites: count(suites, 'total'), failedSuites: count(suites, 'failed'),
-    tests: count(tests, 'total'), failed: count(tests, 'failed'), passed: count(tests, 'passed'),
-  };
-}
-
-/** Judges a jest-style gate from its log: green needs suites that all passed, every test passed and no coverage threshold miss. */
-function judgeJest(text) {
-  const summary = jestSummary(text);
-  const misses = (text.match(THRESHOLD_MISS) ?? []).length;
-  if (!summary) return { pass: false, detail: 'no jest summary in the log', summary: null, misses };
-  const pass = summary.suites > 0 && summary.failedSuites === 0 && summary.failed === 0 && summary.passed === summary.tests && misses === 0;
-  const detail = `suites ${summary.suites - summary.failedSuites}/${summary.suites}, tests ${summary.passed}/${summary.tests}, coverage-threshold misses ${misses}`;
-  return { pass, detail, summary, misses };
-}
-
-/** [command, args] to start an argv; on Windows npm and npx are .cmd files, so they start through cmd.exe (words are validated, never a shell string). */
-export function launch(argv, platform) {
-  if (platform === 'win32' && WRAPPED.has(argv[0])) return ['cmd.exe', ['/d', '/s', '/c', ...argv]];
-  return [argv[0], argv.slice(1)];
-}
-
-/** Sonar availability is public and bounded; HTTP uses the existing injected fetch seam. */
-async function sonarAvailability(ctx, gate) {
-  const sonar = gate.provider;
-  if (!sonar) return null;
-  let up = false;
-  try {
-    const response = await ctx.fetch(sonar.host.replace(/\/$/u, '') + '/api/system/status', { signal: AbortSignal.timeout(10000) });
-    up = response.ok && (await response.json()).status === 'UP';
-  } catch { up = false; }
-  if (up) return null;
-  const detail = sonar.optional
-    ? `notice: sonar skipped: ${sonar.host} not reachable (services.sonar.optional)`
-    : `${SONAR_UNREACHABLE}: ${sonar.host} did not report UP within ten seconds`;
-  return { skipped: sonar.optional === true, pass: false, detail };
-}
-
-/** Unreachable optional providers remain explicit skipped rows, with a real log and no scan invocation. */
-async function runAvailableGate(ctx, gate, options) {
-  const availability = await sonarAvailability(ctx, gate);
-  const log = path.join(options.dir, `${gate.name}.log`);
-  if (!availability) {
-    if (!gate.provider) return runGate(ctx, gate, options);
-    // The scanner imports the app's declared external issues report: produce it first with the app's own lint, as the managed CI does.
-    const started = ctx.now();
-    const lint = produceLintReports(ctx, { launch, platform: options.platform, env: withoutCredentials(ctx.env, options.credentialNames) });
-    if (lint.pass) return runGate(ctx, gate, { ...options, preface: lint.text });
-    fs.writeFileSync(log, lint.text);
-    return { name: gate.name, command: gate.command.join(' '), pass: false, detail: 'lint report failed (see log)', seconds: Math.round((ctx.now() - started) / 1000),
-      summary: null, log: path.resolve(log), logSha256: sha256(log), env: Object.keys(gate.env) };
-  }
-  fs.writeFileSync(log, availability.detail + '\n');
-  return { name: gate.name, command: gate.command.join(' '), ...availability, seconds: 0,
-    summary: null, log: path.resolve(log), logSha256: sha256(log), env: Object.keys(gate.env) };
-}
-
-const withoutCredentials = (values, credentialNames) => {
-  const selected = new Set(credentialNames);
-  return Object.fromEntries(Object.entries(values ?? {}).filter(([key]) => !selected.has(key.toUpperCase())));
-};
-
-function runGate(ctx, gate, { dir, platform, credentialNames, preface = '' }) {
-  const log = path.join(dir, `${gate.name}.log`);
-  const started = ctx.now();
-  const [command, args] = launch(gate.command, platform);
-  // The native scanner alone consumes Sonar credentials; ordinary gates cannot inherit or reintroduce them.
-  const env = { ...ctx.env, ...(gate.provider ? gate.env : withoutCredentials(gate.env, credentialNames)) };
-  const run = tool(ctx, command, args, { cwd: ctx.cwd, env });
-  const output = `${run.stdout ?? ''}${run.stderr ?? ''}`;
-  const text = gate.name === 'sonar' && gate.env.SONAR_TOKEN ? output.replaceAll(gate.env.SONAR_TOKEN, '[REDACTED]') : output;
-  fs.writeFileSync(log, preface + text);
-  const verdict = judgeVerdict(run, gate, text);
-  if (gate.name === 'sonar' && gate.env.SONAR_TOKEN) verdict.detail = verdict.detail.replaceAll(gate.env.SONAR_TOKEN, '[REDACTED]');
-  const seconds = Math.round((ctx.now() - started) / 1000);
-  return {
-    name: gate.name, command: gate.command.join(' '), pass: verdict.pass, detail: verdict.detail, seconds,
-    summary: verdict.summary ?? null, log: path.resolve(log), logSha256: sha256(log), env: Object.keys(gate.env),
-  };
-}
-
-function judgeVerdict(run, gate, text) {
-  if (run.error) return { pass: false, detail: `cannot run (${run.error.message})` };
-  if (run.status !== 0) return { pass: false, detail: `exit ${run.status}` };
-  if (gate.summary === 'jest') return judgeJest(text);
-  return { pass: true, detail: 'exit 0' };
-}
-
-/* ---- the gate */
-
-function sourceProblem(ctx, source, head) {
-  if (source === 'HEAD') return null;
-  if (!refName(source)) return `--source ${source} is not a ref name`;
-  const resolved = git(ctx, ['rev-parse', '--verify', `${source}^{commit}`], { allowFail: true });
-  if (resolved.code !== 0) return `cannot resolve --source ${source}`;
-  if (resolved.stdout !== head) return `--source ${source} is ${resolved.stdout.slice(0, 10)} but HEAD is ${head.slice(0, 10)}: the hook and the L4 record are about HEAD; check the candidate out first`;
-  return null;
-}
-
-function tagLine({ tag, state }) {
-  if (state === 'on-head') return `tag            ${tag} (annotated, already on HEAD)`;
-  if (state === 'taken') return `tag            ${tag} (TAKEN by another commit)`;
-  return `tag            ${tag} (free: will be created, annotated)`;
-}
-
-/** Everything that can be known without running a gate: the facts, the red preconditions and the lines that describe them. */
-function inspect(ctx, config, options) {
-  const head = git(ctx, ['rev-parse', 'HEAD']).stdout;
-  const branch = git(ctx, ['rev-parse', '--abbrev-ref', 'HEAD'], { allowFail: true }).stdout;
-  const out = [`checkout       ${ctx.cwd}`, `HEAD           ${head} (${branch})`];
-  const red = [];
-  const problem = sourceProblem(ctx, options.source ?? 'HEAD', head);
-  if (problem) red.push(problem);
-  const dirty = dirtyPaths(ctx);
-  if (dirty.length > 0) red.push(`working tree is not clean (${dirty.length} path(s), first: ${dirty[0].slice(0, 100)}): the record would vouch for files that are not in HEAD`);
-  else out.push('worktree       clean');
-  const prefix = options.tagPrefix ?? config.tagPrefix;
-  if (!PREFIX.test(prefix)) throw refusal('RELEASE_USAGE', `--tag-prefix must match ${PREFIX}`);
-  const chosen = chooseTag(ctx, config, { prefix, remote: 'origin' });
-  if (chosen.state === 'taken') red.push(`tag ${chosen.tag} already exists on another commit (local or remote)`);
-  out.push(tagLine(chosen));
-  return { head, chosen, red, out };
-}
-
-function planLines(config, facts, dir, recordPath) {
-  const out = [`L4 record      ${recordPath}`, `logs           ${dir}`, '', 'gates (required gates must pass, optional provider outages are skipped, in this order):'];
-  for (const gate of config.gates) {
-    const summary = gate.summary ? ` (summary: ${gate.summary})` : '';
-    out.push(`  ${gate.name.padEnd(17)} ${gate.command.join(' ')}${summary}`);
-  }
-  out.push(`then: write ${path.basename(recordPath)} and \`git tag -a ${facts.chosen.tag}\` on ${facts.head.slice(0, 10)}; push it with \`starci app release push\`.`);
-  return out;
-}
-
-function assertUnmoved(ctx, head) {
-  const now = git(ctx, ['rev-parse', 'HEAD']).stdout;
-  if (now !== head) throw failure('RELEASE_HEAD_MOVED', `HEAD moved during the gates (${head.slice(0, 10)} -> ${now.slice(0, 10)}). No record.`);
-  const dirty = dirtyPaths(ctx);
-  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 }) {
-  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.',
-    gates: results,
-  };
-  fs.mkdirSync(path.dirname(recordPath), { recursive: true });
-  fs.writeFileSync(recordPath, `${JSON.stringify(record, null, 2)}\n`);
-}
-
-/** Gates run sequentially because each failure prevents subsequent commands and record creation. */
-async function runAll(ctx, config, options) {
-  fs.mkdirSync(options.dir, { recursive: true });
-  return config.gates.reduce(async (pending, gate) => {
-    const results = await pending;
-    if (results.some((result) => !result.pass && !result.skipped)) return results;
-    return [...results, await runAvailableGate(ctx, gate, options)];
-  }, Promise.resolve([]));
-}
-
-function summaryOf(result) {
-  let status = result.pass ? 'PASS' : 'FAIL';
-  if (result.skipped) status = 'SKIPPED';
-  return `${status} ${result.name} (${result.detail}, ${result.seconds}s) log ${result.log}`;
-}
-
-/**
- * `starci app release gate`: dry run prints the preconditions, the gate list, the head and the tag; --execute runs every gate and, only if required gates pass,
- * writes the L4 record and creates the annotated tag. options: { execute, sonar, source, tagPrefix, platform }.
- */
-export async function releaseGate(ctx, config, options = {}) {
-  if (options.sonar) config = { ...config, gates: [...config.gates.filter((gate) => gate.name !== 'sonar'), sonarGate(config.services, ctx.env)] };
-  const credentialNames = config.gates.find(gate => gate.provider)?.credentialNames ?? ['SONAR_TOKEN', config.services?.sonar?.token].filter(Boolean);
-  ctx = Object.create(ctx, {env: {value: withoutCredentials(ctx.env, credentialNames)}});
-  // The CI verdict of a release is the candidate run of its own sha, judged by `starci app release push` (candidate-ci.mjs, OWNER RULING candidate-ci 2026-10-18):
-  // the gate no longer refuses over the latest default-branch run.
-  const facts = inspect(ctx, config, options);
-  const common = releaseDir(ctx);
-  const recordPath = path.join(common, `${facts.head}.l4.json`);
-  const dir = path.join(common, facts.head.slice(0, 12));
-  const plan = [...facts.out, ...planLines(config, facts, dir, recordPath)];
-  const base = { head: facts.head, tag: facts.chosen.tag, record: recordPath, gates: config.gates.map((gate) => gate.name) };
-  if (facts.red.length > 0) return { ok: false, lines: [...plan, ...facts.red.map((item) => `RED: ${item}`), 'nothing was run.'], data: { ...base, red: facts.red, executed: false } };
-  if (options.execute !== true) return { ok: true, lines: [...plan, '', 'dry run: no gate was run, nothing written. preconditions OK.'], data: { ...base, red: [], executed: false } };
-  const results = await runAll(ctx, config, { dir, platform: options.platform ?? process.platform, credentialNames });
-  const report = results.map(summaryOf);
-  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 });
-  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)}`;
-  return { ok: true, lines: [...plan, ...report, `L4 record written: ${recordPath}`, tagged], data: { ...base, executed: true, results, tagCreated: created } };
-}
+// gate.mjs - `starci app release gate`: the honest release gate. It runs the app's own gates on a clean HEAD and when all required gates pass it
+// writes the L4 record <git-common-dir>/starci-release/<HEAD sha>.l4.json (head, tag, per-gate log path and sha256) and creates the annotated tag.
+// The canon pre-push hook lets main and v* tags through only for a HEAD with that tag and that record. Nothing is pushed here (see push.mjs).
+// The gate list comes from the optional `release:` block of .starcistacks/application-stacks.yaml, else from the app's managed package scripts.
+// Commands are argument arrays (never shell strings) run through ctx.spawn; a git tool call always goes through the same seam.
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { isPlainObject as plain } from '../runtime/engine/plain-object.mjs';
+import { qualityServices } from '../runtime/scripts/hfs/ci-declaration.mjs';
+import { firstLine, lines, tool } from '../stack/context.mjs';
+import { failure, refusal } from '../stack/errors.mjs';
+import { produceLintReports } from './lint-report.mjs';
+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 GATE_FIELDS = new Set(['name', 'command', 'summary', 'env']);
+const GATE_NAME = /^[a-z][a-z0-9-]*$/u;
+const TOKEN = /^[A-Za-z0-9_@%+=:,./\\-]+$/u;
+const ENV_KEY = /^[A-Z][A-Z0-9_]*$/u;
+const REF_NAME = /^[A-Za-z0-9._/][A-Za-z0-9._/-]*$/u;
+const PREFIX = /^[A-Za-z][A-Za-z0-9._-]{0,19}$/u;
+export const VERSION = /^(\d+)\.(\d+)\.(\d+)$/u;
+const THRESHOLD_MISS = /coverage threshold .* not met/gu;
+const WRAPPED = new Set(['npm', 'npx']);
+const SCRIPT_GATES = ['typecheck', 'build:be', 'lint', 'build:fe', 'test'];
+const MAX_PATCH = 100;
+
+/** True for a branch or remote name git can take as one argument (no leading dash, only path-like characters). */
+export const refName = (value) => typeof value === 'string' && REF_NAME.test(value);
+
+const scriptGate = (script) => ({
+  name: script.replaceAll(':', '-'),
+  command: ['npm', 'run', script],
+  summary: script === 'test' ? 'jest' : null,
+  env: {},
+});
+
+/** Default gates run app-check, the enabled audit, then every managed script present in the app. */
+function defaultGates(scripts, audit) {
+  const present = SCRIPT_GATES.filter((script) => typeof scripts?.[script] === 'string');
+  return [{ name: 'app-check', command: ['npx', 'starci', 'app', 'check'], summary: null, env: {} }, ...(audit ? [audit] : []), ...present.map(scriptGate)];
+}
+
+/** Shared quality settings retain the release reader's audit validation, disabled mode and legacy string host compatibility. */
+function releaseServices(services, options) {
+  const audit = services?.audit ?? {};
+  if (!plain(audit) || (audit.in !== undefined && (!Array.isArray(audit.in) || !audit.in.every((scope) => typeof scope === 'string'))) || (audit.omitDev !== undefined && typeof audit.omitDev !== 'boolean')) throw refusal(RELEASE_CODE, 'services.audit must be a mapping with a string-list in and boolean omitDev');
+  const sonar = services?.sonar;
+  const compatible = typeof sonar?.host === 'string' ? { ...sonar, host: { public: sonar.host } } : sonar;
+  const quality = qualityServices({ services: { ...services, sonar: compatible } }, options);
+  if (audit.mode === 'disabled') quality.audit = null;
+  return quality;
+}
+
+/** The shared audit settings preserve release scope, level and development-dependency selection. */
+function auditGate(audit) {
+  if (!audit || !audit.in.includes('release-gate')) return null;
+  if (!['info', 'low', 'moderate', 'high', 'critical'].includes(audit.level)) throw refusal(RELEASE_CODE, 'services.audit.level must be an npm audit level');
+  return { name: 'audit', command: ['npm', 'audit', ...(audit.omitDev ? ['--omit=dev'] : []), `--audit-level=${audit.level}`], summary: null, env: {} };
+}
+
+/** A requested local Sonar scan uses only the declared host and token variable; the token never enters argv. */
+function sonarGate(services, env) {
+  const configured = services?.sonar;
+  const sonar = configured?.provider === 'sonarcloud' ? { ...configured, host: 'https://sonarcloud.io' } : configured;
+  const tokenName = sonar?.token;
+  if (!sonar?.host || !ENV_KEY.test(tokenName) || !env[tokenName]) throw refusal('RELEASE_SONAR_UNAVAILABLE', 'declare an enabled services.sonar host and set its ci.token environment variable');
+  const command = ['npx', '--yes', '@sonar/scan@4.3.0', `-Dsonar.host.url=${sonar.host}`];
+  const organization = sonar.organization ?? (sonar.organizationVar ? env[sonar.organizationVar] : null);
+  if (organization) command.push(`-Dsonar.organization=${organization}`);
+  if (!command.every((word) => TOKEN.test(word))) throw refusal('RELEASE_SONAR_UNAVAILABLE', 'Sonar host and organization must be plain command arguments');
+  return { name: 'sonar', command, summary: null, env: { SONAR_TOKEN: env[tokenName] }, provider: sonar,
+    credentialNames: [...new Set(['SONAR_TOKEN', tokenName])] };
+}
+
+function gateProblems(entry, at, seen) {
+  const found = [];
+  for (const key of Object.keys(entry)) if (!GATE_FIELDS.has(key)) found.push(`${at}.${key}: is not a field of a gate`);
+  if (typeof entry.name !== 'string' || !GATE_NAME.test(entry.name)) found.push(`${at}.name: must match ${GATE_NAME}`);
+  else if (seen.has(entry.name)) found.push(`${at}.name: ${entry.name} is declared twice`);
+  const command = entry.command;
+  if (!Array.isArray(command) || command.length === 0 || !command.every((word) => typeof word === 'string' && TOKEN.test(word))) found.push(`${at}.command: must be a non-empty list of plain words (no shell strings)`);
+  if (entry.summary !== undefined && entry.summary !== 'jest') found.push(`${at}.summary: must be jest`);
+  const env = entry.env ?? {};
+  if (!plain(env) || !Object.entries(env).every(([key, value]) => ENV_KEY.test(key) && typeof value === 'string')) found.push(`${at}.env: must map UPPER_CASE names to string values`);
+  return found;
+}
+
+function gatesOf(list, problems) {
+  if (!Array.isArray(list) || list.length === 0) {
+    problems.push('release.gates: must be a non-empty list');
+    return [];
+  }
+  const seen = new Set();
+  const gates = [];
+  list.forEach((entry, index) => {
+    const at = `release.gates[${index}]`;
+    const found = plain(entry) ? gateProblems(entry, at, seen) : [`${at}: must be a mapping`];
+    problems.push(...found);
+    if (found.length === 0) {
+      seen.add(entry.name);
+      gates.push({ name: entry.name, command: entry.command, summary: entry.summary ?? null, env: entry.env ?? {} });
+    }
+  });
+  return gates;
+}
+
+/** Judges the optional `release:` block. Absence is fine (defaults). Returns { config } or { problems }. */
+export function normalizeRelease(block, scripts = {}, services = {}, options = {}) {
+  const raw = block ?? {};
+  if (!plain(raw)) return { problems: ['release: must be a mapping'] };
+  const problems = Object.keys(raw).filter((key) => !FIELDS.has(key)).map((key) => `release.${key}: is not a field of the release block`);
+  const tagPrefix = raw.tagPrefix ?? 'v';
+  const defaultBranch = raw.defaultBranch ?? 'main';
+  const tagMatchesVersion = raw.tagMatchesVersion ?? 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');
+  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 };
+}
+
+/* ---- git through the seam */
+
+/** Runs git in the app root; a missing git or (unless allowFail) a non-zero exit is a failure whose message names the first stderr line. */
+export function git(ctx, args, { allowFail = false } = {}) {
+  const run = tool(ctx, 'git', args, { cwd: ctx.cwd, env: ctx.env });
+  if (run.error) throw failure('RELEASE_GIT_MISSING', `cannot run git (${run.error.message})`);
+  if (run.status !== 0 && !allowFail) throw failure('RELEASE_GIT_FAILED', `git ${args.slice(0, 2).join(' ')}: ${firstLine(run.stderr)}`);
+  return { code: run.status, stdout: String(run.stdout ?? '').trim(), stderr: String(run.stderr ?? '') };
+}
+
+/** The directory that holds the L4 records: <git common dir>/starci-release. */
+export const releaseDir = (ctx) => path.join(path.resolve(ctx.cwd, git(ctx, ['rev-parse', '--git-common-dir']).stdout), 'starci-release');
+
+/** Annotated tags `<prefix><digit>*` that point at HEAD (lightweight tags do not count: the hook ignores them). */
+export function annotatedOnHead(ctx, prefix) {
+  const names = lines(git(ctx, ['tag', '--points-at', 'HEAD', '--list', `${prefix}[0-9]*`]).stdout);
+  return names.filter((name) => git(ctx, ['cat-file', '-t', `refs/tags/${name}`], { allowFail: true }).stdout === 'tag');
+}
+
+const dirtyPaths = (ctx) => lines(git(ctx, ['status', '--porcelain', '--untracked-files=normal']).stdout);
+
+/** Tag names that exist locally or on the remote. */
+function takenTags(ctx, prefix, remote) {
+  const local = lines(git(ctx, ['tag', '--list', `${prefix}*`]).stdout);
+  const listed = lines(git(ctx, ['ls-remote', '--tags', remote], { allowFail: true }).stdout);
+  const remoteNames = listed.map((line) => line.split('refs/tags/')[1]?.replace(/\^\{\}$/u, '')).filter(Boolean);
+  return new Set([...local, ...remoteNames]);
+}
+
+/** Next free `<prefix><major>.<minor>.<n>` for the package version. */
+function nextFree(prefix, version, taken) {
+  const [, major, minor] = VERSION.exec(version);
+  for (let patch = 0; patch < MAX_PATCH; patch += 1) {
+    const candidate = `${prefix}${major}.${minor}.${patch}`;
+    if (!taken.has(candidate)) return candidate;
+  }
+  throw refusal('RELEASE_NO_FREE_TAG', `no free tag ${prefix}${major}.${minor}.0 to ${prefix}${major}.${minor}.${MAX_PATCH - 1}`);
+}
+
+/** The tag this release uses and its state: on-head (reused), free (will be created) or taken (exists on another commit). */
+function chooseTag(ctx, config, { prefix, remote }) {
+  const onHead = annotatedOnHead(ctx, prefix);
+  const taken = takenTags(ctx, prefix, remote);
+  const exact = `${prefix}${config.version}`;
+  const tag = config.tagMatchesVersion ? exact : (onHead[0] ?? nextFree(prefix, config.version, taken));
+  if (onHead.includes(tag)) return { tag, state: 'on-head' };
+  return { tag, state: taken.has(tag) ? 'taken' : 'free' };
+}
+
+/* ---- gate results */
+
+const sha256 = (file) => createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+
+const lineAfter = (text, label) => {
+  const found = text.split('\n').find((line) => line.startsWith(label));
+  return found === undefined ? null : found.slice(label.length).trim();
+};
+
+/** The jest summary lines of a log: { suites, failedSuites, tests, failed, passed } or null when jest printed none. */
+function jestSummary(text) {
+  const suites = lineAfter(text, 'Test Suites:');
+  const tests = lineAfter(text, 'Tests:');
+  if (suites === null || tests === null) return null;
+  const count = (line, word) => Number(new RegExp(String.raw`(\d+) ${word}`, 'u').exec(line)?.[1] ?? 0);
+  return {
+    suites: count(suites, 'total'), failedSuites: count(suites, 'failed'),
+    tests: count(tests, 'total'), failed: count(tests, 'failed'), passed: count(tests, 'passed'),
+  };
+}
+
+/** Judges a jest-style gate from its log: green needs suites that all passed, every test passed and no coverage threshold miss. */
+function judgeJest(text) {
+  const summary = jestSummary(text);
+  const misses = (text.match(THRESHOLD_MISS) ?? []).length;
+  if (!summary) return { pass: false, detail: 'no jest summary in the log', summary: null, misses };
+  const pass = summary.suites > 0 && summary.failedSuites === 0 && summary.failed === 0 && summary.passed === summary.tests && misses === 0;
+  const detail = `suites ${summary.suites - summary.failedSuites}/${summary.suites}, tests ${summary.passed}/${summary.tests}, coverage-threshold misses ${misses}`;
+  return { pass, detail, summary, misses };
+}
+
+/** [command, args] to start an argv; on Windows npm and npx are .cmd files, so they start through cmd.exe (words are validated, never a shell string). */
+export function launch(argv, platform) {
+  if (platform === 'win32' && WRAPPED.has(argv[0])) return ['cmd.exe', ['/d', '/s', '/c', ...argv]];
+  return [argv[0], argv.slice(1)];
+}
+
+/** Sonar availability is public and bounded; HTTP uses the existing injected fetch seam. */
+async function sonarAvailability(ctx, gate) {
+  const sonar = gate.provider;
+  if (!sonar) return null;
+  let up = false;
+  try {
+    const response = await ctx.fetch(sonar.host.replace(/\/$/u, '') + '/api/system/status', { signal: AbortSignal.timeout(10000) });
+    up = response.ok && (await response.json()).status === 'UP';
+  } catch { up = false; }
+  if (up) return null;
+  const detail = sonar.optional
+    ? `notice: sonar skipped: ${sonar.host} not reachable (services.sonar.optional)`
+    : `${SONAR_UNREACHABLE}: ${sonar.host} did not report UP within ten seconds`;
+  return { skipped: sonar.optional === true, pass: false, detail };
+}
+
+/** Unreachable optional providers remain explicit skipped rows, with a real log and no scan invocation. */
+async function runAvailableGate(ctx, gate, options) {
+  const availability = await sonarAvailability(ctx, gate);
+  const log = path.join(options.dir, `${gate.name}.log`);
+  if (!availability) {
+    if (!gate.provider) return runGate(ctx, gate, options);
+    // The scanner imports the app's declared external issues report: produce it first with the app's own lint, as the managed CI does.
+    const started = ctx.now();
+    const lint = produceLintReports(ctx, { launch, platform: options.platform, env: withoutCredentials(ctx.env, options.credentialNames) });
+    if (lint.pass) return judgeQualityGate(ctx, gate, runGate(ctx, gate, { ...options, preface: lint.text }));
+    fs.writeFileSync(log, lint.text);
+    return { name: gate.name, command: gate.command.join(' '), pass: false, detail: 'lint report failed (see log)', seconds: Math.round((ctx.now() - started) / 1000),
+      summary: null, log: path.resolve(log), logSha256: sha256(log), env: Object.keys(gate.env) };
+  }
+  fs.writeFileSync(log, availability.detail + '\n');
+  return { name: gate.name, command: gate.command.join(' '), ...availability, seconds: 0,
+    summary: null, log: path.resolve(log), logSha256: sha256(log), env: Object.keys(gate.env) };
+}
+
+/**
+ * A scanner that exited 0 only uploaded its report: the row passes when the server's quality gate of that analysis is OK
+ * (sonar-quality-gate.mjs). The verdict replaces the row's detail and is appended to its log; the row's time includes the wait.
+ */
+async function judgeQualityGate(ctx, gate, row) {
+  if (!row.pass) return row;
+  const started = ctx.now();
+  const verdict = await sonarQualityGate(ctx, { cwd: ctx.cwd, host: gate.provider.host, token: gate.env.SONAR_TOKEN });
+  const failed = (verdict.conditions ?? []).map((line) => `  failed: ${line}\n`).join('');
+  fs.appendFileSync(row.log, `\nquality gate: ${verdict.detail}\n${failed}`);
+  return { ...row, pass: verdict.pass, detail: verdict.detail, seconds: row.seconds + Math.round((ctx.now() - started) / 1000), logSha256: sha256(row.log) };
+}
+
+const withoutCredentials = (values, credentialNames) => {
+  const selected = new Set(credentialNames);
+  return Object.fromEntries(Object.entries(values ?? {}).filter(([key]) => !selected.has(key.toUpperCase())));
+};
+
+function runGate(ctx, gate, { dir, platform, credentialNames, preface = '' }) {
+  const log = path.join(dir, `${gate.name}.log`);
+  const started = ctx.now();
+  const [command, args] = launch(gate.command, platform);
+  // The native scanner alone consumes Sonar credentials; ordinary gates cannot inherit or reintroduce them.
+  const env = { ...ctx.env, ...(gate.provider ? gate.env : withoutCredentials(gate.env, credentialNames)) };
+  const run = tool(ctx, command, args, { cwd: ctx.cwd, env });
+  const output = `${run.stdout ?? ''}${run.stderr ?? ''}`;
+  const text = gate.name === 'sonar' && gate.env.SONAR_TOKEN ? output.replaceAll(gate.env.SONAR_TOKEN, '[REDACTED]') : output;
+  fs.writeFileSync(log, preface + text);
+  const verdict = judgeVerdict(run, gate, text);
+  if (gate.name === 'sonar' && gate.env.SONAR_TOKEN) verdict.detail = verdict.detail.replaceAll(gate.env.SONAR_TOKEN, '[REDACTED]');
+  const seconds = Math.round((ctx.now() - started) / 1000);
+  return {
+    name: gate.name, command: gate.command.join(' '), pass: verdict.pass, detail: verdict.detail, seconds,
+    summary: verdict.summary ?? null, log: path.resolve(log), logSha256: sha256(log), env: Object.keys(gate.env),
+  };
+}
+
+function judgeVerdict(run, gate, text) {
+  if (run.error) return { pass: false, detail: `cannot run (${run.error.message})` };
+  if (run.status !== 0) return { pass: false, detail: `exit ${run.status}` };
+  if (gate.summary === 'jest') return judgeJest(text);
+  return { pass: true, detail: 'exit 0' };
+}
+
+/* ---- the gate */
+
+function sourceProblem(ctx, source, head) {
+  if (source === 'HEAD') return null;
+  if (!refName(source)) return `--source ${source} is not a ref name`;
+  const resolved = git(ctx, ['rev-parse', '--verify', `${source}^{commit}`], { allowFail: true });
+  if (resolved.code !== 0) return `cannot resolve --source ${source}`;
+  if (resolved.stdout !== head) return `--source ${source} is ${resolved.stdout.slice(0, 10)} but HEAD is ${head.slice(0, 10)}: the hook and the L4 record are about HEAD; check the candidate out first`;
+  return null;
+}
+
+function tagLine({ tag, state }) {
+  if (state === 'on-head') return `tag            ${tag} (annotated, already on HEAD)`;
+  if (state === 'taken') return `tag            ${tag} (TAKEN by another commit)`;
+  return `tag            ${tag} (free: will be created, annotated)`;
+}
+
+/** Everything that can be known without running a gate: the facts, the red preconditions and the lines that describe them. */
+function inspect(ctx, config, options) {
+  const head = git(ctx, ['rev-parse', 'HEAD']).stdout;
+  const branch = git(ctx, ['rev-parse', '--abbrev-ref', 'HEAD'], { allowFail: true }).stdout;
+  const out = [`checkout       ${ctx.cwd}`, `HEAD           ${head} (${branch})`];
+  const red = [];
+  const problem = sourceProblem(ctx, options.source ?? 'HEAD', head);
+  if (problem) red.push(problem);
+  const dirty = dirtyPaths(ctx);
+  if (dirty.length > 0) red.push(`working tree is not clean (${dirty.length} path(s), first: ${dirty[0].slice(0, 100)}): the record would vouch for files that are not in HEAD`);
+  else out.push('worktree       clean');
+  const prefix = options.tagPrefix ?? config.tagPrefix;
+  if (!PREFIX.test(prefix)) throw refusal('RELEASE_USAGE', `--tag-prefix must match ${PREFIX}`);
+  const chosen = chooseTag(ctx, config, { prefix, remote: 'origin' });
+  if (chosen.state === 'taken') red.push(`tag ${chosen.tag} already exists on another commit (local or remote)`);
+  out.push(tagLine(chosen));
+  return { head, chosen, red, out };
+}
+
+function planLines(config, facts, dir, recordPath) {
+  const out = [`L4 record      ${recordPath}`, `logs           ${dir}`, '', 'gates (required gates must pass, optional provider outages are skipped, in this order):'];
+  for (const gate of config.gates) {
+    const summary = gate.summary ? ` (summary: ${gate.summary})` : '';
+    out.push(`  ${gate.name.padEnd(17)} ${gate.command.join(' ')}${summary}`);
+  }
+  out.push(`then: write ${path.basename(recordPath)} and \`git tag -a ${facts.chosen.tag}\` on ${facts.head.slice(0, 10)}; push it with \`starci app release push\`.`);
+  return out;
+}
+
+function assertUnmoved(ctx, head) {
+  const now = git(ctx, ['rev-parse', 'HEAD']).stdout;
+  if (now !== head) throw failure('RELEASE_HEAD_MOVED', `HEAD moved during the gates (${head.slice(0, 10)} -> ${now.slice(0, 10)}). No record.`);
+  const dirty = dirtyPaths(ctx);
+  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 }) {
+  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.',
+    gates: results,
+  };
+  fs.mkdirSync(path.dirname(recordPath), { recursive: true });
+  fs.writeFileSync(recordPath, `${JSON.stringify(record, null, 2)}\n`);
+}
+
+/** Gates run sequentially because each failure prevents subsequent commands and record creation. */
+async function runAll(ctx, config, options) {
+  fs.mkdirSync(options.dir, { recursive: true });
+  return config.gates.reduce(async (pending, gate) => {
+    const results = await pending;
+    if (results.some((result) => !result.pass && !result.skipped)) return results;
+    return [...results, await runAvailableGate(ctx, gate, options)];
+  }, Promise.resolve([]));
+}
+
+function summaryOf(result) {
+  let status = result.pass ? 'PASS' : 'FAIL';
+  if (result.skipped) status = 'SKIPPED';
+  return `${status} ${result.name} (${result.detail}, ${result.seconds}s) log ${result.log}`;
+}
+
+/**
+ * `starci app release gate`: dry run prints the preconditions, the gate list, the head and the tag; --execute runs every gate and, only if required gates pass,
+ * writes the L4 record and creates the annotated tag. options: { execute, sonar, source, tagPrefix, platform }.
+ */
+export async function releaseGate(ctx, config, options = {}) {
+  if (options.sonar) config = { ...config, gates: [...config.gates.filter((gate) => gate.name !== 'sonar'), sonarGate(config.services, ctx.env)] };
+  const credentialNames = config.gates.find(gate => gate.provider)?.credentialNames ?? ['SONAR_TOKEN', config.services?.sonar?.token].filter(Boolean);
+  ctx = Object.create(ctx, {env: {value: withoutCredentials(ctx.env, credentialNames)}});
+  // The CI verdict of a release is the candidate run of its own sha, judged by `starci app release push` (candidate-ci.mjs, OWNER RULING candidate-ci 2026-10-18):
+  // the gate no longer refuses over the latest default-branch run.
+  const facts = inspect(ctx, config, options);
+  const common = releaseDir(ctx);
+  const recordPath = path.join(common, `${facts.head}.l4.json`);
+  const dir = path.join(common, facts.head.slice(0, 12));
+  const plan = [...facts.out, ...planLines(config, facts, dir, recordPath)];
+  const base = { head: facts.head, tag: facts.chosen.tag, record: recordPath, gates: config.gates.map((gate) => gate.name) };
+  if (facts.red.length > 0) return { ok: false, lines: [...plan, ...facts.red.map((item) => `RED: ${item}`), 'nothing was run.'], data: { ...base, red: facts.red, executed: false } };
+  if (options.execute !== true) return { ok: true, lines: [...plan, '', 'dry run: no gate was run, nothing written. preconditions OK.'], data: { ...base, red: [], executed: false } };
+  const results = await runAll(ctx, config, { dir, platform: options.platform ?? process.platform, credentialNames });
+  const report = results.map(summaryOf);
+  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 });
+  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)}`;
+  return { ok: true, lines: [...plan, ...report, `L4 record written: ${recordPath}`, tagged], data: { ...base, executed: true, results, tagCreated: created } };
+}

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.25
     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.24
     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.3
     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.17
     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.17
     group: starci
     install: registry
     side: both

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/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": "ce01a03c949f8154644bec5d1068bf0b5316478f328b2231b2369c937f89e118",
   "global": [
     {
       "name": "json",
@@ -1234,6 +1234,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 +1249,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.json

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

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;
 }

package/sync/index.mjs

@@ -158,6 +158,24 @@ export async function loadPresets(root) {
   return { sonarExclusions: require(resolved).sonarExclusions() };
 }
 
+/**
+ * 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.
+ */
+const BUNDLED_SONAR_EXCLUSIONS = new URL('../runtime/packages/jest-preset/sonar-exclusions.json', 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'));
+  } 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');
+  }
+  return { sonarExclusions: list.join(',') };
+}
+
 /** Where the be unit run writes the lcov report (jest `coverageDirectory` coverage under be/, reporter lcov), from the app root. */
 const LCOV_REPORT = 'be/coverage/lcov.info';
 

package/templates/fe/transport/graphql/clients/links/retry.ts

@@ -11,6 +11,6 @@ export const createRetryLink = () =>
         delay: { initial: RETRY_POLICY.initialDelayMs, max: RETRY_POLICY.maxDelayMs, jitter: true },
         attempts: {
             max: RETRY_POLICY.maxAttempts,
-            retryIf: (error) => error !== undefined && !CombinedGraphQLErrors.is(error),
+            retryIf: (error) => !CombinedGraphQLErrors.is(error),
         },
     })

package/upgrade/index.mjs

@@ -18,6 +18,7 @@ import { byCodeUnit } from "../report/order.mjs";
 import {
   TEMPLATES_DIR,
   appSource,
+  bundledPresets,
   checkTargets,
   imageFiles,
   loadHfs,
@@ -48,7 +49,7 @@ const FULL_DEPENDENCIES = Object.freeze(["nest-commander"]);
 // ruling lacks (a current lite app already has it, and the e2e world's @starci/test-world is what full adds). These are the preset's two
 // public sync inputs; once apply resolves the new dependency, normal full sync reads them from @starci/jest-preset again.
 export const UPGRADE_PRESETS = Object.freeze({
-  sonarExclusions: "**/*.spec.ts,**/*.e2e-spec.ts,**/dist/**,**/coverage/**",
+  sonarExclusions: bundledPresets().sonarExclusions,
   coverageSources: Object.freeze([
     "src/**/*.service.ts",
     "src/features/cli/**/*.cli.ts",