@starci/hfs 4.7.45 → 4.7.46

package/runtime/scripts/hfs/rules/deploy-workflow.mjs

@@ -80,9 +80,9 @@ function hasAgeIdentity(job, doc) {
 
 /** The release candidate branches (OWNER RULING candidate-ci, 2026-10-18): `starci app release push` waits for the ci.yml run of the release sha there. */
 const CANDIDATE_BRANCHES = 'release/candidate-*';
-const pushFilterValid = (options) => record(options) && Object.keys(options).length > 0 && Object.keys(options).every((key) => key === 'tags' || key === 'branches')
+const pushFilterValid = (options, ci) => record(options) && Object.keys(options).length > 0 && Object.keys(options).every((key) => key === 'tags' || key === 'branches')
   && (options.tags === undefined || (Array.isArray(options.tags) && options.tags.length === 1 && options.tags[0] === 'v*'))
-  && (options.branches === undefined || (Array.isArray(options.branches) && options.branches.length === 1 && options.branches[0] === CANDIDATE_BRANCHES));
+  && (options.branches === undefined || (Array.isArray(options.branches) && options.branches.length > 0 && new Set(options.branches).size === options.branches.length && options.branches.every((branch) => branch === CANDIDATE_BRANCHES || (ci && branch === 'main'))));
 
 function triggerFindings(doc, refuse, file = '') {
   const on = workflowEventOptions(doc.on);
@@ -94,11 +94,11 @@ function triggerFindings(doc, refuse, file = '') {
   for (const [event, options] of Object.entries(on)) {
     if (event === 'workflow_dispatch') continue;
     if (event !== 'push') {
-      findings.push(refuse(TRIGGER, `trigger ${event} is forbidden; app CI starts only on release tags [v*], the release candidate branches or workflow_dispatch`));
+      findings.push(refuse(TRIGGER, `trigger ${event} is forbidden; app CI starts only on release tags [v*], the release candidate branches, main in ci.yml, or workflow_dispatch`));
       continue;
     }
-    if (!pushFilterValid(options)) {
-      findings.push(refuse(TRIGGER, `push may contain only tags: [v*] and branches: ['${CANDIDATE_BRANCHES}']; other branch and path filters are forbidden`));
+    if (!pushFilterValid(options, /(^|\/)ci\.ya?ml$/.test(file))) {
+      findings.push(refuse(TRIGGER, `push may contain only tags: [v*] and branches: ['${CANDIDATE_BRANCHES}']; ci.yml may also name main; other branch and path filters are forbidden`));
     }
   }
   return findings;

package/runtime/scripts/hfs/runtime-rules/git-triggers.mjs

@@ -0,0 +1,61 @@
+// CI_TRIGGERS_RELEASE_ONLY: runtime workflows and app ci.yml may judge main; release candidates, v* tags and manual dispatch retain their scope.
+import { parseWorkflow, workflowFindings } from './workflow-source.mjs';
+import { workflowEventOptions } from '../../lib/workflow-events.mjs';
+
+export const CODE = 'CI_TRIGGERS_RELEASE_ONLY';
+const RELEASE_TAGS = 'v*';
+const RUNTIME_BRANCH = 'main';
+/** The branch pattern of the release candidate refs (refs/heads/release/candidate-<version>), shared with the release flows. */
+export const CANDIDATE_BRANCHES = 'release/candidate-*';
+/** The workflows that judge an app release (every app ci.yml): they must run on the candidate refs. The runtime's own workflows judge each push to main instead. */
+const RELEASE_WORKFLOW = /(^|\/)ci\.ya?ml$/;
+
+const isReleaseTagFilter = (tags) => Array.isArray(tags) && tags.length === 1 && String(tags[0]) === RELEASE_TAGS;
+/** The branches a filter may name: main (runtime workflows and app ci.yml) and the candidate pattern. */
+const allowedBranches = (ownBranch) => (ownBranch ? [RUNTIME_BRANCH, CANDIDATE_BRANCHES] : [CANDIDATE_BRANCHES]);
+const isBranchFilter = (ownBranch, branches) => Array.isArray(branches) && branches.length > 0 && new Set(branches.map(String)).size === branches.length
+  && branches.every((branch) => allowedBranches(ownBranch).includes(String(branch)));
+const namesCandidate = (branches) => Array.isArray(branches) && branches.map(String).includes(CANDIDATE_BRANCHES);
+
+const missingFilterMessage = (ownBranch) => (ownBranch
+  ? `\`push\` must be filtered to \`tags: ['${RELEASE_TAGS}']\` and/or \`branches\` of [${RUNTIME_BRANCH}, '${CANDIDATE_BRANCHES}'] (no other branch starts CI)`
+  : `\`push\` must be filtered to \`tags: ['${RELEASE_TAGS}']\` and/or \`branches: ['${CANDIDATE_BRANCHES}']\` (no other branch starts an app's CI)`);
+
+const branchFilterMessage = (ownBranch) => (ownBranch
+  ? `\`push.branches\` may name only ${RUNTIME_BRANCH} and '${CANDIDATE_BRANCHES}', each once`
+  : `\`push.branches\` may name only '${CANDIDATE_BRANCHES}' in an example or an app template: its CI runs on the release candidate and the release tag`);
+
+function pushFindings({ ownBranch, config, refuse, release }) {
+  const filters = config && typeof config === 'object' && !Array.isArray(config) ? config : {};
+  const { tags, branches } = filters;
+  const found = [];
+  if (tags === undefined && branches === undefined) found.push(refuse(missingFilterMessage(ownBranch)));
+  if (tags !== undefined && !isReleaseTagFilter(tags)) found.push(refuse(`\`push.tags\` must be exactly ['${RELEASE_TAGS}']`));
+  if (branches !== undefined && !isBranchFilter(ownBranch, branches)) found.push(refuse(branchFilterMessage(ownBranch)));
+  if (release && !namesCandidate(branches)) found.push(refuse(`\`push.branches\` must name '${CANDIDATE_BRANCHES}': starci app release push waits for the CI run of the release sha on its candidate ref`));
+  for (const other of Object.keys(filters).filter((key) => key !== 'tags' && key !== 'branches')) found.push(refuse(`\`push.${other}\` is not allowed beside the trigger filters`));
+  return found;
+}
+
+function eventFindings({ event, config, ownBranch, refuse, release }) {
+  if (event === 'workflow_dispatch') return [];
+  if (event !== 'push') return [refuse(`the trigger \`${event}\` is not allowed: only a push of release tags [${RELEASE_TAGS}], of '${CANDIDATE_BRANCHES}' (and, in runtime workflows or app ci.yml, of branch ${RUNTIME_BRANCH}) and workflow_dispatch may start CI`)];
+  return pushFindings({ ownBranch, config, refuse, release });
+}
+
+/** The CI_TRIGGERS_RELEASE_ONLY findings of one workflow text; a text that is not YAML yields none (the other checks name it). Runtime workflows and app ci.yml may also push on main. */
+function workflowTriggerFindings({ path: file, text }) {
+  const doc = parseWorkflow(text);
+  if (!doc || typeof doc !== 'object') return [];
+  const ownBranch = file.startsWith('.github/workflows/') || RELEASE_WORKFLOW.test(file);
+  const refuse = (why) => ({ code: CODE, level: 'error', path: file, message: `${CODE} ${file}: ${why}` });
+  const on = doc.on;
+  if (on === undefined || on === null) return [refuse('the workflow has no `on` trigger block: it must declare push of tags [v*] and/or workflow_dispatch')];
+  const events = workflowEventOptions(on, String);
+  const release = !file.startsWith('.github/workflows/') && RELEASE_WORKFLOW.test(file);
+  const missingPush = release && !Object.hasOwn(events, 'push') ? [refuse(`the app release workflow must run on a push of '${CANDIDATE_BRANCHES}' and of tags [${RELEASE_TAGS}]`)] : [];
+  return [...missingPush, ...Object.entries(events).flatMap(([event, config]) => eventFindings({ event, config, ownBranch, refuse, release }))];
+}
+
+/** CI_TRIGGERS_RELEASE_ONLY over every tracked workflow (ctx of scripts/hfs/runtime-check.mjs). */
+export const gitTriggerFindings = (ctx) => workflowFindings(ctx, workflowTriggerFindings);

package/runtime/scripts/hfs/runtime-rules/hook-shape.mjs

@@ -1,9 +1,7 @@
 // hook-shape.mjs - RT_HOOK_SHAPE (knowledge/hfs/rules.yaml, gate runtime): the app hook templates keep the gate model.
 //   pre-commit  L0 only: no typecheck and no test run (`test:` scripts, npm test, jest, vitest, a spec). Types and the targeted specs
 //               belong to the op gate.
-//   pre-push    a release gate check, never a build or test run: no npm test, jest, vitest, typecheck or lint, and it carries the
-//               release gate markers: `starci-release` (the L4 record directory), `refs/backup/` (the backup namespace) and `v[0-9]`
-//               (the release tag pattern). A push of anything but the release cut and refs/backup/* is refused there.
+//   pre-push    the bundled push gate owns fast-forward main, annotated tags and the secret scan; no build, test or lint run.
 // Guard hooks keep their host timeout above the runtime's own input, verdict, cleanup and output budgets.
 // Comments are not judged (the templates explain what they do not run). Pure apart from ctx.read.
 import { shellCommandSource } from '../../lib/shell-source.mjs';
@@ -25,7 +23,7 @@ const PRE_PUSH_FORBIDDEN = [
   [/\btypecheck\b/, 'a typecheck'],
   [/\blint\b/, 'a lint run'],
 ];
-const PRE_PUSH_MARKERS = ['starci-release', 'refs/backup/', 'v[0-9]', 'RIGHTS_PUSH_NOT_RELEASE'];
+const PRE_PUSH_MARKERS = ["node --input-type=module -e", "import { main } from '@starci/hfs/runtime/scripts/guards/release-push-gate.mjs'", 'process.exit(await main())'];
 
 const finding = (file, message) => ({ code: CODE, level: 'error', path: file, message: `${CODE} ${file}: ${message}` });
 
@@ -35,13 +33,13 @@ function fileHookShapeFindings({ path: file, name, text }) {
   const found = [];
   const forbidden = name === 'pre-commit' ? PRE_COMMIT_FORBIDDEN : PRE_PUSH_FORBIDDEN;
   for (const [pattern, what] of forbidden) {
-    if (pattern.test(body)) found.push(finding(file, name === 'pre-commit' ? `the commit gate is L0 only and runs ${what}; types and targeted specs belong to the op gate` : `the push gate checks the release gate and runs ${what}; only the release cut tests`));
+    if (pattern.test(body)) found.push(finding(file, name === 'pre-commit' ? `the commit gate is L0 only and runs ${what}; types and targeted specs belong to the op gate` : `the push gate runs ${what}; it must use the bundled push policy alone`));
   }
   if (name === 'pre-push') {
     const missing = PRE_PUSH_MARKERS.filter((marker) => !body.includes(marker));
     if (missing.length) {
       const markers = missing.map((m) => `\`${m}\``).join(', ');
-      found.push(finding(file, `the push gate lacks the release gate marker${missing.length === 1 ? '' : 's'} ${markers}; it must check the L4 record of HEAD and allow only the release cut and refs/backup/*`));
+      found.push(finding(file, `the push gate lacks the bundled gate marker${missing.length === 1 ? '' : 's'} ${markers}; it must invoke the shared fast-forward, annotation and secret-scan policy`));
     }
   }
   return found;

package/runtime/scripts/lib/release-version.mjs

@@ -1,134 +1,134 @@
-// release-version.mjs - the one reading of a release version (owner ruling release-waves). A prerelease `<label>.N` opens the release
-// line N and `<label>.N.M` is the M-th release after it, a wave or a fix alike, so alpha.31 < alpha.31.1 < alpha.31.2 < alpha.32 in
-// SemVer order. The next release is derived from the highest one already released, never guessed. The legacy `<label>.N-fix.K` still
-// reads as release K after `<label>.N` and is never produced again. Pure: the callers read the tags and the registry.
-
-const NUMERIC = /^(?:0|[1-9]\d*)$/;
-const POSITIVE = /^[1-9]\d*$/;
-const IDENTIFIERS = /^[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*$/;
-const LEGACY_FIX = '-fix.';
-
-/** {base, wave, legacy}: the release a version counts its waves from, and its wave M (0 for the release that opens the line). */
-export function waveOf(version) {
-  const text = String(version ?? '').split('+')[0];
-  const fix = text.lastIndexOf(LEGACY_FIX);
-  const legacyWave = fix > 0 ? text.slice(fix + LEGACY_FIX.length) : '';
-  if (POSITIVE.test(legacyWave)) return { base: text.slice(0, fix), wave: Number(legacyWave), legacy: true };
-  const ids = text.split('.');
-  const counted = ids.length > 3 && POSITIVE.test(ids.at(-1)) && (text.includes('-') ? NUMERIC.test(ids.at(-2)) : ids.length === 4);
-  return counted ? { base: ids.slice(0, -1).join('.'), wave: Number(ids.at(-1)), legacy: false } : { base: text, wave: 0, legacy: false };
-}
-
-/** Parsed SemVer identifiers {core, pre} of `version`; an unreadable version throws. */
-export function versionParts(version) {
-  const parts = typeof version === 'string' ? version.split('+') : [];
-  if (!parts.length || parts.length > 2 || (parts.length === 2 && !IDENTIFIERS.test(parts[1]))) throw new Error(`unreadable release version ${version}`);
-  const boundary = parts[0].indexOf('-');
-  const core = (boundary < 0 ? parts[0] : parts[0].slice(0, boundary)).split('.');
-  const prerelease = boundary < 0 ? null : parts[0].slice(boundary + 1);
-  if (core.length !== 3 || core.some((part) => !NUMERIC.test(part)) || (prerelease !== null && !IDENTIFIERS.test(prerelease))) throw new Error(`unreadable release version ${version}`);
-  const pre = prerelease?.split('.') ?? [];
-  if (pre.some((part) => /^0\d+$/.test(part))) throw new Error(`invalid numeric prerelease identifier in ${version}`);
-  return { core: core.map(BigInt), pre };
-}
-
-const readable = (version) => {
-  try {
-    versionParts(version);
-    return true;
-  } catch {
-    return false;
-  }
-};
-
-/** The SemVer spelling a version is ordered by: a legacy `-fix.K` orders as wave K of its line. */
-const ordered = (version) => {
-  const { base, wave, legacy } = waveOf(version);
-  return legacy ? `${base}.${wave}` : version;
-};
-
-const compareIdentifier = (a, b) => {
-  const numericA = /^\d+$/.test(a), numericB = /^\d+$/.test(b);
-  if (numericA && numericB) return BigInt(a) < BigInt(b) ? -1 : Number(BigInt(a) > BigInt(b));
-  if (numericA !== numericB) return numericA ? -1 : 1;
-  return a < b ? -1 : Number(a > b);
-};
-
-/** SemVer precedence, numeric prerelease identifiers included; build metadata has no precedence. */
-export function compareVersions(a, b) {
-  const left = versionParts(ordered(a)), right = versionParts(ordered(b));
-  for (const i of left.core.keys()) {
-    if (left.core[i] !== right.core[i]) return left.core[i] < right.core[i] ? -1 : 1;
-  }
-  if (!left.pre.length || !right.pre.length) return Number(!left.pre.length) - Number(!right.pre.length);
-  for (let i = 0; i < Math.max(left.pre.length, right.pre.length); i += 1) {
-    if (left.pre[i] === undefined) return -1;
-    if (right.pre[i] === undefined) return 1;
-    const compared = compareIdentifier(left.pre[i], right.pre[i]);
-    if (compared) return compared;
-  }
-  return 0;
-}
-
-/** The release line of `version`: a prerelease's core and the identifiers before its first number (every alpha.N and alpha.N.M share one), a stable release's major and minor. */
-export function releaseLine(version) {
-  const { core, pre } = versionParts(ordered(version));
-  if (!pre.length) return `${core.slice(0, 2).join('.')}-stable`;
-  const first = pre.findIndex((id) => /^\d+$/.test(id));
-  return `${core.join('.')}-${(first < 0 ? pre : pre.slice(0, first)).join('.')}`;
-}
-
-/** {family, line} of a release that opens a line (`<x.y.z>-<label>.N`), or null for any other shape. */
-function lineStart(base) {
-  if (!readable(base)) return null;
-  const { core, pre } = versionParts(base);
-  return pre.length === 2 && !/^\d+$/.test(pre[0]) && NUMERIC.test(pre[1]) ? { family: `${core.join('.')}-${pre[0]}`, line: Number(pre[1]) } : null;
-}
-
-/** The next wave after `version`: its base with M one past the highest wave of that base among `version` and `known`. */
-export function nextWave(version, known = []) {
-  const { base } = waveOf(version);
-  const waves = [version, ...known].map(waveOf).filter((entry) => entry.base === base).map((entry) => entry.wave);
-  return `${base}.${Math.max(0, ...waves) + 1}`;
-}
-
-/** The family of a version: its core and label up to `-<label>` (`1.0.0-alpha`), or null for a stable or unlabelled version. */
-export function familyOf(version) {
-  if (!readable(version)) return null;
-  const { core, pre } = versionParts(ordered(version));
-  return pre.length && !/^\d+$/.test(pre[0]) ? `${core.join('.')}-${pre[0]}` : null;
-}
-
-/**
- * What may follow the highest line-shaped release of `versions`: {highest, family, wave, line}, or null when none has that shape.
- * With a `candidate`, a family that already has released tags is judged alone (another family's tags, such as legacy 2.0.1-alpha.N,
- * never outrank the candidate's own line); a family without a tag falls back to the highest release overall.
- */
-export function nextReleases(versions, candidate = null) {
-  const shaped = versions.filter((version) => readable(version) && lineStart(waveOf(version).base));
-  const family = candidate === null ? null : familyOf(candidate);
-  const own = family === null ? [] : shaped.filter((version) => lineStart(waveOf(version).base).family === family);
-  const pool = own.length ? own : shaped;
-  if (!pool.length) return null;
-  const highest = pool.reduce((top, version) => (compareVersions(version, top) > 0 ? version : top));
-  const start = lineStart(waveOf(highest).base);
-  return { highest, family: start.family, wave: nextWave(highest, pool), line: `${start.family}.${start.line + 1}` };
-}
-
-/**
- * Why `version` cannot be released after `released` (the versions already tagged), or null when it can: the next wave of the highest
- * release of its own family, the first release of the next line, or (when its family has no tag) a later release of another label or
- * core than the highest. The legacy `-fix` form is always refused.
- */
-export function releaseVersionRefusal(version, released) {
-  const next = nextReleases(released.filter((entry) => entry !== version), version);
-  const named = next ? `; the next release is ${next.wave} (the next wave or fix after ${next.highest}) or ${next.line} (the next line)` : '';
-  if (waveOf(version).legacy) return `${version} is the legacy -fix form, which is read and never released again${named}`;
-  if (!next || version === next.wave || version === next.line) return null;
-  if (!readable(version)) return `${version} is not a SemVer version${named}`;
-  if (lineStart(waveOf(version).base)?.family !== next.family && compareVersions(version, next.highest) > 0) return null;
-  return `${version} does not follow ${next.highest}${named}`;
-}
-
-/** The versions of the release tags `v<version>` in the output of `git tag --list`. */
-export const taggedVersions = (listing) => String(listing ?? '').split(/\r?\n/).map((name) => name.trim()).filter((name) => /^v\d/.test(name)).map((name) => name.slice(1));
+// release-version.mjs - the one reading of a release version (owner ruling release-waves). A prerelease `<label>.N` opens the release
+// line N and `<label>.N.M` is the M-th release after it, a wave or a fix alike, so alpha.31 < alpha.31.1 < alpha.31.2 < alpha.32 in
+// SemVer order. The next release is derived from the highest one already released, never guessed. The legacy `<label>.N-fix.K` still
+// reads as release K after `<label>.N` and is never produced again. Pure: the callers read the tags and the registry.
+
+const NUMERIC = /^(?:0|[1-9]\d*)$/;
+const POSITIVE = /^[1-9]\d*$/;
+const IDENTIFIERS = /^[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*$/;
+const LEGACY_FIX = '-fix.';
+
+/** {base, wave, legacy}: the release a version counts its waves from, and its wave M (0 for the release that opens the line). */
+export function waveOf(version) {
+  const text = String(version ?? '').split('+')[0];
+  const fix = text.lastIndexOf(LEGACY_FIX);
+  const legacyWave = fix > 0 ? text.slice(fix + LEGACY_FIX.length) : '';
+  if (POSITIVE.test(legacyWave)) return { base: text.slice(0, fix), wave: Number(legacyWave), legacy: true };
+  const ids = text.split('.');
+  const counted = ids.length > 3 && POSITIVE.test(ids.at(-1)) && (text.includes('-') ? NUMERIC.test(ids.at(-2)) : ids.length === 4);
+  return counted ? { base: ids.slice(0, -1).join('.'), wave: Number(ids.at(-1)), legacy: false } : { base: text, wave: 0, legacy: false };
+}
+
+/** Parsed SemVer identifiers {core, pre} of `version`; an unreadable version throws. */
+export function versionParts(version) {
+  const parts = typeof version === 'string' ? version.split('+') : [];
+  if (!parts.length || parts.length > 2 || (parts.length === 2 && !IDENTIFIERS.test(parts[1]))) throw new Error(`unreadable release version ${version}`);
+  const boundary = parts[0].indexOf('-');
+  const core = (boundary < 0 ? parts[0] : parts[0].slice(0, boundary)).split('.');
+  const prerelease = boundary < 0 ? null : parts[0].slice(boundary + 1);
+  if (core.length !== 3 || core.some((part) => !NUMERIC.test(part)) || (prerelease !== null && !IDENTIFIERS.test(prerelease))) throw new Error(`unreadable release version ${version}`);
+  const pre = prerelease?.split('.') ?? [];
+  if (pre.some((part) => /^0\d+$/.test(part))) throw new Error(`invalid numeric prerelease identifier in ${version}`);
+  return { core: core.map(BigInt), pre };
+}
+
+const readable = (version) => {
+  try {
+    versionParts(version);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/** The SemVer spelling a version is ordered by: a legacy `-fix.K` orders as wave K of its line. */
+const ordered = (version) => {
+  const { base, wave, legacy } = waveOf(version);
+  return legacy ? `${base}.${wave}` : version;
+};
+
+const compareIdentifier = (a, b) => {
+  const numericA = /^\d+$/.test(a), numericB = /^\d+$/.test(b);
+  if (numericA && numericB) return BigInt(a) < BigInt(b) ? -1 : Number(BigInt(a) > BigInt(b));
+  if (numericA !== numericB) return numericA ? -1 : 1;
+  return a < b ? -1 : Number(a > b);
+};
+
+/** SemVer precedence, numeric prerelease identifiers included; build metadata has no precedence. */
+export function compareVersions(a, b) {
+  const left = versionParts(ordered(a)), right = versionParts(ordered(b));
+  for (const i of left.core.keys()) {
+    if (left.core[i] !== right.core[i]) return left.core[i] < right.core[i] ? -1 : 1;
+  }
+  if (!left.pre.length || !right.pre.length) return Number(!left.pre.length) - Number(!right.pre.length);
+  for (let i = 0; i < Math.max(left.pre.length, right.pre.length); i += 1) {
+    if (left.pre[i] === undefined) return -1;
+    if (right.pre[i] === undefined) return 1;
+    const compared = compareIdentifier(left.pre[i], right.pre[i]);
+    if (compared) return compared;
+  }
+  return 0;
+}
+
+/** The release line of `version`: a prerelease's core and the identifiers before its first number (every alpha.N and alpha.N.M share one), a stable release's major and minor. */
+export function releaseLine(version) {
+  const { core, pre } = versionParts(ordered(version));
+  if (!pre.length) return `${core.slice(0, 2).join('.')}-stable`;
+  const first = pre.findIndex((id) => /^\d+$/.test(id));
+  return `${core.join('.')}-${(first < 0 ? pre : pre.slice(0, first)).join('.')}`;
+}
+
+/** {family, line} of a release that opens a line (`<x.y.z>-<label>.N`), or null for any other shape. */
+function lineStart(base) {
+  if (!readable(base)) return null;
+  const { core, pre } = versionParts(base);
+  return pre.length === 2 && !/^\d+$/.test(pre[0]) && NUMERIC.test(pre[1]) ? { family: `${core.join('.')}-${pre[0]}`, line: Number(pre[1]) } : null;
+}
+
+/** The next wave after `version`: its base with M one past the highest wave of that base among `version` and `known`. */
+export function nextWave(version, known = []) {
+  const { base } = waveOf(version);
+  const waves = [version, ...known].map(waveOf).filter((entry) => entry.base === base).map((entry) => entry.wave);
+  return `${base}.${Math.max(0, ...waves) + 1}`;
+}
+
+/** The family of a version: its core and label up to `-<label>` (`1.0.0-alpha`), or null for a stable or unlabelled version. */
+export function familyOf(version) {
+  if (!readable(version)) return null;
+  const { core, pre } = versionParts(ordered(version));
+  return pre.length && !/^\d+$/.test(pre[0]) ? `${core.join('.')}-${pre[0]}` : null;
+}
+
+/**
+ * What may follow the highest line-shaped release of `versions`: {highest, family, wave, line}, or null when none has that shape.
+ * With a `candidate`, a family that already has released tags is judged alone (another family's tags, such as legacy 2.0.1-alpha.N,
+ * never outrank the candidate's own line); a family without a tag falls back to the highest release overall.
+ */
+export function nextReleases(versions, candidate = null) {
+  const shaped = versions.filter((version) => readable(version) && lineStart(waveOf(version).base));
+  const family = candidate === null ? null : familyOf(candidate);
+  const own = family === null ? [] : shaped.filter((version) => lineStart(waveOf(version).base).family === family);
+  const pool = own.length ? own : shaped;
+  if (!pool.length) return null;
+  const highest = pool.reduce((top, version) => (compareVersions(version, top) > 0 ? version : top));
+  const start = lineStart(waveOf(highest).base);
+  return { highest, family: start.family, wave: nextWave(highest, pool), line: `${start.family}.${start.line + 1}` };
+}
+
+/**
+ * Why `version` cannot be released after `released` (the versions already tagged), or null when it can: the next wave of the highest
+ * release of its own family, the first release of the next line, or (when its family has no tag) a later release of another label or
+ * core than the highest. The legacy `-fix` form is always refused.
+ */
+export function releaseVersionRefusal(version, released) {
+  const next = nextReleases(released.filter((entry) => entry !== version), version);
+  const named = next ? `; the next release is ${next.wave} (the next wave or fix after ${next.highest}) or ${next.line} (the next line)` : '';
+  if (waveOf(version).legacy) return `${version} is the legacy -fix form, which is read and never released again${named}`;
+  if (!next || version === next.wave || version === next.line) return null;
+  if (!readable(version)) return `${version} is not a SemVer version${named}`;
+  if (lineStart(waveOf(version).base)?.family !== next.family && compareVersions(version, next.highest) > 0) return null;
+  return `${version} does not follow ${next.highest}${named}`;
+}
+
+/** The versions of the release tags `v<version>` in the output of `git tag --list`. */
+export const taggedVersions = (listing) => String(listing ?? '').split(/\r?\n/).map((name) => name.trim()).filter((name) => /^v\d/.test(name)).map((name) => name.slice(1));

package/runtime/scripts/machine/home.mjs

@@ -49,7 +49,7 @@ export const STARTUP_RESERVATION_MS = 180_000;
 
 export const DEFAULTS = Object.freeze({
   workers: Object.freeze({ base: 0, max: 0, hardMax: 10 }),
-  landGate: Object.freeze({ mode: 'shared' }),
+  landGate: Object.freeze({ mode: 'shared', push: true }),
   frozenMinutes: 10,
   pollIntervalMs: 600_000,
 });
@@ -194,7 +194,7 @@ export function supervisorSettings({ config = undefined } = {}) {
     pollIntervalMs: Number.isInteger(sup.pollIntervalMs) ? sup.pollIntervalMs : DEFAULTS.pollIntervalMs,
     workers: { base: Number.isInteger(sup.workers?.base) ? sup.workers.base : DEFAULTS.workers.base,
       max: Math.min(DEFAULTS.workers.hardMax, Number.isInteger(sup.workers?.max) ? sup.workers.max : DEFAULTS.workers.max) },
-    landGate: { mode: sup.landGate?.mode === 'exclusive' ? 'exclusive' : DEFAULTS.landGate.mode },
+    landGate: { mode: sup.landGate?.mode === 'exclusive' ? 'exclusive' : DEFAULTS.landGate.mode, push: typeof sup.landGate?.push === 'boolean' ? sup.landGate.push : DEFAULTS.landGate.push },
     // supervisor-watchdog.mjs: a busy seat frame with no turn progress for this long is frozen, not busy.
     frozenMinutes: Number.isInteger(sup.frozenMinutes) && sup.frozenMinutes > 0 ? sup.frozenMinutes : DEFAULTS.frozenMinutes,
     language: typeof cfg?.language === 'string' ? cfg.language : DEFAULT_OWNER_LANGUAGE,

package/templates/app/ci-workflows/github/workflows/ci.yml

@@ -1,10 +1,10 @@
 {{header}}
 name: ci
 
-# The release candidate ref first (starci app release push waits for this run of the release sha before the branch and the tag move), then the tag.
+# CI judges main, release candidates and release tags.
 on:
   push:
-    branches: ["release/candidate-*"]
+    branches: ["main", "release/candidate-*"]
     tags: ["v*"]
   workflow_dispatch:
 

package/templates/app/ci-workflows-lite/github/workflows/ci.yml

@@ -1,10 +1,10 @@
 {{header}}
 name: ci
 
-# The release candidate ref first (starci app release push waits for this run of the release sha before the branch and the tag move), then the tag.
+# CI judges main, release candidates and release tags.
 on:
   push:
-    branches: ["release/candidate-*"]
+    branches: ["main", "release/candidate-*"]
     tags: ["v*"]
   workflow_dispatch:
 

package/templates/app/hooks/husky/pre-push

@@ -1,57 +1,4 @@
 {{header}}
-# Push gate: a release gate check, never a test run. Nothing but the release cut pushes main or a release tag, and the coordinator
-# backs work up under refs/backup/*. Git hands this hook one line per ref: <local ref> <local sha> <remote ref> <remote sha>.
-#   refs/backup/*                  allowed: the coordinator backup namespace
-#   refs/heads/main, refs/tags/v*  allowed only when HEAD carries an annotated tag v[0-9]* and the release cut recorded the
-#                                  full suite of HEAD: <git common dir>/starci-release/<HEAD sha>.l4.json names that head and tag;
-#                                  a pushed tag must be that tag and must point at HEAD
-#   refs/heads/release/candidate-* the release candidate (starci app release push sends the release sha there first and moves main
-#                                  and the tag only when its ci.yml run is green): allowed under the same release gate, never deleted
-#   any other ref, a delete        refused
-common=$(git rev-parse --git-common-dir)
-case "$common" in /* | [A-Za-z]:*) ;; *) common="$(pwd)/$common" ;; esac
-head=$(git rev-parse HEAD)
-record="$common/starci-release/$head.l4.json"
-status=0
-gate=""
-gate_tag=""
-refuse() {
-  echo "RIGHTS_PUSH_NOT_RELEASE: $1 - the allowed path is the release cut (main, v* tags and the release/candidate-* ref) or refs/backup/* (backups)" >&2
-  status=1
-}
-# gate: the verdict of the release gate for HEAD, computed once: "ok" or the reason it is closed.
-release_gate() {
-  if [ -n "$gate" ]; then return 0; fi
-  gate="no annotated tag v[0-9]* on HEAD $head"
-  tags=$(git tag --points-at HEAD --list 'v[0-9]*' 2>/dev/null) || { gate="cannot list the tags of HEAD $head"; return 0; }
-  for tag in $tags; do
-    kind=$(git cat-file -t "refs/tags/$tag" 2>/dev/null) || continue
-    if [ "$kind" != "tag" ]; then continue; fi
-    if [ ! -f "$record" ]; then gate="no L4 record $record"; continue; fi
-    flat=$(tr -d ' \t\r\n' < "$record")
-    case "$flat" in
-      *'"head":"'"$head"'"'*'"tag":"'"$tag"'"'* | *'"tag":"'"$tag"'"'*'"head":"'"$head"'"'*) gate="ok"; gate_tag="$tag"; return 0 ;;
-    esac
-    gate="the L4 record $record does not name head $head and tag $tag"
-  done
-  return 0
-}
-while read -r local_ref local_sha remote_ref remote_sha; do
-  case "$remote_ref" in
-    refs/backup/*) ;;
-    refs/heads/main | refs/tags/v* | refs/heads/release/candidate-*)
-      case "$local_sha" in
-        *[!0]*) ;;
-        *) refuse "refusing to delete $remote_ref"; continue ;;
-      esac
-      release_gate
-      if [ "$gate" != "ok" ]; then refuse "$remote_ref is closed: $gate"; continue; fi
-      case "$remote_ref" in
-        refs/tags/*)
-          if [ "$remote_ref" != "refs/tags/$gate_tag" ]; then refuse "$remote_ref is not the release tag $gate_tag of HEAD $head"
-          elif [ "$(git rev-parse "$local_sha^{commit}" 2>/dev/null)" != "$head" ]; then refuse "$remote_ref does not point at HEAD $head"; fi ;;
-      esac ;;
-    *) refuse "refusing to push $remote_ref" ;;
-  esac
-done
-exit "$status"
+# Push gate: fast-forward main with a clean secret scan, annotated v* tags, and bounded ref input.
+# The bundled gate owns the policy; backups and lane refs use the same policy as the runtime.
+node --input-type=module -e "import { main } from '@starci/hfs/runtime/scripts/guards/release-push-gate.mjs'; process.exit(await main());"

package/release/supabase-bucket.mjs

@@ -1,8 +0,0 @@
-// supabase-bucket.mjs - select storage configuration from a local stack's migrated bucket ids.
-
-/** Returns no bucket variable for no ids, selects the sole id, and refuses ambiguous storage with every id listed. */
-export function storageBucketEnv(ids) {
-  if (ids.length === 0) return {};
-  if (ids.length === 1) return { STORAGE_S3_BUCKET: ids[0] };
-  throw new Error(`Local Supabase storage has multiple buckets: ${ids.map((id) => JSON.stringify(id)).join(', ')}; app configuration must name which bucket to use`);
-}

package/runtime/scripts/api/fs/write-json-file.mjs

@@ -1,10 +0,0 @@
-// write-json-file.mjs - one JSON document written to a file (the runtime's pretty-printed state files).
-import fs from 'node:fs';
-import path from 'node:path';
-
-/** `value` written to `file` as two-space JSON plus a trailing newline (parent directories created). */
-export function writeJsonFile(file, value) {
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}
-`);
-}

package/runtime/scripts/api/git/merge-base-query.mjs

@@ -1,5 +0,0 @@
-// merge-base-query.mjs — `git merge-base <args>`: one merge-base query (the best common ancestor, or --is-ancestor's exit status).
-import { runGit } from './lib.mjs';
-
-/** The spawn result {status, stdout, stderr, error} of `git merge-base ...args`; options are runGit's (cwd or dir, config, timeout, maxBuffer, input, encoding, env, git). */
-export const mergeBaseQuery = (args = [], options = {}) => runGit(['merge-base', ...args], options);

package/runtime/scripts/gates/commit-proof.mjs

@@ -1,53 +0,0 @@
-// commit-proof.mjs — locations and file IO for a commit's verification and release evidence. Each producer owns its schema.
-import fs from 'node:fs';
-import path from 'node:path';
-import { runtimeStateDir, starciLocalRoot } from '../../engine/runtime-root.mjs';
-import { sha256 } from '../../engine/digest.mjs';
-import { readJsonFile } from '../lib/json.mjs';
-import { sameResolvedPath } from '../lib/path-key.mjs';
-import { writeJsonFile } from '../api/fs/write-json-file.mjs';
-
-const RELEASE_KINDS = Object.freeze({ l4: 'l4', affected: 'affected', rows: 'l4-rows', ci: 'ci', report: 'affected-report' });
-const SHORT = 12;
-/** The local git note namespace used to write and read land proof. */
-export const LAND_NOTE_REF = 'land';
-
-/** The directory shared by release proofs of every worktree of a repository. */
-const proofDirOf = (commonDir) => path.join(commonDir, 'starci-release');
-
-/** The location of an affected, verify, deploy/check or release receipt; existing references keep their established paths. */
-export function proofFileOf({ kind, sha, base, root, env, commonDir }) {
-  if (kind === 'verify') return path.join(runtimeStateDir(root), 'verify', `${sha}.json`);
-  if (kind === 'affected-receipt') return path.join(runtimeStateDir(root), 'affected', `${String(base).slice(0, SHORT)}-${String(sha).slice(0, SHORT)}.json`);
-  if (kind === 'deploy') return path.join(starciLocalRoot(env), 'deploy', 'receipts', `${sha}.json`);
-  if (!Object.hasOwn(RELEASE_KINDS, kind)) throw new Error(`unknown commit proof kind: ${kind}`);
-  return path.join(proofDirOf(commonDir), `${sha}.${RELEASE_KINDS[kind]}.json`);
-}
-
-/** Every release proof of one kind under the git common directory, or [] when the directory is absent. */
-export function proofFilesOf({ commonDir, kind }) {
-  if (!Object.hasOwn(RELEASE_KINDS, kind)) throw new Error(`unknown release proof kind: ${kind}`);
-  const folder = proofDirOf(commonDir);
-  const suffix = `.${RELEASE_KINDS[kind]}.json`;
-  return fs.existsSync(folder) ? fs.readdirSync(folder).filter((name) => name.endsWith(suffix)).map((name) => path.join(folder, name)) : [];
-}
-
-/** Writes one receipt atomically; a reader sees a complete JSON document. Returns its file. */
-export function writeProofFile(file, record) {
-  const tmp = `${file}.${process.pid}.tmp`;
-  writeJsonFile(tmp, record);
-  fs.renameSync(tmp, file);
-  return file;
-}
-
-/** A proof file's parsed document, or null when it is missing, unreadable or malformed; its producer validates the schema. */
-export const readProofFile = (file) => readJsonFile(file, null);
-
-/** The digest of the schema's ordered binding fields. */
-export const proofDigest = (fields) => sha256(fields.join('\n'));
-
-/** Whether a receipt binds the requested commit and tree. */
-export const proofBinds = (record, { sha, tree }) => record?.sha === sha && record?.tree === tree;
-
-/** Whether the specs judged this source root; a missing root never supplies proof for another checkout. */
-export const judgedIn = (recorded, root) => typeof recorded === 'string' && recorded !== '' && sameResolvedPath(recorded, root);