@starci/hfs 4.12.2 → 4.13.0

package/runtime/modules/schemas/application-stacks.schema.yaml

@@ -288,6 +288,12 @@ $defs:
             enum: [public, private]
       secrets: {type: array, items: {$ref: '#/$defs/ciSecret'}}
       vars: {type: array, items: {$ref: '#/$defs/ciVariable'}}
+      imageCache:
+        description: >-
+          Where the images job keeps its BuildKit layer cache: gha (default, the repository's GitHub Actions cache, one scope per image) or registry (a buildcache tag
+          beside the image in the registry, for images large enough to be evicted from the 10 GB Actions cache).
+        enum: [gha, registry]
+        default: gha
       jobs:
         description: >-
           Per-job settings of the managed CI (the CI standard, knowledge/hfs/ci-standard.yaml defaults): timeoutMinutes per job and the number of unit-run shards.
@@ -598,6 +604,26 @@ $defs:
         description: Host variable names interpolated into the rendered stack (names only).
         type: array
         items: {$ref: '#/$defs/deployKey'}
+      auto:
+        description: >-
+          true: every release tag whose CI is green deploys to this environment by itself, in the order the environments are declared (the owner's yes, given once by this setting;
+          ruling app-cicd-auto-deploy). The variable STARCI_DEPLOY_PAUSED=true on the GitHub Environment stops it without a code change. Default false (a manual dispatch deploys).
+        type: boolean
+        default: false
+      approval:
+        description: >-
+          none (default): the pipeline deploys without a human step. reviewers: the GitHub Environment has required reviewers (a public repository or Enterprise; Free, Pro and Team
+          private repositories cannot set them), which the owner configures on the environment.
+        enum: [none, reviewers]
+        default: none
+      platforms:
+        description: >-
+          The platforms the images are built for. Default [linux/amd64], the architecture of the VPS; add linux/arm64 only when an environment declares a node of that architecture
+          (the build then uses QEMU, and the release record keeps the index digest).
+        type: array
+        uniqueItems: true
+        minItems: 1
+        items: {enum: [linux/amd64, linux/arm64]}
       verify: {$ref: '#/$defs/deployVerify'}
       jobs: {$ref: '#/$defs/deployJobs'}
       tasks: {$ref: '#/$defs/deployTasks'}

package/runtime/scripts/hfs/architecture/hfs.d.mts

@@ -50,7 +50,7 @@ export declare function checkHfs(config: HfsConfig): {
     violations: ArchitectureViolation[];
     coverage: {
         status: string;
-        source: "fs" | "git";
+        source: "git" | "fs";
         rootEntries: number;
         apps: string[];
         ruleIds: string[];
@@ -69,7 +69,7 @@ export declare function checkAppRoot({ root, resolver, tree }: {
     violations: ArchitectureViolation[];
     coverage: {
         status: string;
-        source: "fs" | "git";
+        source: "git" | "fs";
         hooksPath: {
             status: string;
             reason: string;
@@ -80,7 +80,7 @@ export declare function checkAppRoot({ root, resolver, tree }: {
             hooks?: never;
         } | {
             status: string;
-            hooks: "missing" | "installed" | "empty" | "unreadable";
+            hooks: "installed" | "missing" | "empty" | "unreadable";
             reason?: never;
         };
         rootEntries: number;
@@ -100,7 +100,7 @@ export declare function checkHfsWithoutConfig(repositoryRoot: string): {
     violations: ArchitectureViolation[];
     coverage: {
         status: string;
-        source: "fs" | "git";
+        source: "git" | "fs";
         rootEntries: number;
         apps: string[];
         ruleIds: string[];
@@ -109,7 +109,7 @@ export declare function checkHfsWithoutConfig(repositoryRoot: string): {
     violations: ArchitectureViolation[];
     coverage: {
         status: string;
-        source: "fs" | "git";
+        source: "git" | "fs";
         hooksPath: {
             status: string;
             reason: string;
@@ -120,7 +120,7 @@ export declare function checkHfsWithoutConfig(repositoryRoot: string): {
             hooks?: never;
         } | {
             status: string;
-            hooks: "missing" | "installed" | "empty" | "unreadable";
+            hooks: "installed" | "missing" | "empty" | "unreadable";
             reason?: never;
         };
         rootEntries: number;

package/runtime/scripts/hfs/check.mjs

@@ -113,7 +113,7 @@ export const CHECK_CODES = Object.freeze([
     'DB_MIGRATION_SHAPE', 'DB_RLS_REQUIRED', 'DB_DYNAMIC_DDL', 'DB_POLICY_SHAPE', 'DB_DEFINER_SAFE', 'DB_STORAGE_POLICY', 'LITE_DB_MIGRATION',
     'HFS_DOCKER_HEALTHCHECK_FAKE', 'DB_APP_ROLE', 'DB_FORCE_RLS_DEFAULT',
     'DB_POLICY_TAUTOLOGY', 'DB_VIEW_UNSAFE', 'DB_STORAGE_PREFIX', 'DB_DEFINER_REVOKE',
-    'HFS_GITIGNORE_BLOCK_DRIFT', 'HFS_SONAR_CONFIG', 'HFS_COVERAGE_SCOPE_DRIFT', 'HFS_FORMAT',
+    'HFS_GITIGNORE_BLOCK_DRIFT', 'HFS_SONAR_CONFIG', 'HFS_COVERAGE_SCOPE_DRIFT', 'HFS_FORMAT', 'HFS_CHECK_CACHE_FORGED', 'HFS_CHECK_CACHE_STALE', 'HFS_CHECK_CACHE_MISSING',
     'HFS_EMPTY_DIR', 'HFS_GHOST_TREE', 'HFS_UNTRACKED_ROOT_ENTRY',
     ...A15_CODES,
     ...REFUSAL_CODES,

package/runtime/scripts/hfs/gate-threshold.mjs

@@ -1,6 +1,6 @@
 // gate-threshold.mjs - the verdict of `starci app check` and `starci app lint` (owner ruling gate-threshold-20, 2026-10-30): green
 // while fewer than GATE_ERROR_LIMIT error findings remain and none of them is a hard blocker, so a release is not held back finding
-// by finding (5, 4, 3, ...) by the last few structural nits. A plaintext secret, a failed boot proof and a broken migration block at
+// by finding (5, 4, 3, ...) by the last few structural nits. A plaintext secret, a failed boot proof, a forged check cache record and a broken migration block at
 // any count. Every finding is still printed; only the exit code changes. Typecheck, build and the tests are not judged here.
 export const GATE_ERROR_LIMIT = 20;
 /** The limit in force: policy/quality.yaml `gate.errorLimit`, handed in by the harness CLI as STARCI_GATE_ERROR_LIMIT, else 20. */
@@ -14,6 +14,7 @@ export const HARD_BLOCKERS = Object.freeze(new Set([
     'HFS_PLAINTEXT_SECRET', 'HFS_SECRET_PLAINTEXT_FILE', 'HFS_SECRET_OUTSIDE_ENC', 'HFS_SCRIPT_PLAINTEXT_LOAD', 'RT_SECRET_TRACKED',
     'STACKS_SECRET_ENV_LITERAL', 'APP_SECRET_IN_CI', 'BE_LOG_SECRET',
     'BE_APP_BOOT_PROOF_MISSING',
+    'HFS_CHECK_CACHE_FORGED',
     'DB_MIGRATION_SHAPE', 'DB_MIGRATION_DESTRUCTIVE', 'LITE_DB_MIGRATION', 'BE_MIGRATION_REVERSIBLE',
 ]));
 export function gateVerdict(errors, limit = gateErrorLimit()) {

package/runtime/scripts/hfs/rules/boot-proof.d.mts

@@ -1,5 +1,10 @@
 import type { Repo } from './rule-types.mjs';
 export declare const BE_APP_BOOT_PROOF_MISSING = "BE_APP_BOOT_PROOF_MISSING";
+/**
+ * Runs `work` with the ordinary content finder's boot proof off. The app check cache runs the proof as its own scoped step (`--wiring`,
+ * keyed on the back-end side), so the always-run app pass must not compile the Nest graph a second time.
+ */
+export declare function withoutBootProof<T>(work: () => T): T;
 /** Root scopes delegate to the be side, so each app is compiled once. */
 export declare function bootProofFindings({ repoRoot, files, all, repo, isRoot, inScope }: {
     repoRoot: string;

package/runtime/scripts/hfs/rules/boot-proof.mjs

@@ -3,9 +3,23 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { appWiring } from '../app-wiring.mjs';
 export const BE_APP_BOOT_PROOF_MISSING = 'BE_APP_BOOT_PROOF_MISSING';
+let suppressed = 0;
+/**
+ * Runs `work` with the ordinary content finder's boot proof off. The app check cache runs the proof as its own scoped step (`--wiring`,
+ * keyed on the back-end side), so the always-run app pass must not compile the Nest graph a second time.
+ */
+export function withoutBootProof(work) {
+    suppressed += 1;
+    try {
+        return work();
+    }
+    finally {
+        suppressed -= 1;
+    }
+}
 /** Root scopes delegate to the be side, so each app is compiled once. */
 export function bootProofFindings({ repoRoot, files, all = files, repo, isRoot = Boolean(repo?.sides), inScope = () => true }) {
-    if (repo?.edition !== 'lite' || isRoot || repo?.profile === 'fe' || repo?.kind === 'fe')
+    if (suppressed > 0 || repo?.edition !== 'lite' || isRoot || repo?.profile === 'fe' || repo?.kind === 'fe')
         return [];
     // Dependencies not installed (a fresh scaffold, a lint-only checkout): the Nest graph cannot be compiled, so the proof is unavailable here; CI and every installed app judge it.
     const installed = [repoRoot, path.dirname(repoRoot ?? '.')].some((dir) => dir && fs.existsSync(path.join(dir, 'node_modules')));

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

@@ -8,6 +8,8 @@ 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}`;
+/** The variables the managed workflows themselves read; an app declares none of them. STARCI_DEPLOY_PAUSED is the brake of the automatic deploy, set per GitHub environment by the owner. */
+const MANAGED_VARIABLES = ['STARCI_DEPLOY_PAUSED'];
 /** 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));
@@ -44,7 +46,7 @@ function runtimeFindings(doc, ci, sealed) {
 /** 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)));
+    const allowed = new Set([...declared.map(({ kind, name }) => identity(kind, name)), ...MANAGED_VARIABLES.map((name) => identity('vars', name))]);
     if (hasCi) {
         for (const entry of ciNamesOfServices(doc).filter(named)) {
             const legacy = list(doc.services?.[entry.service]?.ci?.[`${entry.kind}s`]);

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

@@ -47,11 +47,14 @@ 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 prefix = String(standard.deployJobPrefix ?? 'deploy-');
+    const deployIds = ids.filter((id) => id.startsWith(prefix));
+    const must = [...shape.required, ...(shape.pipeline ?? [])];
+    const missing = must.filter((id) => !ids.includes(id));
+    const extra = ids.filter((id) => !must.includes(id) && !shape.optional.includes(id) && !deployIds.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}`));
+        out.push(say('job-shape', `the jobs must be ${must.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@'));
@@ -65,6 +68,32 @@ function jobShape(doc, edition, standard, say) {
     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'}`));
+    out.push(...pipelineShape(doc, ids, deployIds, say));
+    return out;
+}
+const needsOf = (job) => (Array.isArray(job?.needs) ? job.needs.map(String) : typeof job?.needs === 'string' ? [job.needs] : []);
+/** The plan, images, verdict and deploy jobs: the verdict judges every other job and always runs, the images are the reusable images.yml, a deploy job calls stack-deploy.yml after the verdict. */
+function pipelineShape(doc, ids, deployIds, say) {
+    const out = [];
+    const others = ids.filter((id) => id !== 'verdict' && !deployIds.includes(id));
+    const verdict = doc.jobs?.verdict;
+    if (record(verdict)) {
+        const judged = needsOf(verdict);
+        const unjudged = others.filter((id) => !judged.includes(id));
+        if (unjudged.length)
+            out.push(say('job-shape', `the verdict job must need every other job; it does not need ${unjudged.join(', ')}`));
+        if (!/^(?:\$\{\{\s*)?always\(\)/.test(String(verdict.if ?? '').trim()))
+            out.push(say('job-shape', 'the verdict job runs under if: always(), so a skipped or red job reaches it'));
+    }
+    if (record(doc.jobs?.images) && doc.jobs.images.uses !== './.github/workflows/images.yml')
+        out.push(say('job-shape', 'the images job calls the reusable ./.github/workflows/images.yml'));
+    for (const id of deployIds) {
+        const job = doc.jobs[id];
+        if (!needsOf(job).includes('verdict'))
+            out.push(say('job-shape', `job ${id} deploys, so it must need the verdict job`));
+        if (job.uses !== './.github/workflows/stack-deploy.yml')
+            out.push(say('job-shape', `job ${id} deploys through the reusable ./.github/workflows/stack-deploy.yml, never with steps of its own`));
+    }
     return out;
 }
 function testSharding(doc, say) {

package/runtime/scripts/hfs/rules/database-migrations.d.mts

@@ -33,6 +33,20 @@ export declare function databaseSqlTokens(text: string): {
 export declare function databaseSqlStatements(tokens: Parsed): any[][];
 /** SQL and PL/pgSQL bodies are scanned; comments, data literals and other function languages are opaque. */
 export declare function databaseExecutableTokens(text: string, depth?: number): any[];
+/**
+ * A contract migration must not ship in the same release as the code change it depends on (cicd.md, Database migrations). The deploy applies
+ * a contract migration right after the accept, while the release it replaced is still the rollback target: if that release's code still names
+ * the destroyed object, a rollback after the contract would run code against a schema that no longer has it. The check judges exactly that
+ * with git: each contract migration that is new since the previous release tag (absent there) is read for the objects it destroys, and the
+ * be/src sources AS THEY WERE AT THE PREVIOUS RELEASE TAG must not reference them (the sources at HEAD are judged by destructiveMigrationFindings).
+ * The first release, a repository without a release tag, or an unreadable git history has no previous release and no finding. It reports
+ * DB_MIGRATION_DESTRUCTIVE (R259), a hard blocker: ship the code change in one release and its contract migration in the next.
+ */
+export declare function contractReleaseFindings({ repoRoot, migrations, git }: {
+    repoRoot: string;
+    migrations: Parsed;
+    git: Parsed;
+}): Promise<any>;
 /** Destructive changes require a contract migration and no remaining SQL/entity reference in be/src. */
 export declare function destructiveMigrationFindings({ repoRoot, migrations, files }: {
     repoRoot: string;

package/runtime/scripts/hfs/rules/database-migrations.mjs

@@ -3,6 +3,7 @@
 import { lsTree } from '../../api/git/ls-tree.mjs';
 import { mergeBase } from '../../api/git/merge-base.mjs';
 import { show } from '../../api/git/show.mjs';
+import { tag } from '../../api/git/tag.mjs';
 import { withoutGitLocalEnv } from '../../lib/git.mjs';
 import { eachInOrder, findInOrder } from '../../lib/in-order.mjs';
 import { sameText } from '../../lib/same-text.mjs';
@@ -37,12 +38,21 @@ export function defaultGit(args, { cwd }) {
         const sha = mergeBase(cwd, rest[0], rest[1]);
         return { ok: sha !== null, stdout: sha ?? '' };
     }
+    if (verb === 'previous-release')
+        return previousReleaseTag(cwd, env, rest[0]);
     let call = show;
     if (verb === 'ls-tree')
         call = lsTree;
     const result = call(rest, { cwd, env, maxBuffer: 64 * 1024 * 1024 });
     return { ok: !result.error && result.status === 0, stdout: result.stdout };
 }
+/** The nearest release tag before HEAD: the newest version among the tags HEAD contains that do not point at HEAD itself. `pattern` is a tag glob (v*). */
+function previousReleaseTag(cwd, env, pattern) {
+    const listed = (args) => { const result = tag(args, { cwd, env }); return !result.error && result.status === 0 ? String(result.stdout).split(/\r?\n/).map((line) => line.trim()).filter(Boolean) : []; };
+    const here = new Set(listed(['--points-at', 'HEAD']));
+    const previous = listed(['--merged', 'HEAD', '--list', pattern, '--sort=-v:refname']).find((name) => !here.has(name));
+    return { ok: previous !== undefined, stdout: previous ?? '' };
+}
 const runGit = (git, repoRoot, args) => Promise.resolve(git(args, { cwd: repoRoot }))
     .then((result) => ({ ok: result?.ok === true, stdout: String(result?.stdout ?? '') }));
 async function baseShaOf(git, repoRoot, base) {
@@ -515,6 +525,51 @@ function destructiveFileFindings(file, text, references) {
         return finding ? [finding] : [];
     });
 }
+const BE_SQL_SOURCE = /^be\/src\/.+\.(?:sql|entity)\.[cm]?tsx?$/;
+/** The tag glob of a release (release.tagPrefix defaults to v). */
+const RELEASE_TAG_GLOB = 'v*';
+/**
+ * A contract migration must not ship in the same release as the code change it depends on (cicd.md, Database migrations). The deploy applies
+ * a contract migration right after the accept, while the release it replaced is still the rollback target: if that release's code still names
+ * the destroyed object, a rollback after the contract would run code against a schema that no longer has it. The check judges exactly that
+ * with git: each contract migration that is new since the previous release tag (absent there) is read for the objects it destroys, and the
+ * be/src sources AS THEY WERE AT THE PREVIOUS RELEASE TAG must not reference them (the sources at HEAD are judged by destructiveMigrationFindings).
+ * The first release, a repository without a release tag, or an unreadable git history has no previous release and no finding. It reports
+ * DB_MIGRATION_DESTRUCTIVE (R259), a hard blocker: ship the code change in one release and its contract migration in the next.
+ */
+export async function contractReleaseFindings({ repoRoot, migrations, git }) {
+    const contracts = migrations.filter((file) => /_contract_[a-z0-9]+(?:[-_][a-z0-9]+)*\.sql$/.test(file));
+    if (!contracts.length)
+        return [];
+    const previous = await runGit(git, repoRoot, ['previous-release', RELEASE_TAG_GLOB]);
+    const release = previous.stdout.trim();
+    if (!previous.ok || !release)
+        return [];
+    const known = new Set(await migrationFilesAt(git, repoRoot, release));
+    const fresh = contracts.filter((file) => !known.has(file));
+    if (!fresh.length)
+        return [];
+    const listing = await runGit(git, repoRoot, ['ls-tree', '-r', '--name-only', '-z', release, '--', 'be/src']);
+    const sources = listing.ok ? listing.stdout.split('\0').filter((file) => BE_SQL_SOURCE.test(file)) : [];
+    if (!sources.length)
+        return [];
+    const ts = loadTypescript(repoRoot, HERE);
+    if (!ts)
+        return [found(DB_MIGRATION_DESTRUCTIVE, 'hfs.json', 'the contract-release check requires the TypeScript parser to read the be/src references of the previous release')];
+    const references = [];
+    await eachInOrder(sources, async (file) => {
+        references.push({ file, scopes: sourceNameScopes(ts, await baseFileText(git, repoRoot, release, file) ?? '', file) });
+    });
+    return fresh.flatMap((file) => {
+        const text = readText(repoRoot, file);
+        if (text === null)
+            return [];
+        return databaseSqlStatements(databaseExecutableTokens(text)).flatMap(destructiveObjects).flatMap((object) => {
+            const reference = references.find(({ scopes }) => referencesObject(scopes, object));
+            return reference ? [found(DB_MIGRATION_DESTRUCTIVE, file, `${file}:${object.line} destroys ${object.name}, which the previous release ${release} still references in ${reference.file}; the contract migration runs right after the accept while that release is the rollback target: ship the code change in one release and this contract migration in the next`, { line: object.line, object: object.name, release, reference: reference.file })] : [];
+        });
+    });
+}
 /** Destructive changes require a contract migration and no remaining SQL/entity reference in be/src. */
 export function destructiveMigrationFindings({ repoRoot, migrations, files }) {
     const sources = files.filter((file) => /^be\/src\/.+\.(?:sql|entity)\.[cm]?tsx?$/.test(file));

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

@@ -1,7 +1,7 @@
 // The database rules of a lite app's db/ tree (design 4.2, L02-L09). SQL migrations are parsed with libpg-query through
 // database-sql.mjs; Git history and generated-type checks are split into bounded sibling modules.
 import { found, readJson, readText } from './read.mjs';
-import { defaultGit, migrationShapeFindings } from './database-migrations.mjs';
+import { contractReleaseFindings, defaultGit, migrationShapeFindings } from './database-migrations.mjs';
 import { migrationSetPolicyFindings, sqlAnalysis } from './database-sql.mjs';
 import { migrationSetDefinerFindings } from './database-plpgsql.mjs';
 import { databaseAccessFindings } from './database-access.mjs';
@@ -66,6 +66,7 @@ export async function checkDatabase({ repoRoot, files, base, git, edition, db })
         findings.push(...liteDbPathFindings(files));
     const forceRls = new Set((declared?.forceRls ?? []).map((name) => (name.includes('.') ? name : `public.${name}`)));
     findings.push(...await migrationShapeFindings({ repoRoot, migrations, archived, git: git ?? defaultGit, base }));
+    findings.push(...await contractReleaseFindings({ repoRoot, migrations, git: git ?? defaultGit }));
     const analyses = await migrationAnalyses({ repoRoot, migrations, exposed: APP_SCHEMAS, forceRls, findings });
     findings.push(...migrationSetPolicyFindings(analyses), ...migrationSetDefinerFindings(analyses, APP_SCHEMAS), ...await databaseAccessFindings({ analyses, exposed: APP_SCHEMAS, db: declared }));
     return findings;

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

@@ -1,4 +1,6 @@
 // R251: product workflow custody, immutable dependencies and release-only triggers, in both editions.
+// A release deploys through the reusable stack-deploy.yml: its jobs hold the environment, the age key and the transport; the job of ci.yml that calls it
+// (a deployment caller) holds permissions, concurrency and the environment name it passes. A pull_request run reads and never binds an environment.
 import { parseWorkflow } from '../runtime-rules/workflow-source.mjs';
 import { found } from './read.mjs';
 import { appWorkflowFindings } from './app-workflow-findings.mjs';
@@ -71,6 +73,7 @@ const deployName = (value) => !/authorize[\s_.-]+deploy[\s_.-]+key/i.test(value)
 const materializeCommand = (script) => commands(script).some(({ text }) => /^starci\s+app\s+secret\s+materialize\b/.test(commandBody(text)));
 const DEPLOYMENT_COMMANDS = [
     /^starci\s+(?:app\s+)?(?:deploy|secret\s+materialize)\b/,
+    /^(?:npx\s+(?:--no-install\s+)?)?starci\s+app\s+stack\s+(?:deploy|rollback|accept)\b/,
     /^docker\s+stack\s+deploy\b/,
     /^(?:ba?sh\s+)?(?:\.\/)?deploy\//,
     /^(?:ba?sh\s+)?(?:\.\/)?(?:scripts\/)?[\w.-]*deploy[\w.-]*\.sh\b/,
@@ -92,22 +95,46 @@ const CANDIDATE_BRANCHES = 'release/candidate-*';
 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 > 0 && new Set(options.branches).size === options.branches.length && options.branches.every((branch) => branch === CANDIDATE_BRANCHES || (ci && branch === 'main'))));
+const isCi = (file) => /(^|\/)ci\.ya?ml$/.test(file);
+/** A pull request to main in ci.yml: the checks of a change. Read-only workflow permissions, no environment on a job of the file itself (a call of a reusable workflow cannot have one). */
+function pullRequestFindings(doc, options, refuse, file) {
+    if (!isCi(file))
+        return [refuse(TRIGGER, 'pull_request may start only ci.yml: no other app workflow runs the code of a pull request')];
+    const findings = [];
+    const filters = record(options) ? options : {};
+    const branches = filters.branches;
+    if (!Array.isArray(branches) || branches.length !== 1 || branches[0] !== 'main' || Object.keys(filters).some((key) => key !== 'branches'))
+        findings.push(refuse(TRIGGER, "pull_request may contain only branches: ['main']"));
+    const permissions = doc.permissions;
+    const readOnly = record(permissions) && Object.values(permissions).every((value) => value === 'read' || value === 'none');
+    if (!readOnly)
+        findings.push(refuse(TRIGGER, 'a workflow that runs on pull_request declares read-only workflow permissions (permissions: contents: read); a job that needs more asks for it itself'));
+    for (const [name, job] of Object.entries(record(doc.jobs) ? doc.jobs : {})) {
+        if (record(job) && job.environment !== undefined)
+            findings.push(refuse(TRIGGER, `job ${name} binds an environment in a workflow that runs on pull_request; a pull request run reads no environment secret`));
+    }
+    return findings;
+}
 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))) {
+    if (isCi(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')
+        if (event === 'workflow_dispatch' || event === 'workflow_call')
             continue;
+        if (event === 'pull_request') {
+            findings.push(...pullRequestFindings(doc, options, refuse, file));
+            continue;
+        }
         if (event !== 'push') {
-            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`));
+            findings.push(refuse(TRIGGER, `trigger ${event} is forbidden; app CI starts only on release tags [v*], the release candidate branches, main and pull requests to main in ci.yml, workflow_call or workflow_dispatch`));
             continue;
         }
-        if (!pushFilterValid(options, /(^|\/)ci\.ya?ml$/.test(file))) {
+        if (!pushFilterValid(options, isCi(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`));
         }
     }
@@ -158,6 +185,8 @@ function scriptWritesDotenv(value) {
 function writesDotenv(doc) {
     return entries(doc).some(({ key, value }) => key === 'env_file' || key === 'env-file' || (['run', 'script'].includes(key) && typeof value === 'string' && scriptWritesDotenv(value)));
 }
+/** The job of a workflow that calls a reusable workflow of the app (`uses: ./.github/workflows/<file>`): a deployment caller when the callee deploys. */
+const localCall = (job) => typeof job.uses === 'string' && job.uses.startsWith('./.github/workflows/');
 function deploymentJobs(doc, file) {
     const jobs = record(doc.jobs) ? Object.entries(doc.jobs).filter(([, job]) => record(job)) : [];
     const identified = jobs.filter(([name, job]) => deployName(name) || deployName(String(job.name ?? '')) || scripts(job).some(deploymentCommand) || (typeof job.uses === 'string' && deployName(job.uses)));
@@ -167,7 +196,23 @@ function deploymentJobs(doc, file) {
         return jobs;
     return [];
 }
+/** A deployment caller (ci.yml's deploy-<env>): permissions, concurrency and the environment it passes; the called job binds the environment and opens the key. */
+function callerFindings(name, job, doc, refuse) {
+    const findings = [];
+    const environment = record(job.with) ? job.with.environment : undefined;
+    if (job.environment !== undefined)
+        findings.push(refuse(DEPLOY, `job ${name} calls a reusable workflow, which cannot bind an environment itself; pass the name as with.environment and let the called job bind it`));
+    if (!nonempty(environment))
+        findings.push(refuse(DEPLOY, `job ${name} must pass with.environment: the GitHub environment the called deploy job binds`));
+    if (!validPermissions(job.permissions ?? doc.permissions))
+        findings.push(refuse(DEPLOY, `job ${name} must declare permissions at job or workflow scope`));
+    if (!validConcurrency(job.concurrency ?? doc.concurrency))
+        findings.push(refuse(DEPLOY, `job ${name} must declare concurrency at job or workflow scope`));
+    return findings;
+}
 function deploymentJobFindings(name, job, doc, refuse) {
+    if (localCall(job))
+        return callerFindings(name, job, doc, refuse);
     const findings = [];
     if (!validEnvironment(job.environment))
         findings.push(refuse(DEPLOY, `job ${name} must declare its protected environment`));
@@ -205,9 +250,11 @@ function deploymentFindings(doc, file, refuse) {
         findings.push(refuse(DEPLOY, 'the deploy workflow must declare a deployment job'));
     for (const [name, job] of deployment)
         findings.push(...deploymentJobFindings(name, job, doc, refuse));
-    for (const problem of secretProblems(doc))
+    // The secrets and dotenv writes are judged where the deploy runs: the workflow-level env and the deployment jobs, not a check job beside them (the Sonar token of ci.yml).
+    const judged = { env: doc.env, jobs: Object.fromEntries(deployment) };
+    for (const problem of secretProblems(judged))
         findings.push(refuse(DEPLOY, problem));
-    if (writesDotenv(doc))
+    if (writesDotenv(judged))
         findings.push(refuse(DEPLOY, 'deploy workflows must never write dotenv files or use env_file blobs; materialize sealed custody'));
     return findings;
 }

package/runtime/scripts/hfs/rules/release-provenance.mjs

@@ -1,4 +1,5 @@
-// R271: a product release keeps its v<semver> tag, root package version, image tags and database deployment ref together.
+// R271: a product release keeps its v<semver> tag, root package version, image tags and database deployment ref together. The pushed images are named by the
+// commit (sha-<sha>); the release name v<version> is a retag of that digest under a release guard. A migration runs in the stack deploy after the release tag.
 // Ordinary untagged development trees have no release version to compare. Workflow checks still run there in both editions.
 // YAML is parsed, so comments and unrelated jobs cannot supply a guard. Shell guards are deliberately a small, explicit form;
 // opaque helper scripts and computed image metadata cannot prove provenance in this static check.
@@ -171,10 +172,12 @@ function dbJobConstrained(job, guarded) {
         constrained = false;
     return constrained;
 }
+// The database deploy workflow is retired in a lite app: its migrations are the migrate phase of the stack deploy (starci app stack deploy, tag-gated by
+// stack-deploy.yml). A full app that keeps its own db-deploy.yml, and a lite app that has not synced yet, are still judged here.
 function dbFindings(file, workflow) {
     const jobs = Object.entries(workflow.jobs ?? {});
     if (!jobs.length)
-        return [found(HFS_DB_DEPLOY_UNGUARDED, file, `${file} has no verifiable database deploy job; require a release tag before migration`)];
+        return [found(HFS_DB_DEPLOY_UNGUARDED, file, `${file} has no verifiable database deploy job; require a release tag before migration (a lite app's migrations are the migrate phase of the stack deploy: run starci app sync --execute to retire this file)`)];
     const findings = [];
     for (const [name, job] of jobs) {
         if (!job || typeof job !== 'object')
@@ -203,17 +206,42 @@ function imageTagIsRelease(value, version) {
         return SEMVER.test(String(version)) && ref.endsWith(`:v${version}`);
     });
 }
+/** A commit tag: `<repo>:sha-${{ github.sha }}`, immutable and per commit, so any ref may push it. */
+const COMMIT_TAG = /^.+:sha-\$\{\{\s*github\.sha\s*\}\}$/;
+function imageTagsAreCommit(value) {
+    if (typeof value !== 'string')
+        return false;
+    const tags = value.split(/[\n,]+/).map((tag) => tag.trim()).filter(Boolean);
+    return tags.length > 0 && tags.every((tag) => COMMIT_TAG.test(tag));
+}
+/** The release guard of a reusable images workflow: a step under `if: ${{ inputs.release }}` whose script rejects a ref that is not refs/tags/v*. */
+function inputReleaseGuard(step) {
+    if (typeof step.run !== 'string' || step['continue-on-error'] || !/^\$\{\{\s*inputs\.release\s*\}\}$/.test(String(step.if ?? '').trim()))
+        return false;
+    const first = step.run.trim().split(/\r?\n/)[0].trim();
+    return /^\[\[\s*["']?\$(?:GITHUB_REF|\{GITHUB_REF\})["']?\s*==\s*refs\/tags\/v\*\s*\]\]\s*\|\|\s*exit\s+[1-9]\d*\s*;?$/.test(first);
+}
+/** The release name v<version> is a retag of the commit digest (`imagetools create --tag <repo>:$GITHUB_REF_NAME <repo>:sha-...`): only after the guard, only on a release run. */
+function retagIsGuarded(job, step) {
+    const steps = job.steps ?? [];
+    const guard = steps.findIndex(inputReleaseGuard);
+    return guard >= 0 && guard < steps.indexOf(step) && /^\$\{\{\s*inputs\.release\s*&&/.test(String(step.if ?? '').trim());
+}
 function imageFindings(file, workflow, version) {
     const findings = [];
     let builds = 0;
     for (const [name, job] of Object.entries(workflow.jobs ?? {})) {
         for (const step of job?.steps ?? []) {
+            if (typeof step.run === 'string' && /\bimagetools\s+create\b/.test(step.run) && !retagIsGuarded(job, step)) {
+                findings.push(found(HFS_RELEASE_TAG_MISMATCH, file, `${file} job ${name} retags an image outside a release guard; put it after a step \`if: \${{ inputs.release }}\` that rejects a ref other than refs/tags/v*, and under \`if: \${{ inputs.release && ... }}\``, { job: name }));
+            }
             if (!(step.uses ?? '').startsWith('docker/build-push-action@'))
                 continue;
             builds += 1;
             const guarded = tagOnlyTrigger(workflow) || refProof(job.if) === RELEASE_REF || refProof(step.if) === RELEASE_REF;
-            if (!guarded || !checkoutPreservesRef(job) || !imageTagIsRelease(step.with?.tags, version))
-                findings.push(found(HFS_RELEASE_TAG_MISMATCH, file, `${file} job ${name} must build the checked-out release ref and tag every image with v<package.json version> or github.ref_name under a release-tag guard`, { job: name }));
+            // An immutable commit tag (sha-<sha>) is pushed by any ref; a release name must come from the checked-out release ref under a guard.
+            if (!checkoutPreservesRef(job) || !(imageTagsAreCommit(step.with?.tags) || (guarded && imageTagIsRelease(step.with?.tags, version))))
+                findings.push(found(HFS_RELEASE_TAG_MISMATCH, file, `${file} job ${name} must build the checked-out ref and tag every image with sha-\${{ github.sha }} (the release name v<package.json version> is a guarded retag of that digest), or tag with v<version> or github.ref_name under a release-tag guard`, { job: name }));
         }
     }
     if (!builds)

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

@@ -20,7 +20,8 @@ const allowedExpressions = (allows) => allows.flatMap((entry) => braceVariants(e
 const shapeFinding = (file, message, extra) => found(STACKS_SHAPE, file, message, extra);
 function treeFindings(files, allowed, prefix) {
     const findings = [];
-    for (const file of files.filter((f) => f.startsWith(prefix))) {
+    // `cache` is reserved: .starcistacks/cache/ is the committed check cache (slot app.starcistacks.cache), written by the CLI, not an environment.
+    for (const file of files.filter((f) => f.startsWith(prefix) && !f.startsWith(`${prefix}cache/`))) {
         const rel = file.slice(prefix.length);
         if (/\.enc(?:\.yaml)?$/.test(rel) && !INSIDE_SECRETS.test(rel))
             findings.push(shapeFinding(file, `${file} is a sealed secret outside <env>/secrets/<slug>.enc.yaml; move it to .starcistacks/<env>/secrets/`));
@@ -34,6 +35,9 @@ function declarationFindings(files, prefix, declaration) {
     if (!files.includes(declared))
         return [];
     const findings = [];
+    const environments = declaration.doc?.environments;
+    if (environments !== null && typeof environments === 'object' && Object.hasOwn(environments, 'cache'))
+        findings.push(shapeFinding(declared, `${declared} declares an environment named cache; the name is reserved for the committed check cache (.starcistacks/cache/)`));
     if (declaration.error)
         return [shapeFinding(declared, `${declared} cannot be read: ${declaration.error}`)];
     const services = declaration.doc?.services;

package/runtime/scripts/hfs/rules/supply-chain.mjs

@@ -5,7 +5,10 @@ const DEPENDABOT = '.github/dependabot.yml';
 const CI = '.github/workflows/ci.yml';
 const IMAGES = '.github/workflows/images.yml';
 const ECOSYSTEMS = ['npm', 'github-actions', 'docker'];
-const enabled = (entry) => entry && (entry.if === undefined || entry.if === true || entry.if === 'true') && !entry['continue-on-error'];
+// A job the plan or the caller decides is no disabled job: a reusable workflow runs a job on `if: ${{ inputs.release }}` whenever its caller asks, and the CI jobs
+// run on `if: ${{ needs.plan.outputs.checks == 'true' }}` on every run that checks (the plan leaves them out only where a green run of the same commit stands in).
+const DECIDED_CONDITION = /^\$\{\{\s*(?:inputs\.[A-Za-z_][\w-]*|needs\.plan\.outputs\.[A-Za-z_]\w*\s*==\s*'true')\s*\}\}$/;
+const enabled = (entry) => entry && (entry.if === undefined || entry.if === true || entry.if === 'true' || (typeof entry.if === 'string' && DECIDED_CONDITION.test(entry.if.trim()))) && !entry['continue-on-error'];
 function shellSeparator(line, index, quote) {
     if (quote)
         return null;