@starci/hfs 4.6.0 → 4.7.0

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": "93fd9007c93fe7430043d8b6682fd46dd0e1d5f9f9b7094fc94ffad2ccdcceeb",
+  "hash": "441c47efec9ac314fb4ffd8b203fd6469aac65710ca9cd12aace0c032c2c537f",
   "global": [
     {
       "name": "json",
@@ -177,7 +177,7 @@ export const CATALOG = {
           "runtimeSide": "host"
         },
         "ci": {
-          "summary": "set declared GitHub CI secrets and variables and verify their custody",
+          "summary": "set declared GitHub CI secrets and variables, verify their custody, or run the managed CI locally",
           "owner": "@starci/hfs",
           "positional": [
             {
@@ -185,7 +185,8 @@ export const CATALOG = {
               "enum": [
                 "secret",
                 "var",
-                "verify"
+                "verify",
+                "local"
               ],
               "required": true,
               "variadic": false
@@ -234,12 +235,27 @@ export const CATALOG = {
             {
               "name": "json",
               "type": "boolean",
-              "summary": "print verification findings as JSON"
+              "summary": "print verification findings (or the local plan and results) as JSON"
+            },
+            {
+              "name": "jobs",
+              "type": "string",
+              "summary": "local: the jobs to run, comma separated (default fast,lint,test,coverage,build; sonar and db-types only when named)"
+            },
+            {
+              "name": "parallel",
+              "type": "string",
+              "summary": "local: job instances run at once (default half the CPUs, at most 4)"
+            },
+            {
+              "name": "dry-run",
+              "type": "boolean",
+              "summary": "local: print which steps would run and which only GitHub can run"
             }
           ],
           "exit": {
-            "0": "action completed or verification clean",
-            "1": "verification findings",
+            "0": "action completed, verification clean or every local job green",
+            "1": "verification findings or a local job red",
             "2": "refusal or bad usage"
           },
           "json": "flag",
@@ -250,13 +266,66 @@ export const CATALOG = {
             "starci app ci var set SONAR_HOST_URL",
             "starci app ci var sync",
             "starci app ci var sync --execute",
-            "starci app ci verify --json"
+            "starci app ci verify --json",
+            "starci app ci local --dry-run",
+            "starci app ci local --jobs lint,test --parallel 4"
+          ],
+          "editions": [
+            "full",
+            "lite"
+          ],
+          "impl": null,
+          "conventions": [
+            "local reads .github/workflows/ci.yml and runs every job instance (matrix values substituted) on this machine, in parallel, a job after its needs",
+            "it skips what only GitHub runs (uses: actions, npm ci, the lint baseline, a step whose if: needs a Sonar token, a tag ref or step outputs) and lists it",
+            "the unit shards write be/coverage/shards/shard-<i>, which the coverage job merges; each instance logs to a temp directory"
+          ],
+          "runtimeSide": "host"
+        },
+        "coverage": {
+          "summary": "merge the lcov reports of the sharded unit run into one report",
+          "owner": "@starci/hfs",
+          "positional": [
+            {
+              "name": "action",
+              "enum": [
+                "merge"
+              ],
+              "required": true,
+              "variadic": false
+            }
+          ],
+          "flags": [
+            {
+              "name": "out",
+              "type": "string",
+              "summary": "the merged lcov to write (the managed CI writes be/coverage/lcov.info)"
+            },
+            {
+              "name": "cwd",
+              "type": "string",
+              "summary": "the app root (default the current directory)"
+            }
+          ],
+          "exit": {
+            "0": "merged",
+            "2": "bad usage or no report found"
+          },
+          "json": "none",
+          "examples": [
+            "starci app coverage merge --out be/coverage/lcov.info be/coverage/shards"
           ],
           "editions": [
             "full",
             "lite"
           ],
           "impl": null,
+          "conventions": [
+            "the CI standard shards the unit run (npm test -- --shard=i/N); each shard writes an lcov over the whole coverage scope",
+            "merge sums every line, function and branch hit by identity across the reports and writes one record per source file",
+            "a path is an lcov file or a directory searched for every lcov.info below it; no report found refuses (exit 2), never an empty report",
+            "the coverage proof (starci app check --coverage-from), the Codecov upload and the Sonar import read the merged report"
+          ],
           "runtimeSide": "host"
         },
         "db": {
@@ -618,8 +687,8 @@ export const CATALOG = {
           ],
           "exit": {
             "0": "gate green or push done or nothing to do",
-            "1": "a gate is red or the push was refused by the hook",
-            "2": "refusal or bad usage including RELEASE_CI_RED and RELEASE_SONAR_UNAVAILABLE"
+            "1": "a gate is red, the candidate CI of the sha is not green, or the push was refused by the hook",
+            "2": "refusal or bad usage including RELEASE_SONAR_UNAVAILABLE"
           },
           "json": "flag",
           "examples": [
@@ -641,10 +710,11 @@ 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",
-            "gate checks the newest completed ci.yml run on the default branch, including reachable push/tag runs;",
-            "failure, cancelled or timed_out refuses RELEASE_CI_RED with its URL and SHA;",
-            "unreadable GitHub or no run warns RELEASE_CI_UNKNOWN and continues",
-            "only the owner's starci release ci-override --sha <sha> --reason <text> record can override red CI; there is no --no-ci-check flag",
+            "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",
+            "no run, or no end in time, refuses RELEASE_CANDIDATE_CI_TIMEOUT; unreadable GitHub refuses RELEASE_CI_UNKNOWN; nothing reaches the branch",
+            "only the owner's starci release ci-override --sha <sha> --reason <text> record lets a red candidate through; there is no --no-ci-check flag",
             "gate refuses a dirty tree, HEAD other than --source, a moved HEAD and a tree dirtied by the gates; record and tag only when all gates are green",
             "a gate with summary jest is red on failed tests and on a coverage threshold miss even when the process exits 0",
             "push needs the annotated tag and L4 record of HEAD, runs git push --dry-run --atomic first and never uses --no-verify"
@@ -7723,6 +7793,11 @@ export const CATALOG = {
               "name": "keep",
               "type": "boolean",
               "summary": "keep and print the temporary application path"
+            },
+            {
+              "name": "source",
+              "type": "boolean",
+              "summary": "scaffold with this checkout and install the @starci scope from its packed tarballs (the pre-publish form release scaffold-e2e runs)"
             }
           ],
           "exit": {
@@ -7733,7 +7808,8 @@ export const CATALOG = {
           "json": "none",
           "examples": [
             "starci release app-installs",
-            "starci release app-installs --keep"
+            "starci release app-installs --keep",
+            "starci release app-installs --source"
           ],
           "editions": [
             "full"
@@ -7778,7 +7854,7 @@ export const CATALOG = {
           "runtimeSide": "tree"
         },
         "ci-override": {
-          "summary": "the owner accepts red CI for one SHA and records who and why",
+          "summary": "the owner accepts a red candidate CI for one SHA (emergency path) and records who and why",
           "owner": "runtime",
           "flags": [
             {
@@ -7813,14 +7889,17 @@ export const CATALOG = {
             "script": "scripts/supervisor/release-ci-override-cli.mjs"
           },
           "conventions": [
-            "OWNER RULING 2026-10-17 (chat to main, relayed): alpha.20 \"cut refuses when the latest CI on main is red, with a documented owner override verb\";",
-            "the override is owner-only, records who and why in the owner rulings, and agents cannot run it.",
+            "OWNER RULING candidate-ci (2026-10-18): a release reaches main only when the candidate CI of its own sha is green;",
+            "this verb is the one documented EMERGENCY path for a red candidate.",
+            "The override is owner-only, records who and why, and agents cannot run it (OWNER RULING alpha20-ci-override-owner-only).",
             "Every bound role is refused by the command guard and by this script. The owner must use a terminal and type the first 12 SHA characters exactly.",
             "Writes <git-common-dir>/starci-release/<sha>.ci-override.json, schema starci/ci-override@1,",
             "with sha, reason, by (git user.name and OS user), at, and runUrl (empty if GitHub is unavailable).",
-            "For the runtime, appends ci-override-<sha12> under rulings before the top-level supersedes key in modules/kernel/owner-rulings.yaml.",
-            "Commit that entry into the tree being cut. App repositories receive only the record.",
-            "An override applies only to its exact SHA. It does not permit a cut when CI is unknown. Existing ruling IDs with another reason refuse."
+            "release cut and app release push read that record for the exact candidate sha only; the release record logs its use.",
+            "For the runtime it also appends ci-override-<sha12> under rulings in modules/kernel/owner-rulings.yaml as the audit trail.",
+            "App repositories receive only the record.",
+            "An override applies only to its exact SHA. It never permits a release whose CI is unknown or timed out.",
+            "Existing ruling IDs with another reason refuse."
           ],
           "runtimeSide": "tree"
         },
@@ -7942,8 +8021,8 @@ export const CATALOG = {
             }
           ],
           "exit": {
-            "0": "the release was cut and main plus its tag were pushed atomically, or --plan found nothing missing",
-            "1": "refused (RELEASE_CI_RED, RELEASE_CI_UNKNOWN, dirty tree, no or wrong tag, release notes incomplete, version not moved past the remote main, suite red, main moved, secret scan) and nothing was pushed",
+            "0": "the candidate CI of the release sha was green, then main plus its tag were pushed atomically, or --plan found nothing missing",
+            "1": "refused (RELEASE_CANDIDATE_CI_RED, RELEASE_CANDIDATE_CI_TIMEOUT, RELEASE_CI_UNKNOWN, dirty tree, no or wrong tag, release notes incomplete, version not moved past the remote main, suite red, main moved, secret scan) and nothing was pushed",
             "2": "bad usage"
           },
           "json": "flag",
@@ -7960,14 +8039,18 @@ export const CATALOG = {
             "script": "scripts/supervisor/release-cut-cli.mjs"
           },
           "conventions": [
-            "OWNER RULING 2026-10-17 (chat to main, relayed): alpha.20 \"cut refuses when the latest CI on main is red, with a documented owner override verb\";",
-            "the override is owner-only, records who and why in the owner rulings, and agents cannot run it.",
-            "Before the suite, including --plan, read the newest completed CI workflow run on main.",
-            "Only success continues; every other conclusion refuses RELEASE_CI_RED and names the run URL and headSha.",
-            "Unreadable GitHub or no completed run refuses RELEASE_CI_UNKNOWN: a cut must not proceed blind, including under suite ci.",
-            "The owner may run starci release ci-override --sha <headSha> --reason <text>.",
-            "A red run requires both starci-release/<headSha>.ci-override.json in the git common dir and ci-override-<sha12>",
-            "in modules/kernel/owner-rulings.yaml of the tree being cut. Commit the ruling before cutting."
+            "OWNER RULING candidate-ci (2026-10-18): never again have main receive a release whose CI is red, with the owner confirming afterwards.",
+            "Before the suite, including --plan, the workflows the candidate CI waits for (release-cut.yaml candidate.workflows) must be readable,",
+            "else RELEASE_CI_UNKNOWN. The latest run on main is no longer read: a red main needs no owner override before the next release.",
+            "After the suite and the secret scan the exact HEAD is pushed to refs/heads/release/candidate-<version>;",
+            "a re-cut of the same version force-moves only that ref, never main.",
+            "The cut waits for every required workflow run of that sha (pollSeconds, graceMinutes, waitMinutes in release-cut.yaml).",
+            "Red refuses RELEASE_CANDIDATE_CI_RED with the run URLs and the failing jobs and steps; nothing reaches main.",
+            "No run within the grace, or no end within the wait, refuses RELEASE_CANDIDATE_CI_TIMEOUT.",
+            "A red candidate keeps its ref for diagnosis; after a cut the candidate ref is left on the remote, naming the released sha.",
+            "Only on green is the annotated tag created and main plus the tag pushed atomically; the release record logs the candidate verdict.",
+            "Emergency path, owner-only: starci release ci-override --sha <HEAD> --reason <text> lets a red candidate through.",
+            "The release record logs its use."
           ],
           "runtimeSide": "tree"
         },

package/runtime/scripts/hfs/lcov-merge.mjs

@@ -0,0 +1,89 @@
+// lcov-merge.mjs - the lcov reports of the sharded unit run merged into one (`starci app coverage merge`, the coverage job of the managed CI). Each shard of
+// `npm test -- --shard=i/N` writes its own lcov over the whole collectCoverageFrom scope (a file no test of that shard loads is a record of zeros), so the
+// merge sums every line, function and branch hit by its identity across the shards and writes ONE record per source file, with the summaries recomputed:
+// the coverage proof (`starci app check --coverage-from`), the Codecov upload and the Sonar import then read the one be/coverage/lcov.info they always read.
+// Pure over the texts; the file walk is lcovFilesUnder.
+import fs from 'node:fs';
+import path from 'node:path';
+import { byCodeUnit } from '../lib/list.mjs';
+import { addHits as add } from './rules/coverage-below.mjs';
+
+const count = (value) => (/^\d+$/.test(value) ? Number(value) : 0);
+
+function recordOf(records, source) {
+  if (!records.has(source)) records.set(source, { lines: new Map(), fnLines: new Map(), fnHits: new Map(), branches: new Map() });
+  return records.get(source);
+}
+
+/** Function data: FN:<line>[,<end>],<name> declares, FNDA:<hits>,<name> counts (a name may hold commas). */
+function functionLine(record, tag, value) {
+  const at = value.indexOf(',');
+  if (at < 0) return;
+  if (tag === 'FN') {
+    let name = value.slice(at + 1);
+    let line = value.slice(0, at);
+    if (/^\d+,/.test(name)) { line = `${line},${name.slice(0, name.indexOf(','))}`; name = name.slice(name.indexOf(',') + 1); }
+    if (!record.fnLines.has(name)) record.fnLines.set(name, line);
+    if (!record.fnHits.has(name)) record.fnHits.set(name, 0);
+  } else add(record.fnHits, value.slice(at + 1), count(value.slice(0, at)));
+}
+
+function dataLine(record, tag, value) {
+  if (tag === 'DA') {
+    const [line, hits] = value.split(',');
+    add(record.lines, Number(line), count(hits ?? ''));
+  } else if (tag === 'FN' || tag === 'FNDA') functionLine(record, tag, value);
+  else if (tag === 'BRDA') {
+    const parts = value.split(',');
+    if (parts.length === 4) add(record.branches, parts.slice(0, 3).join(','), parts[3] === '-' ? 0 : count(parts[3]));
+  }
+}
+
+/** Every record of every text, merged by source file (SF) and identity. */
+function parseAll(texts) {
+  const records = new Map();
+  for (const text of texts) {
+    let current = null;
+    for (const raw of String(text).replace(/^/, '').split(/\r?\n/)) {
+      const line = raw.trim();
+      if (line === 'end_of_record') { current = null; continue; }
+      const colon = line.indexOf(':');
+      if (colon < 0) continue;
+      const tag = line.slice(0, colon);
+      const value = line.slice(colon + 1);
+      if (tag === 'SF') current = recordOf(records, value);
+      else if (current) dataLine(current, tag, value);
+    }
+  }
+  return records;
+}
+
+const branchOrder = (a, b) => a.split(',').map(Number).reduce((order, part, index) => order || part - Number(b.split(',')[index]), 0);
+
+function serialize(source, record) {
+  const out = ['TN:', `SF:${source}`];
+  const functions = [...record.fnLines.keys()].sort((a, b) => Number(record.fnLines.get(a).split(',')[0]) - Number(record.fnLines.get(b).split(',')[0]) || byCodeUnit(a, b));
+  for (const name of functions) out.push(`FN:${record.fnLines.get(name)},${name}`);
+  for (const name of functions) out.push(`FNDA:${record.fnHits.get(name) ?? 0},${name}`);
+  out.push(`FNF:${functions.length}`, `FNH:${functions.filter((name) => (record.fnHits.get(name) ?? 0) > 0).length}`);
+  const lines = [...record.lines.keys()].sort((a, b) => a - b);
+  for (const line of lines) out.push(`DA:${line},${record.lines.get(line)}`);
+  out.push(`LF:${lines.length}`, `LH:${lines.filter((line) => record.lines.get(line) > 0).length}`);
+  const branches = [...record.branches.keys()].sort(branchOrder);
+  for (const branch of branches) out.push(`BRDA:${branch},${record.branches.get(branch)}`);
+  out.push(`BRF:${branches.length}`, `BRH:${branches.filter((branch) => record.branches.get(branch) > 0).length}`, 'end_of_record');
+  return out.join('\n');
+}
+
+/** One lcov text of the merged `texts`: a record per source file, sorted by path, hits summed by line, function name and branch identity. */
+export function mergeLcov(texts) {
+  const records = parseAll(texts);
+  return [...records.keys()].sort(byCodeUnit).map((source) => serialize(source, records.get(source))).join('\n') + (records.size ? '\n' : '');
+}
+
+/** The lcov files a path names: the file itself, or every `lcov.info` below a directory (sorted). */
+export function lcovFilesUnder(target) {
+  if (!fs.statSync(target).isDirectory()) return [target];
+  return fs.readdirSync(target, { recursive: true, withFileTypes: true }).filter((entry) => entry.isFile() && entry.name === 'lcov.info')
+    .map((entry) => path.join(entry.parentPath ?? entry.path, entry.name)).sort(byCodeUnit);
+}

package/runtime/scripts/hfs/rules/a15-findings.mjs

@@ -34,6 +34,7 @@ import { stackToolingFindings } from './stack-tooling.mjs';
 import { stacksDeployFindings } from './stacks-deploy.mjs';
 import { ciCustodyFindings } from './ci-custody.mjs';
 import { workflowContextsFindings } from './workflow-contexts.mjs';
+import { ciStandardAppFindings } from './ci-standard.mjs';
 import { feBuildArgsFindings } from './fe-build-args.mjs';
 // finders-import-end
 
@@ -42,6 +43,7 @@ export const A15_CODES = [
   // codes-begin
   'FE_PUBLIC_BUILD_ARG_MISSING',
   'HFS_WORKFLOW_CONTEXT',
+  'CI_STANDARD',
   'CI_SECRET_SEALED', 'APP_SECRET_IN_CI', 'CI_DECLARATION_DRIFT',
   'BACKUP_PROOF_MISSING', 'BACKUP_UNDECLARED', 'BE_APP_BOOT_PROOF_MISSING', 'BE_APP_ENV_REQUIRED', 'BE_APP_MODULE_LIST_INLINE', 'BE_LITE_PROOF_LANE_MISSING', 'DB_API_EXPOSED', 'DB_ARCHIVE_MUTATED', 'DB_BASELINE_SHAPE', 'DB_CRON_OWNED', 'DB_EXTENSION_ALLOWED', 'DB_MIGRATION_DESTRUCTIVE', 'DB_PGMQ_DECLARED', 'DB_VAULT_WRITE', 'ENV_DUPLICATE', 'ENV_EXAMPLE_DRIFT', 'ENV_PUBLIC_SEALED', 'ENV_REQUIRED_UNSET', 'ENV_SEALED_UNREAD', 'ENV_VALUE_SHAPE', 'FE_STACK_CORE_MISSING', 'FE_STACK_UNLISTED', 'HFS_AGE_KEY_CUSTODY', 'HFS_APP_LEXICON', 'HFS_APP_WORKFLOW_TRIGGER', 'HFS_ASSET_KIND', 'HFS_ASSET_OVERSIZE', 'HFS_AUDIT_STEP_MISSING', 'HFS_CANON_COPY_DRIFT', 'HFS_CI_TOOL_INSTALL', 'HFS_COVERAGE_BELOW', 'HFS_DB_DEPLOY_UNGUARDED', 'HFS_DEPENDABOT_MISSING', 'HFS_DEPLOY_COMPOSE_ON_VPS', 'HFS_DEPLOY_NO_LOGIC', 'HFS_DEPLOY_SCHEDULER', 'HFS_DEPLOY_WORKFLOW', 'HFS_DOC_COMMAND_UNKNOWN', 'HFS_DOC_ENV_UNKNOWN', 'HFS_DOC_PATH_MISSING', 'HFS_DOC_RULE_UNKNOWN', 'HFS_FEATURE_FILE_BUDGET', 'HFS_HOST_CRON', 'HFS_RELEASE_TAG_MISMATCH', 'HFS_SBOM_MISSING', 'HFS_SCHEDULE_UNDECLARED', 'HFS_SCRIPT_PLAINTEXT_LOAD', 'HFS_SCRIPT_XTRACE', 'HFS_SECRET_OUTSIDE_ENC', 'HFS_SECRET_PLAINTEXT_FILE', 'HFS_SEED_PII', 'HFS_SERVICE_ROLE_SCOPE', 'HFS_UNUSED_SYMBOL', 'HFS_WORKFLOW_PIN', 'STACKS_DEPLOY_CONFIG_INVALID', 'STACKS_DNS_UNDECLARED', 'STACKS_HEALTHCHECK_MISSING', 'STACKS_HOST_UNROUTED', 'STACKS_INGRESS_UNDECLARED', 'STACKS_INGRESS_UNKNOWN', 'STACKS_LITE_SELFHOSTED_DB', 'STACKS_MODEL_UNAVAILABLE', 'STACKS_PLACEMENT_MISSING', 'STACKS_PORT_PUBLISHED', 'STACKS_REALTIME_SCALED', 'STACKS_RELEASE_UNDECLARED', 'STACKS_SECOND_INGRESS', 'STACKS_SECRET_ENV_LITERAL', 'STACKS_SECRET_NOT_EXTERNAL', 'STACKS_SECRET_UNVERSIONED', 'STACKS_SIDECAR_DB_UNSUPPORTED', 'STACKS_SIDECAR_VOLUME_UNDECLARED', 'STACKS_TLS_UNDECLARED', 'STACKS_UPDATE_POLICY_MISSING', 'STACK_TOOLING_REIMPLEMENTED',
   // codes-end
@@ -51,6 +53,7 @@ const FINDERS = [
   // finders-begin
   feBuildArgsFindings,
   workflowContextsFindings,
+  ciStandardAppFindings,
   featureFileFindings,
   lexiconFindings,
   assetsFindings,

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

@@ -0,0 +1,202 @@
+// ci-standard.mjs - R301 CI_STANDARD: the one StarCi CI standard (knowledge/hfs/ci-standard.yaml, OWNER RULING ci-standard 2026-10-18: ".claude defines ONE standard CI
+// ruleset, its own CI and the examples follow it, and apps inherit it"). This file checks the items the standard marks `check: ci-standard`:
+//   job-shape              the managed ci.yml holds exactly the edition's jobs; the unit run is in `test`, the proof and the Codecov upload in `coverage` (the one OIDC job)
+//   full-history-base-ref  every actions/checkout fetches the full history; a job that lints writes STARCI_BASE_REF before it lints
+//   heap-per-step          every heavy step (heap.steps) declares NODE_OPTIONS --max-old-space-size >= heap.minMiB on the step
+//   sonar-lint-per-side    a lint with --sonar names --side
+//   optional-providers     an optional (continue-on-error) Codecov or Sonar step follows its availability probe in the same job
+//   test-sharding          the test job is a shard matrix; each shard runs --shard=i/N without the per-file threshold; the coverage job merges, then proves
+//   lint-parallel          the lint job is a matrix over side [be, fe]
+//   cache-saved-always     no cache keyed by the commit sha; actions/cache/save runs under if: always()
+//   timeouts               every job declares timeout-minutes
+//   sha-pinned-actions     every remote `uses:` names a 40-hex commit sha (docker:// a sha256 digest; ./ local actions allowed)
+// `ciStandardFindings({doc, file, scope})` is the pure core: scope `app-ci` (an app's managed .github/workflows/ci.yml: the example apps and every app through the
+// app check) or `runtime` (the runtime repository's own workflows, scripts/hfs/runtime-rules/runtime-ci-standard.mjs), each checking the items whose `covers` names it.
+import fs from 'node:fs';
+import { parseYaml } from '../../../engine/yaml.mjs';
+import { parseWorkflow } from '../runtime-rules/workflow-source.mjs';
+import { found } from './read.mjs';
+import { appWorkflowFindings } from './app-workflow-findings.mjs';
+import { isPlainObject as record } from '../../../engine/plain-object.mjs';
+import { byCodeUnit } from '../../lib/list.mjs';
+
+export const CI_STANDARD = 'CI_STANDARD';
+const STANDARD_FILE = new URL('../../../knowledge/hfs/ci-standard.yaml', import.meta.url);
+const APP_CI = '.github/workflows/ci.yml';
+const SHA_PIN = /@[0-9a-f]{40}$/;
+const DIGEST_PIN = /@sha256:[0-9a-f]{64}$/;
+
+let cached = null;
+/** The standard (knowledge/hfs/ci-standard.yaml), read once. */
+function ciStandard() {
+  if (!cached) {
+    const doc = parseYaml(fs.readFileSync(STANDARD_FILE, 'utf8'));
+    if (doc?.schema !== 'starci/ci-standard@1' || !Array.isArray(doc.items)) throw new Error('knowledge/hfs/ci-standard.yaml is not a starci/ci-standard@1 standard');
+    cached = doc;
+  }
+  return cached;
+}
+
+const jobsOf = (doc) => (record(doc?.jobs) ? Object.entries(doc.jobs).filter(([, job]) => record(job)) : []);
+const stepsOf = (job) => (Array.isArray(job.steps) ? job.steps.filter(record) : []);
+const usesOf = (step) => String(step.uses ?? '').trim();
+const runOf = (step) => (typeof step.run === 'string' ? step.run : '');
+
+/** The items of the standard this file checks for `scope`: their ids. */
+const checkedItems = (standard, scope) => new Set(standard.items.filter((item) => item.check === 'ci-standard' && item.covers.includes(scope)).map((item) => item.id));
+
+function jobShape(doc, edition, standard, say) {
+  const shape = standard.jobs[edition] ?? standard.jobs.full;
+  const ids = jobsOf(doc).map(([id]) => id);
+  const out = [];
+  const missing = shape.required.filter((id) => !ids.includes(id));
+  const extra = ids.filter((id) => !shape.required.includes(id) && !shape.optional.includes(id));
+  const gaps = [missing.length ? 'missing ' + missing.join(', ') : '', extra.length ? 'not in the standard ' + extra.join(', ') : ''].filter(Boolean).join('; ');
+  if (gaps) out.push(say('job-shape', `the jobs must be ${shape.required.join(', ')} (optional ${shape.optional.join(', ')}); ${gaps}`));
+  const withStep = (match) => jobsOf(doc).filter(([, job]) => stepsOf(job).some((step) => match(step))).map(([id]) => id);
+  const unit = withStep((step) => step.name === 'unit');
+  const upload = withStep((step) => usesOf(step).startsWith('codecov/codecov-action@'));
+  const proof = withStep((step) => /app check --coverage-from/.test(runOf(step)));
+  if (unit.join() !== 'test') out.push(say('job-shape', `the unit run must be a step of the test job alone, not of ${unit.join(', ') || 'no job'}`));
+  if (proof.join() !== 'coverage') out.push(say('job-shape', `the coverage proof must be a step of the coverage job alone, not of ${proof.join(', ') || 'no job'}`));
+  if (upload.length && upload.join() !== 'coverage') out.push(say('job-shape', `the Codecov upload must be a step of the coverage job alone, not of ${upload.join(', ')}`));
+  const oidc = jobsOf(doc).filter(([, job]) => job.permissions?.['id-token'] === 'write').map(([id]) => id);
+  if (upload.length && oidc.join() !== 'coverage') out.push(say('job-shape', `only the coverage job holds the OIDC id-token (id-token: write), not ${oidc.join(', ') || 'no job'}`));
+  return out;
+}
+
+function testSharding(doc, say) {
+  const test = record(doc.jobs?.test) ? doc.jobs.test : null;
+  if (!test) return [];
+  const out = [];
+  const shards = test.strategy?.matrix?.shard;
+  if (!Array.isArray(shards) || !shards.length) out.push(say('test-sharding', 'the test job must be a matrix over shard (ci.jobs.test.shards)'));
+  const unit = stepsOf(test).find((step) => step.name === 'unit');
+  const total = /--shard=\$\{\{\s*matrix\.shard\s*\}\}\/(\d+)/.exec(unit ? runOf(unit) : '');
+  if (unit && !total) out.push(say('test-sharding', 'the unit run must pass --shard=${{ matrix.shard }}/<N>'));
+  if (total && Array.isArray(shards) && Number(total[1]) !== shards.length) out.push(say('test-sharding', `the unit run's shard total ${total[1]} must equal the ${shards.length} matrix shards`));
+  if (unit && !runOf(unit).includes('--coverageThreshold={}')) out.push(say('test-sharding', 'a shard measures without the per-file threshold (--coverageThreshold={}); the coverage job proves it on the merged report'));
+  const coverage = record(doc.jobs?.coverage) ? stepsOf(doc.jobs.coverage) : [];
+  const merge = coverage.findIndex((step) => /app coverage merge\b/.test(runOf(step)));
+  const proof = coverage.findIndex((step) => /app check --coverage-from/.test(runOf(step)));
+  if (merge < 0 || (proof >= 0 && merge > proof)) out.push(say('test-sharding', 'the coverage job must merge the shard reports (starci app coverage merge) before the coverage proof'));
+  return out;
+}
+
+function lintParallel(doc, say) {
+  const sides = record(doc.jobs?.lint) ? doc.jobs.lint.strategy?.matrix?.side : null;
+  return Array.isArray(sides) && sides.map(String).sort(byCodeUnit).join() === 'be,fe' ? [] : [say('lint-parallel', 'the lint job must be a matrix over side [be, fe]')];
+}
+
+function cacheSavedAlways(doc, say) {
+  const out = [];
+  for (const [id, job] of jobsOf(doc)) {
+    for (const step of stepsOf(job)) {
+      const uses = usesOf(step);
+      if (/^actions\/cache(?:\/restore)?@/.test(uses) && String(step.with?.key ?? '').includes('github.sha')) out.push(say('cache-saved-always', `job ${id}: a cache keyed by the commit sha never warms; key it by the lockfile hash (and the run) with restore-keys`));
+      if (uses.startsWith('actions/cache/save@') && !/^(?:\$\{\{\s*)?always\(\)/.test(String(step.if ?? '').trim())) out.push(say('cache-saved-always', `job ${id}: actions/cache/save runs under if: always(), so a red run still warms the cache`));
+    }
+  }
+  return out;
+}
+
+function fullHistory(doc, say) {
+  const out = [];
+  for (const [id, job] of jobsOf(doc)) {
+    for (const step of stepsOf(job)) {
+      if (usesOf(step).startsWith('actions/checkout@') && String(step.with?.['fetch-depth']) !== '0') out.push(say('full-history-base-ref', `job ${id}: actions/checkout must fetch the full history (fetch-depth: 0)`));
+    }
+  }
+  for (const [id, job] of jobsOf(doc)) {
+    const steps = stepsOf(job);
+    const base = steps.findIndex((step) => /STARCI_BASE_REF=.*>>\s*"?\$GITHUB_ENV"?/.test(runOf(step)));
+    const lint = steps.findIndex((step) => /\bnpm run lint\b|\bstarci app lint\b/.test(runOf(step)));
+    if (lint >= 0 && (base < 0 || base > lint)) out.push(say('full-history-base-ref', `job ${id} must write STARCI_BASE_REF to GITHUB_ENV before its first lint step`));
+  }
+  return out;
+}
+
+function heapPerStep(doc, standard, say) {
+  const out = [];
+  for (const [id, job] of jobsOf(doc)) {
+    for (const step of stepsOf(job)) {
+      const run = runOf(step);
+      if (!standard.heap.steps.some((needle) => run.includes(needle))) continue;
+      const heap = /--max-old-space-size=(\d+)/.exec(String(step.env?.NODE_OPTIONS ?? ''));
+      if (!heap || Number(heap[1]) < standard.heap.minMiB) out.push(say('heap-per-step', `job ${id}, step ${step.name ?? run.split('\n')[0].slice(0, 60)}: a heavy step declares NODE_OPTIONS --max-old-space-size=${standard.heap.minMiB} (or more) on the step`));
+    }
+  }
+  return out;
+}
+
+function sonarLintPerSide(doc, say) {
+  const out = [];
+  for (const [id, job] of jobsOf(doc)) {
+    for (const step of stepsOf(job)) {
+      const run = runOf(step);
+      if (/\b(?:npm run lint|starci(?:\.mjs)?["']?\s+app lint|app lint)\b/.test(run) && /\s--sonar\b/.test(run) && !/\s--side\s+(?:be\b|fe\b|\$\{\{\s*matrix\.side\s*\}\})/.test(run)) {
+        out.push(say('sonar-lint-per-side', `job ${id}, step ${step.name ?? 'lint'}: a lint with a Sonar import must name its side (--side be|fe) and the reports are merged afterwards; a combined lint with Sonar breaks the standard`));
+      }
+    }
+  }
+  return out;
+}
+
+function optionalProviders(doc, say) {
+  const out = [];
+  const probes = [['codecov/codecov-action@', 'codecov-availability'], ['SonarSource/sonarqube-scan-action@', 'sonar-availability']];
+  for (const [id, job] of jobsOf(doc)) {
+    const steps = stepsOf(job);
+    steps.forEach((step, index) => {
+      const probe = probes.find(([prefix]) => usesOf(step).startsWith(prefix));
+      if (!probe || step['continue-on-error'] !== true) return;
+      if (!steps.slice(0, index).some((earlier) => earlier.id === probe[1])) out.push(say('optional-providers', `job ${id}: the optional ${usesOf(step).split('@')[0]} step must follow its availability probe (id ${probe[1]})`));
+    });
+  }
+  return out;
+}
+
+function timeouts(doc, say) {
+  return jobsOf(doc).filter(([, job]) => !Number.isFinite(Number(job['timeout-minutes'])) || job['timeout-minutes'] === null || job['timeout-minutes'] === '')
+    .filter(([, job]) => job.uses === undefined).map(([id]) => say('timeouts', `job ${id} must declare timeout-minutes`));
+}
+
+function shaPinned(doc, say) {
+  const out = [];
+  for (const [id, job] of jobsOf(doc)) {
+    for (const uses of [job.uses, ...stepsOf(job).map((step) => step.uses)].filter((value) => typeof value === 'string')) {
+      const ref = uses.trim();
+      if (ref.startsWith('./')) continue;
+      const pinned = ref.startsWith('docker://') ? DIGEST_PIN.test(ref) : SHA_PIN.test(ref);
+      if (!pinned) out.push(say('sha-pinned-actions', `job ${id}: ${ref} must be pinned to a commit sha (a docker:// action to a sha256 digest)`));
+    }
+  }
+  return out;
+}
+
+/** The R301 findings of one workflow document: scope `app-ci` (with the app's edition) or `runtime`. Pure over the document and the standard. */
+export function ciStandardFindings({ doc, file, scope, edition = 'full', standard = ciStandard() }) {
+  if (!record(doc)) return [];
+  const items = checkedItems(standard, scope);
+  const say = (item, why) => found(CI_STANDARD, file, `${CI_STANDARD} ${file}: [${item}] ${why} (knowledge/hfs/ci-standard.yaml)`, { item });
+  const checks = {
+    'job-shape': () => jobShape(doc, edition, standard, say),
+    'full-history-base-ref': () => fullHistory(doc, say),
+    'heap-per-step': () => heapPerStep(doc, standard, say),
+    'sonar-lint-per-side': () => sonarLintPerSide(doc, say),
+    'optional-providers': () => optionalProviders(doc, say),
+    'test-sharding': () => testSharding(doc, say),
+    'lint-parallel': () => lintParallel(doc, say),
+    'cache-saved-always': () => cacheSavedAlways(doc, say),
+    timeouts: () => timeouts(doc, say),
+    'sha-pinned-actions': () => shaPinned(doc, say),
+  };
+  return Object.entries(checks).filter(([id]) => items.has(id)).flatMap(([, check]) => check());
+}
+
+/** R301 over an app: its managed .github/workflows/ci.yml (the app check, and the runtime check over every example app). */
+export function ciStandardAppFindings(ctx) {
+  const edition = ctx.repo?.edition === 'lite' ? 'lite' : 'full';
+  return appWorkflowFindings({ ...ctx, inScope: (file) => file === APP_CI && (ctx.inScope ?? (() => true))(file) },
+    ({ path: file, text }) => ciStandardFindings({ doc: parseWorkflow(text), file, scope: 'app-ci', edition }), { dedupe: true });
+}

package/runtime/scripts/hfs/rules/coverage-below.mjs

@@ -18,7 +18,7 @@ const countOf = (value) => /^\d+$/.test(value) && Number.isSafeInteger(Number(va
 const slash = (value) => path.posix.normalize(String(value).replaceAll('\\', '/'));
 
 const emptyRecord = (source) => ({ source, lines: new Map(), functions: new Map(), branches: new Map(), summary: {}, problems: [] });
-const addHits = (map, key, hits) => map.set(key, Math.min(Number.MAX_SAFE_INTEGER, (map.get(key) ?? 0) + hits));
+export const addHits = (map, key, hits) => map.set(key, Math.min(Number.MAX_SAFE_INTEGER, (map.get(key) ?? 0) + hits));
 const parseProblem = (record, line, tag) => record.problems.push(`invalid ${tag} at lcov line ${line}`);
 
 function lineData(record, value, line) {

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

@@ -68,18 +68,27 @@ function hasAgeIdentity(job, doc) {
   return steps.some((step) => strings(step.with).some((value) => reference.test(value)) || (typeof step.run === 'string' && reference.test(executable(step.run))));
 }
 
-function triggerFindings(doc, refuse) {
+/** 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')
+  && (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));
+
+function triggerFindings(doc, refuse, file = '') {
   const on = workflowEventOptions(doc.on);
   if (!record(on) || !Object.keys(on).length) return [refuse(TRIGGER, 'declare release tags [v*] and/or workflow_dispatch')];
   const findings = [];
+  if (/(^|\/)ci\.ya?ml$/.test(file) && !(record(on.push) && Array.isArray(on.push.branches) && on.push.branches.includes(CANDIDATE_BRANCHES))) {
+    findings.push(refuse(TRIGGER, `the release CI must run on push of branches ['${CANDIDATE_BRANCHES}']: starci app release push waits for that run (starci app sync renders it)`));
+  }
   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*] or workflow_dispatch`));
+      findings.push(refuse(TRIGGER, `trigger ${event} is forbidden; app CI starts only on release tags [v*], the release candidate branches or workflow_dispatch`));
       continue;
     }
-    if (!record(options) || !Array.isArray(options.tags) || options.tags.length !== 1 || options.tags[0] !== 'v*' || Object.keys(options).some((key) => key !== 'tags')) {
-      findings.push(refuse(TRIGGER, 'push must contain only tags: [v*]; branch and path filters are forbidden'));
+    if (!pushFilterValid(options)) {
+      findings.push(refuse(TRIGGER, `push may contain only tags: [v*] and branches: ['${CANDIDATE_BRANCHES}']; other branch and path filters are forbidden`));
     }
   }
   return findings;
@@ -197,7 +206,7 @@ function perWorkflow({ path: file, text }) {
   const refuse = (code, message) => found(code, file, `${code} ${file}: ${message}`);
   const doc = parseWorkflow(text);
   if (!record(doc)) return [refuse(TRIGGER, 'the workflow must be valid YAML with a release-only on block'), ...(deployName(file) ? [refuse(DEPLOY, 'the deploy workflow must be valid YAML')] : [])];
-  return [...triggerFindings(doc, refuse), ...deploymentFindings(doc, file, refuse), ...toolFindings(doc, refuse)];
+  return [...triggerFindings(doc, refuse, file), ...deploymentFindings(doc, file, refuse), ...toolFindings(doc, refuse)];
 }
 
 /** Synchronous R251 findings over the tracked workflows of a lite/full app. */

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

@@ -75,7 +75,7 @@ function expressions(value) {
 }
 
 /** Source markers travel inside parsed scalar expressions, preserving flow maps, quoted keys and repeated values without matching comments. */
-function workflowContextFindings({ path: file, text }) {
+export function workflowContextFindings({ path: file, text }) {
   const marked = text.replace(/\$\{\{/g, (match, offset) => `${match} __hfs_context_line_${text.slice(0, offset).split('\n').length}__ `);
   const findings = [];
   function inspect(value, keys) {