@starci/hfs 4.4.0 → 4.5.0

package/runtime/scripts/api/git/lib.mjs

@@ -20,7 +20,7 @@ import { withTempEnv } from '../../../engine/temp-root.mjs';
  * is a request for raw bytes, not an encoding: spawnSync encodes a string `input` with it and throws
  * ERR_UNKNOWN_ENCODING, so it reaches spawnSync as encoding:null (Buffer output either way).
  */
-export const gitSpawn = (file, args, options = {}) => {
+const gitSpawn = (file, args, options = {}) => {
   assertMutationFence({ kind: 'git-effect', args });
   const spawn = { encoding: 'utf8', windowsHide: true, ...options };
   if (spawn.encoding === 'buffer') spawn.encoding = null;
@@ -76,5 +76,5 @@ export const gitExecutable = (options = null) => {
   return found;
 };
 
-/** The output ceiling of the whole-diff and `cat-file --batch` calls `test affected` batches (a release diff is tens of megabytes). */
-export const BATCH_MAX_BUFFER = 1024 * 1024 * 1024;
+/** The output ceiling of the whole-diff and `cat-file --batch` calls batch (a release diff is tens of megabytes). */
+const BATCH_MAX_BUFFER = 1024 * 1024 * 1024;

package/runtime/scripts/api/sops/lib.mjs

@@ -105,7 +105,7 @@ const IDENTITY_TIMEOUT_MS = 20_000;
 const CONTROLLED_ENV = new Set(['SOPS_AGE_KEY', 'SOPS_AGE_KEY_FILE', 'SOPS_AGE_KEY_CMD', 'SOPS_AGE_SSH_PRIVATE_KEY_FILE', 'SOPS_AGE_SSH_PRIVATE_KEY_CMD', 'SOPS_AGE_RECIPIENT', 'SOPS_KEYSERVICE', 'SOPS_ENABLE_LOCAL_KEYSERVICE', 'SOPS_DECRYPTION_ORDER', 'SOPS_KMS_ARN', 'SOPS_GCP_KMS_IDS', 'SOPS_HUAWEICLOUD_KMS_IDS', 'SOPS_AZURE_KEYVAULT_URLS', 'SOPS_VAULT_URIS', 'SOPS_PGP_FP', 'SOPS_AGE_RECIPIENTS', 'HOME', 'USERPROFILE', 'APPDATA', 'XDG_CONFIG_HOME']);
 
 /** Construct only the child map; empty desktop roots make Go return directory errors, not fallback paths. */
-export function isolatedSopsEnv(env, inlineName = 'SOPS_AGE_KEY') {
+function isolatedSopsEnv(env, inlineName = 'SOPS_AGE_KEY') {
   const out = Object.fromEntries(Object.entries(env).filter(([name]) => !CONTROLLED_ENV.has(name.toUpperCase())));
   out.HOME = ''; out.USERPROFILE = ''; out.APPDATA = ''; out.XDG_CONFIG_HOME = '';
   if (inlineName !== null) out.SOPS_AGE_KEY = env[inlineName];

package/runtime/scripts/hfs/app-wiring.mjs

@@ -24,7 +24,7 @@ const COMPILATION_FAILURE = 'module or proof could not be compiled';
 const WORKER_FAILURE = 'proof worker failed or timed out';
 const SAFE_REASONS = new Set([...DI_FAILURES.values(), COMPILATION_FAILURE]);
 const modulePath = app => `apps/${app}/src/app.module.ts`;
-export const wiringFixturePath = app => `src/tests/fixtures/builders/${app}.builder.ts`;
+const wiringFixturePath = app => `src/tests/fixtures/builders/${app}.builder.ts`;
 
 const refusal = (file, reason) => ({ code: BOOT_PROOF_CODE, level: 'error', path: file,
   message: `${file}: lite boot proof failed (${reason}); compile the real AppModule with explicit fixture options and infrastructure doubles using starci app check --wiring`, reason });
@@ -177,7 +177,7 @@ export function appWiring({ repoRoot, repo = readJson(repoRoot, 'hfs.json'), fil
 }
 
 /** Optional standalone entry; coordinator connects the same seam to app check --wiring. */
-export function appWiringMain(argv, { cwd = invocationDir(), stdout = text => process.stdout.write(text), stderr = text => process.stderr.write(text) } = {}) {
+function appWiringMain(argv, { cwd = invocationDir(), stdout = text => process.stdout.write(text), stderr = text => process.stderr.write(text) } = {}) {
   let directory = cwd, json = false;
   for (let at = 0; at < argv.length; at += 1) {
     if (argv[at] === '--cwd' && argv[at + 1]) directory = path.resolve(cwd, argv[++at]);

package/runtime/scripts/hfs/architecture/config.mjs

@@ -346,4 +346,4 @@ export function loadArchitectureConfig(repositoryRoot, { hfs } = {}) {
   };
 }
 
-export { canonical, enclosingRepository, exactKeys, isInside, slash };
+export { canonical, exactKeys, isInside, slash };

package/runtime/scripts/hfs/architecture/index.mjs

@@ -162,7 +162,7 @@ const machineIds = () => [
  * backend composition and data machine and frontend repository machine. A spec about another rule judges its own
  * report without these (they have their own specs); every one of them is in ARCHITECTURE_RULE_IDS.
  */
-export const HFS_MACHINE_RULE_IDS = Object.freeze((() => {
+const HFS_MACHINE_RULE_IDS = Object.freeze((() => {
   const ordinary = new Set([...COMMON_RULE_IDS, ...BACKEND_RULE_IDS, ...FRONTEND_RULE_IDS, ...OWNER_RULE_IDS, ...GRAMMAR_RULE_IDS, ...REGISTRATION_RULE_IDS,
     ...SWR_DATA_RULE_IDS, SOURCE_LAYOUT_RULE_ID, SOURCE_NAME_RULE_ID, PUBLIC_CONTRACT_RULE_ID, READONLY_BOUNDARY_RULE_ID]);
   return [...new Set(machineIds().filter((id) => !ordinary.has(id)))].sort(byCodeUnit);

package/runtime/scripts/hfs/architecture/supabase.mjs

@@ -209,7 +209,7 @@ export function checkBackendSupabase(input) {
   };
 }
 
-export function checkJwtPolicy(input) {
+function checkJwtPolicy(input) {
   const kit = machineKit(input);
   const violations = [];
   let verifyCalls = 0;

package/runtime/scripts/hfs/architecture/tiers.mjs

@@ -67,7 +67,7 @@ function finishFrame(state, frame) {
   if (state.low.get(frame.node) === state.index.get(frame.node)) closeComponent(state, frame);
 }
 
-export function stronglyConnected(adjacency) {
+function stronglyConnected(adjacency) {
   const state = { counter: 0, index: new Map(), low: new Map(), onStack: new Set(), stack: [], result: [], work: [] };
   for (const start of adjacency.keys()) {
     if (state.index.has(start)) continue;

package/runtime/scripts/hfs/architecture.mjs

@@ -26,7 +26,7 @@ function parseArchitectureArgs(argv) {
   return {root, base};
 }
 
-export function architectureMain(argv, {check = checkArchitecture, write = (text) => process.stdout.write(text), fail = (text) => process.stderr.write(text)} = {}) {
+function architectureMain(argv, {check = checkArchitecture, write = (text) => process.stdout.write(text), fail = (text) => process.stderr.write(text)} = {}) {
   let parsed;
   try { parsed = parseArchitectureArgs(argv); } catch (error) { fail(`${error.message}\n`); return 2; }
   let report;

package/runtime/scripts/hfs/ci-declaration.mjs

@@ -0,0 +1,102 @@
+import path from 'node:path';
+import { list } from '../lib/list.mjs';
+import { parseYaml } from '../../engine/yaml.mjs';
+
+const nameOf = (item) => typeof item === 'string' ? item : item?.name;
+
+/** Each CI name belongs to one class and scope; declarations contain names and public configuration only. */
+export function readCiDeclaration(doc) {
+  const problems = [], seen = new Set();
+  const invalid = (at, message) => problems.push({ code: 'CI_DECLARATION_INVALID', at, message });
+  const normalize = (entries, at, dependabot = false, variable = false) => list(entries).map((item, index) => {
+    const where = `${at}[${index}]`, name = item?.name;
+    if (seen.has(name)) invalid(`${where}.name`, 'a name must appear once across all CI classes');
+    seen.add(name);
+    if (typeof name !== 'string' || !/^[A-Z][A-Z0-9_]*$/.test(name) || name.startsWith('GITHUB_')) invalid(`${where}.name`, 'use an uppercase CI name outside the reserved GITHUB_ namespace');
+    const scope = dependabot ? 'repository' : item?.scope;
+    if (!['repository', 'environment'].includes(scope)) invalid(`${where}.scope`, 'scope must be repository or environment');
+    if (scope === 'environment' && (typeof item?.environment !== 'string' || !/^[a-z][a-z0-9-]*$/.test(item.environment))) invalid(`${where}.environment`, 'environment scope requires an environment name');
+    if ((dependabot || scope !== 'environment') && item && Object.hasOwn(item, 'environment')) invalid(`${where}.environment`, 'only environment scope may name an environment');
+    return { name, scope, environment: item?.environment ?? null, purpose: item?.purpose ?? null,
+      optional: item?.optional === true, ...(variable ? { value: item?.value } : {}) };
+  });
+  const ci = doc?.ci;
+  const secrets = normalize(ci?.secrets, 'ci.secrets');
+  const vars = normalize(ci?.vars, 'ci.vars', false, true);
+  const dependabotSecrets = normalize(ci?.dependabot?.secrets, 'ci.dependabot.secrets', true);
+  return { secrets, vars, dependabotSecrets, problems };
+}
+
+/** Missing quality blocks preserve the existing rendered defaults; disabled services remain explicitly disabled. */
+export function qualityServices(doc, { example = false } = {}) {
+  const services = doc?.services ?? {}, sonar = services.sonar, codecov = services.codecov ?? {};
+  const dependabot = services.dependabot ?? {}, audit = services.audit ?? {};
+  return {
+    sonar: !sonar || sonar.mode === 'disabled' ? null : {
+      provider: sonar.provider, mode: sonar.mode, host: sonar.host?.public || sonar.host?.local || null,
+      organization: sonar.organization ?? null,
+      organizationVar: sonar.ci?.organizationVar ?? (sonar.provider === 'sonarcloud' && (example || list(sonar.runtimeSecrets).length > 0) && !list(sonar.credentials).length ? 'SONAR_ORGANIZATION' : null), projectKey: sonar.projects?.[0]?.key ?? null,
+      qualityGate: sonar.qualityGate ?? (example ? 'starci-quality-lite' : 'starci-quality'), wiring: sonar.ci?.wiring ?? 'required',
+      token: sonar.ci?.token || nameOf(sonar.ci?.secrets?.[0]) || 'SONAR_TOKEN', hostVar: sonar.ci?.hostVar || 'SONAR_HOST_URL',
+    },
+    codecov: { enabled: codecov.mode !== 'disabled', auth: codecov.auth ?? 'oidc', token: codecov.ci?.token ?? null,
+      flag: codecov.flag ?? null, target: codecov.target ?? 100, components: codecov.components ?? 'auto', required: codecov.required ?? true, wiring: codecov.ci?.wiring ?? 'required' },
+    dependabot: { ecosystems: [...(dependabot.ecosystems ?? ['npm', 'github-actions', 'docker'])],
+      schedule: { interval: 'weekly', ...dependabot.schedule }, groups: { minorPatch: 'grouped', major: 'per-package', ...dependabot.groups },
+      ignore: [...(dependabot.ignore ?? ['@starci/*'])], security: dependabot.security ?? 'immediate' },
+    audit: { level: audit.level ?? 'high', omitDev: audit.omitDev ?? true, in: [...(audit.in ?? ['release-gate', 'ci'])] },
+  };
+}
+
+/** Enumerate a missing directory as empty; all filesystem access uses the caller's injected synchronous seam. */
+function entries(dir, fs) {
+  try { return fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name)); }
+  catch (error) { if (error.code === 'ENOENT') return []; throw error; }
+}
+
+/** Read only encrypted envelope key names, never decrypting or returning any sealed value. */
+export function sealedKeyNames(root, { fs }) {
+  const out = [], base = path.join(root, '.starcistacks');
+  for (const env of entries(base, fs).filter((entry) => entry.isDirectory())) {
+    for (const member of entries(path.join(base, env.name, 'secrets'), fs).filter((entry) => entry.isFile() && entry.name.endsWith('.enc'))) {
+      const file = `.starcistacks/${env.name}/secrets/${member.name}`;
+      const source = fs.readFileSync(path.join(root, file), 'utf8');
+      const dotenv = [...source.matchAll(/^([A-Za-z_][A-Za-z0-9_]*)=ENC\[/gm)].map((match) => match[1]).filter((key) => !key.startsWith('sops_'));
+      let keys = dotenv;
+      if (!dotenv.length) {
+        const doc = parseYaml(source);
+        keys = doc && typeof doc === 'object' && !Array.isArray(doc) ? Object.keys(doc).filter((key) => key !== 'sops' && !key.startsWith('sops_')) : [];
+      }
+      for (const key of keys) out.push({ env: env.name, member: member.name.slice(0, -4), key, file });
+    }
+  }
+  return out;
+}
+
+/** Collect every static secrets and vars reference inside workflow expressions, excluding the automatic GitHub token. */
+export function workflowReferences(root, { fs }) {
+  const out = [], dir = path.join(root, '.github', 'workflows');
+  for (const entry of entries(dir, fs).filter((item) => item.isFile() && /\.ya?ml$/i.test(item.name))) {
+    const file = `.github/workflows/${entry.name}`, source = fs.readFileSync(path.join(root, file), 'utf8');
+    for (const expression of source.matchAll(/\$\{\{([^}]*)/g)) {
+      for (const match of expression[1].matchAll(/\b(secrets|vars)\.([A-Z][A-Z0-9_]*)/g)) {
+        if (match[2] !== 'GITHUB_TOKEN') out.push({ file, kind: match[1], name: match[2] });
+      }
+    }
+  }
+  return out;
+}
+
+/** Service CI bindings name the shared declaration classes, including the readable legacy lists. */
+export function ciNamesOfServices(doc) {
+  const out = [];
+  for (const [service, entry] of Object.entries(doc?.services ?? {})) {
+    const ci = entry?.ci ?? {};
+    if (ci.token) out.push({ service, name: ci.token, kind: 'secret' });
+    if (ci.hostVar) out.push({ service, name: ci.hostVar, kind: 'var' });
+    if (ci.organizationVar) out.push({ service, name: ci.organizationVar, kind: 'var' });
+    for (const item of list(ci.secrets)) out.push({ service, name: nameOf(item), kind: 'secret' });
+    for (const item of list(ci.vars)) out.push({ service, name: nameOf(item), kind: 'var' });
+  }
+  return out;
+}

package/runtime/scripts/hfs/coverage-from.mjs

@@ -55,7 +55,7 @@ export function formatCoverageReport(report) {
 }
 
 /** Standalone coordinator entry point: exit 0 proof passed, 2 proof or invocation refused. */
-export function coverageFromMain(argv, { cwd = invocationDir(), stdout = (text) => process.stdout.write(text), stderr = (text) => process.stderr.write(text), run = coverageFrom } = {}) {
+function coverageFromMain(argv, { cwd = invocationDir(), stdout = (text) => process.stdout.write(text), stderr = (text) => process.stderr.write(text), run = coverageFrom } = {}) {
   try {
     const opts = parse(argv);
     const report = run({ repoRoot: path.resolve(cwd, opts.cwd ?? '.'), coverageFrom: opts.coverageFrom });

package/runtime/scripts/hfs/coverage-scope.mjs

@@ -17,7 +17,7 @@ import { byCodeUnit } from '../lib/list.mjs';
 import { trimTrailingSlashes } from './trailing-slashes.mjs';
 
 /** The component that holds the shared infrastructure: the platform tier and every capability more than one service app composes. */
-export const PLATFORM_COMPONENT = 'platform';
+const PLATFORM_COMPONENT = 'platform';
 const SERVICE_APP_KINDS = new Set(['api', 'worker']);
 /** `text` with every `<placeholder>` (a `<`, at least one character, the next `>`) replaced by `*`; a `<` with no closing `>` stays. */
 export const star = (text) => {

package/runtime/scripts/hfs/example-secrets.mjs

@@ -135,7 +135,7 @@ function commandEnvironment() {
 }
 
 /** Run an installed app command in a sealed temporary copy, returning its exit code and preserving report artifacts. */
-export async function runMaterializedCommand(repoRoot, command, args = [], { run = runProgram } = {}) {
+async function runMaterializedCommand(repoRoot, command, args = [], { run = runProgram } = {}) {
   return withMaterializedExample(repoRoot, '.', (app) => {
     const launch = commandLaunch(command, args);
     const result = run(launch.file, launch.args, { cwd: app, env: commandEnvironment(), stdio: 'inherit', windowsHide: true });

package/runtime/scripts/hfs/manifest-shape.mjs

@@ -56,8 +56,6 @@ export const unitRolesOf = (manifest) => manifest.ruleParams.be.unitRoles;
 /** The roles that carry logic (ruleParams.be.logicRoles): measured at 100 per file inside a coverage-required slot. */
 export const logicRolesOf = (manifest) => manifest.ruleParams.be.logicRoles;
 
-/** The roles a feature-tier file is judged thin by (ruleParams.be.thinRoles, R203 BE_FEATURE_THIN). */
-export const thinRolesOf = (manifest) => manifest.ruleParams.be.thinRoles;
 
 /** Shape problems of ruleParams.be.unitRoles: unique roles of the suffix vocabulary, each spec `<role>.spec`. */
 export function unitRolesProblems(be) {
@@ -86,7 +84,7 @@ export const MANIFEST_KINDS = [APP_KIND, RUNTIME_KIND];
 export const manifestKind = (m) => (isPlainObject(m) && m.kind !== undefined ? m.kind : APP_KIND);
 const strList = (v) => stringList(v);
 
-const APP_SLOT_KEYS = ['id', 'profiles', 'path', 'presence', 'tracked', 'tier', 'tests', 'owner', 'appKind', 'minInstances', 'requiredWhen', 'requiredInstances', 'requires', 'pattern', 'trigger', 'allows', 'forbids', 'layers', 'kinds', 'roles', 'composedBy', 'budget', 'managedBy', 'liteManagedBy', 'rules', 'goesTo', 'why', 'since', 'perConnection', 'parent', 'editions', 'editionWhy', 'litePresence', 'lite', 'provider', 'coverage', 'entries', 'outcomeHome', 'templateNa', 'exemplifiedBy'];
+const APP_SLOT_KEYS = ['id', 'profiles', 'path', 'presence', 'tracked', 'tier', 'tests', 'owner', 'appKind', 'minInstances', 'requiredWhen', 'requiredInstances', 'requires', 'pattern', 'trigger', 'allows', 'forbids', 'layers', 'kinds', 'roles', 'composedBy', 'budget', 'managedBy', 'liteManagedBy', 'rules', 'goesTo', 'why', 'since', 'perConnection', 'parent', 'editions', 'editionWhy', 'litePresence', 'lite', 'provider', 'coverage', 'entries', 'outcomeHome', 'templateNa', 'exampleNa', 'exemplifiedBy'];
 /** The fields a slot's `lite` overlay may hold: the same keys it would carry in the slot body, resolved under edition lite. */
 const LITE_OVERLAY_KEYS = ['path', 'requires', 'allows', 'forbids', 'minInstances', 'requiredInstances', 'why'];
 /** A runtime slot has no app kind, side composition, layer or managed template; it may name the generator of a generated copy. */
@@ -220,6 +218,8 @@ function slotCoverageEvidenceProblems(slot, at) {
   const bad = [];
   if (slot.templateNa !== undefined && !(typeof slot.templateNa === 'string' && slot.templateNa.trim()))
     bad.push(`${at}: templateNa must be non-empty text`);
+  if (slot.exampleNa !== undefined && !(typeof slot.exampleNa === 'string' && slot.exampleNa.trim()))
+    bad.push(`${at}: exampleNa must be non-empty text`);
   if (slot.exemplifiedBy === undefined) return bad;
   const refs = slot.exemplifiedBy;
   const valid = Array.isArray(refs) && refs.length > 0 && refs.every(slotEvidenceRefValid)

package/runtime/scripts/hfs/param-names.mjs

@@ -1,6 +1,6 @@
 // param-names.mjs - the one shape of `ruleParams.be.paramNames` of knowledge/hfs/slots.yaml (R85 injected-param-name): a non-empty list of unique
 // entries `{type | typeSuffix, names, nameSuffix?}`. The loader of scripts/hfs/slots.mjs calls it; the schema (modules/schemas/hfs-slots.schema.yaml)
-// states the same shape and tests/hfs/hfs-slots.spec.mjs proves the two agree.
+// states the same shape.
 import { isPlainObject } from '../../engine/plain-object.mjs';
 
 const UPPER = /^[A-Z][A-Za-z0-9]*$/u;

package/runtime/scripts/hfs/rule-catalog.mjs

@@ -16,7 +16,7 @@ const RULE_KINDS = Object.freeze(['codemod', 'lint', 'check', 'design']);
 const FINDING_CODE = /^[A-Z][A-Z0-9]*(_[A-Z0-9]+)+$/;
 const ENFORCER_ID = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 const FILE_ENFORCERS = new Set(['machine', 'hfs', 'work-validate', 'sonar', 'runtime']);
-const RULE_KEYS = new Set(['id', 'code', 'law', 'scope', 'kinds', 'gates', 'failureCodes', 'editions', 'codeEditions', 'enforcers', 'cases', 'docs', 'exemplifiedBy', 'proves', 'witness', 'editionWhy', 'amendedBy', 'templateNa']);
+const RULE_KEYS = new Set(['id', 'code', 'law', 'scope', 'kinds', 'gates', 'failureCodes', 'editions', 'codeEditions', 'enforcers', 'cases', 'docs', 'exemplifiedBy', 'proves', 'witness', 'editionWhy', 'amendedBy', 'templateNa', 'specNa', 'exampleNa']);
 const CASE_KEYS = new Set(['id', 'date', 'source', 'ruling', 'quote', 'supersedes', 'status', 'staleWhen', 'amendedBy']);
 const CASE_DATE = /^\d{4}-\d{2}-\d{2}$/;
 const ENFORCER_KEYS = new Set(['kind', 'id', 'status', 'at', 'editions', 'editionWhy']);
@@ -279,6 +279,8 @@ function checkRule(rule, index, catalog, codeOwner, bad) {
   if (rule.amendedBy !== undefined) caseReferenceProblems(rule.amendedBy, `${label}.amendedBy`, bad);
   optionalText(rule, 'editionWhy', label, bad);
   optionalText(rule, 'templateNa', label, bad);
+  optionalText(rule, 'specNa', label, bad);
+  optionalText(rule, 'exampleNa', label, bad);
   for (const key of ['docs', 'exemplifiedBy', 'proves']) evidenceProblems(rule, key, label, bad);
   witnessProblems(rule, label, bad);
   enumListProblems(rule, label, 'kinds', RULE_KINDS, bad);

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

@@ -32,17 +32,25 @@ import { stacksIngressFindings } from './stacks-ingress.mjs';
 import { stacksLiteBackingFindings } from './stacks-lite-backing.mjs';
 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 { feBuildArgsFindings } from './fe-build-args.mjs';
 // finders-import-end
 
 /** The failure codes the finders above emit, so `starci app check` ships their labels (check.mjs adds them to CHECK_CODES). Append-only; the coordinator regenerates it at merge time. */
 export const A15_CODES = [
   // codes-begin
+  'FE_PUBLIC_BUILD_ARG_MISSING',
+  'HFS_WORKFLOW_CONTEXT',
+  '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
 ];
 
-export const FINDERS = [
+const FINDERS = [
   // finders-begin
+  feBuildArgsFindings,
+  workflowContextsFindings,
   featureFileFindings,
   lexiconFindings,
   assetsFindings,
@@ -72,6 +80,7 @@ export const FINDERS = [
   stacksLiteBackingFindings,
   stackToolingFindings,
   stacksDeployFindings,
+  ciCustodyFindings,
   // finders-end
 ];
 

package/runtime/scripts/hfs/rules/app-workflow-findings.mjs

@@ -0,0 +1,10 @@
+// app-workflow-findings.mjs - app-root workflow scope shared by deployment and expression-context rules.
+import { workflowFindings } from '../runtime-rules/workflow-source.mjs';
+import { readText } from './read.mjs';
+
+/** Judge tracked workflows only at full/lite app roots, preserving each caller's duplicate-file policy. */
+export function appWorkflowFindings({ repoRoot, files, all = files, repo, isRoot, inScope = () => true }, perWorkflow, { dedupe = false } = {}) {
+  if (isRoot === false || repo?.kind !== 'app' || !['lite', 'full'].includes(repo.edition)) return [];
+  const selected = dedupe ? [...new Set(all)] : all;
+  return workflowFindings({ files: selected.filter((file) => inScope(file)), read: (file) => readText(repoRoot, file) }, perWorkflow);
+}

package/runtime/scripts/hfs/rules/assets.mjs

@@ -8,7 +8,7 @@ import { found } from './read.mjs';
 
 export const HFS_ASSET_OVERSIZE = 'HFS_ASSET_OVERSIZE';
 export const HFS_ASSET_KIND = 'HFS_ASSET_KIND';
-export const DEFAULT_ASSET_BYTES = 512000;
+const DEFAULT_ASSET_BYTES = 512000;
 const BUILD_EXTENSIONS = ['.ttf', '.otf', '.woff', '.woff2', '.eot', '.png', '.svg', '.webp', '.jpg', '.jpeg', '.gif', '.ico', '.avif', '.bmp', '.tif', '.tiff'];
 const MEDIA_EXTENSIONS = new Set(['.mp3', '.mp4', '.wav', '.ogg', '.oga', '.opus', '.flac', '.aac', '.m4a', '.wma', '.aiff', '.aif', '.mid', '.midi', '.mov', '.m4v', '.webm', '.avi', '.mkv', '.mpeg', '.mpg', '.wmv', '.flv', '.3gp']);
 const IMAGE_EXTENSIONS = new Set(BUILD_EXTENSIONS.filter((ext) => !['.ttf', '.otf', '.woff', '.woff2', '.eot'].includes(ext)));

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

@@ -0,0 +1,104 @@
+// ci-custody.mjs - R296-R298: CI declarations, sealed app keys and workflow reads agree by consumer, without decrypting or contacting GitHub.
+import fs from 'node:fs';
+import { list } from '../../lib/list.mjs';
+import { findStackDeclaration, STACK_ROOT } from '../../lib/stack-declaration.mjs';
+import { readCiDeclaration, sealedKeyNames, workflowReferences, ciNamesOfServices } from '../ci-declaration.mjs';
+import { found } from './read.mjs';
+
+const DECLARATION = `${STACK_ROOT}/application-stacks.yaml`;
+const named = (entry) => typeof entry.name === 'string' && /^[A-Z][A-Z0-9_]*$/.test(entry.name);
+const identity = (kind, name) => `${kind}:${name}`;
+const atCi = (section) => `${DECLARATION}#ci.${section}`;
+
+/** A CI or Dependabot secret must never also live in a sealed app member. */
+function sealedFindings(ci, sealed) {
+  const names = new Set([...ci.secrets, ...ci.dependabotSecrets].filter(named).map((entry) => entry.name));
+  return sealed.filter(({ key }) => names.has(key)).map(({ key, file }) => found(
+    'CI_SECRET_SEALED', file,
+    `${key} is a CI secret (GitHub reads it) but it is sealed in ${file} for app containers; one key, one class: remove it from the member (starci app secret unset ...) and set it with starci app ci secret set ${key}`,
+  ));
+}
+
+/** A source selects sealed keys only from its own member and environment. */
+function sourceRuntimeFindings(source, grant, environment, { sealed, names, findings, seen }) {
+  for (const entry of sealed) {
+    if (entry.env !== environment || entry.member !== source?.member || !names.has(entry.key)) continue;
+    if (source.keys !== undefined && !list(source.keys).includes(entry.key)) continue;
+    const id = `${entry.file}:${grant.service}:${entry.key}`;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    findings.push(found('APP_SECRET_IN_CI', entry.file,
+      `${entry.key} is read by the ${grant.service} container at runtime through the ${environment} deploy grant; keep it in the .enc and drop it from ci`));
+  }
+}
+
+/** Only keys actually selected by a grant, in that grant's environment and member, are runtime consumers. */
+function runtimeFindings(doc, ci, sealed) {
+  const names = new Set([...ci.secrets, ...ci.vars].filter(named).map((entry) => entry.name));
+  const findings = [], seen = new Set();
+  for (const [environment, spec] of Object.entries(doc.environments ?? {})) {
+    for (const grant of list(spec?.deploy?.secrets?.grants)) {
+      if (typeof grant?.service !== 'string') continue;
+      for (const source of list(grant.from)) sourceRuntimeFindings(source, grant, environment, { sealed, names, findings, seen });
+    }
+  }
+  return findings;
+}
+
+/** Workflow reads are class-sensitive; legacy lists remain readable, but an absent ci block always signals migration once per name. */
+function workflowFindings(doc, declared, references) {
+  const hasCi = doc.ci !== undefined;
+  const allowed = new Set(declared.map(({ kind, name }) => identity(kind, name)));
+  if (hasCi) {
+    for (const entry of ciNamesOfServices(doc).filter(named)) {
+      const legacy = list(doc.services?.[entry.service]?.ci?.[`${entry.kind}s`]);
+      if (legacy.some((item) => (typeof item === 'string' ? item : item?.name) === entry.name)) allowed.add(identity(`${entry.kind}s`, entry.name));
+    }
+  }
+  const findings = [], seen = new Set();
+  for (const { file, kind, name } of references) {
+    if (allowed.has(identity(kind, name))) continue;
+    const id = hasCi ? `${file}:${kind}:${name}` : name;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    findings.push(found('CI_DECLARATION_DRIFT', file,
+      `${kind}.${name} is read by this workflow but is not declared in ci.${kind}; declare its name, scope and consumer in ${DECLARATION}`));
+  }
+  return findings;
+}
+
+/** Dependabot has its own store and consumer, so only Actions secrets and vars require a workflow read. */
+function driftFindings(doc, ci, references) {
+  const declared = [
+    ...ci.secrets.filter(named).map((entry) => ({ ...entry, kind: 'secrets' })),
+    ...ci.vars.filter(named).map((entry) => ({ ...entry, kind: 'vars' })),
+  ];
+  const findings = workflowFindings(doc, declared, references);
+  if (doc.ci === undefined) return findings;
+  const reads = new Set(references.map(({ kind, name }) => identity(kind, name)));
+  for (const { kind, name, optional } of declared) {
+    if (!optional && !reads.has(identity(kind, name))) findings.push(found('CI_DECLARATION_DRIFT', atCi(kind),
+      `${name} is declared in ci.${kind} as non-optional but no workflow reads it; remove the declaration, mark it optional or wire its workflow consumer`));
+  }
+  const names = new Set(declared.map(({ kind, name }) => identity(kind, name)));
+  for (const [service, entry] of Object.entries(doc.services ?? {})) {
+    for (const [field, kind] of [['token', 'secrets'], ['hostVar', 'vars']]) {
+      const name = entry?.ci?.[field];
+      if (typeof name !== 'string' || names.has(identity(kind, name))) continue;
+      findings.push(found('CI_DECLARATION_DRIFT', atCi(kind),
+        `services.${service}.ci.${field} names ${name}, which is not declared in ci.${kind}; declare the shared CI name`));
+    }
+  }
+  return findings;
+}
+
+/** Offline CI custody findings of an app root, in both lite and full editions. */
+export function ciCustodyFindings({ repoRoot, repo, isRoot }) {
+  if (repo?.kind !== 'app' || !['lite', 'full'].includes(repo.edition) || isRoot === false) return [];
+  const { doc } = findStackDeclaration(repoRoot);
+  if (!doc) return [];
+  const ci = readCiDeclaration(doc);
+  const sealed = sealedKeyNames(repoRoot, { fs });
+  const references = workflowReferences(repoRoot, { fs });
+  return [...sealedFindings(ci, sealed), ...runtimeFindings(doc, ci, sealed), ...driftFindings(doc, ci, references)];
+}

package/runtime/scripts/hfs/rules/cli.mjs

@@ -10,7 +10,7 @@ import { found } from './read.mjs';
 const CLI_REQUIRED = 'BE_CLI_REQUIRED';
 
 /** The one name of the cli app, its kind, and what its image is called below it. */
-export const CLI_APP = 'cli';
+const CLI_APP = 'cli';
 const CLI_KIND = 'cli';
 const IMAGE = 'Dockerfile';
 const CLI_FEATURE_SLOT = 'be.cli';

package/runtime/scripts/hfs/rules/contract-compat.mjs

@@ -14,7 +14,7 @@ import { isPlainObject } from '../../../engine/plain-object.mjs';
 import { found, readJson } from './read.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
 
-export const CONTRACT_BREAKING = 'BE_CONTRACT_BREAKING';
+const CONTRACT_BREAKING = 'BE_CONTRACT_BREAKING';
 
 const CONTRACTS = /^be\/contracts\/([^/]+)\/events\.pin\.json$/;
 

package/runtime/scripts/hfs/rules/contract.mjs

@@ -15,7 +15,7 @@ import { safeRemove } from '../../api/fs/safe-remove.mjs';
 import { makeTempDir } from '../../api/fs/make-temp-dir.mjs';
 import { loadTypescript } from '../../lib/package-at.mjs';
 
-export const CONTRACT_SNAPSHOT_DRIFT = 'HFS_CONTRACT_SNAPSHOT_DRIFT';
+const CONTRACT_SNAPSHOT_DRIFT = 'HFS_CONTRACT_SNAPSHOT_DRIFT';
 const GRAPHQL_TRANSPORT_SLOT = 'be.transport.graphql';
 const SNAPSHOT_OF = { graphql: 'schema.graphql', json: 'openapi.json' };
 const GRAPHQL_PLATFORM = /^src\/modules\/platform\/graphql(?:\/|\.ts$|$)/;

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

@@ -1,11 +1,11 @@
 // R251: product workflow custody, immutable dependencies and release-only triggers, in both editions.
-import { parseWorkflow, workflowFindings } from '../runtime-rules/workflow-source.mjs';
-import { found, readText } from './read.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 { workflowEventOptions } from '../../lib/workflow-events.mjs';
 
 const DEPLOY = 'HFS_DEPLOY_WORKFLOW';
-const PIN = 'HFS_WORKFLOW_PIN';
 const TOOL = 'HFS_CI_TOOL_INSTALL';
 const TRIGGER = 'HFS_APP_WORKFLOW_TRIGGER';
 // Only the age identity and SSH transport credentials belong in the CI secret store.
@@ -85,18 +85,6 @@ function triggerFindings(doc, refuse) {
   return findings;
 }
 
-function actionFindings(doc, refuse) {
-  const findings = [];
-  for (const { key, value } of entries(doc)) {
-    if (key !== 'uses') continue;
-    const local = typeof value === 'string' && /^\.\/[\w./-]+$/.test(value);
-    const remote = typeof value === 'string' && /^[\w.-]+\/[\w.-]+(?:\/[\w./-]+)?@[a-f\d]{40}$/i.test(value);
-    const container = typeof value === 'string' && /^docker:\/\/[^\s@]+@sha256:[a-f\d]{64}$/i.test(value);
-    if (!local && !remote && !container) findings.push(refuse(PIN, 'every remote uses entry needs a full 40-hex commit SHA (a container action needs a sha256 digest)'));
-  }
-  return findings;
-}
-
 function secretProblems(doc) {
   const problems = [];
   if (entries(doc).some(({ key, value }) => key === 'secrets' && value === 'inherit')) problems.push('inherited secrets are forbidden');
@@ -209,11 +197,10 @@ 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), ...actionFindings(doc, refuse), ...deploymentFindings(doc, file, refuse), ...toolFindings(doc, refuse)];
+  return [...triggerFindings(doc, refuse), ...deploymentFindings(doc, file, refuse), ...toolFindings(doc, refuse)];
 }
 
 /** Synchronous R251 findings over the tracked workflows of a lite/full app. */
-export function deployWorkflowFindings({ repoRoot, files, all = files, repo, isRoot, inScope = () => true }) {
-  if (isRoot === false || repo?.kind !== 'app' || !['lite', 'full'].includes(repo.edition)) return [];
-  return workflowFindings({ files: all.filter((file) => inScope(file)), read: (file) => readText(repoRoot, file) }, perWorkflow);
+export function deployWorkflowFindings(ctx) {
+  return appWorkflowFindings(ctx, perWorkflow);
 }