@starci/hfs 4.12.2 → 4.13.2

package/release/records.d.mts

@@ -15,4 +15,19 @@ export declare function recordRow(dir: string, head: string, row: {
 }): void;
 /** The recorded green row of `head` whose name and command match and whose log still has the recorded sha256, or null. */
 export declare function greenRow(dir: string, head: string, name: string, command: string): Json;
+/** The trailer keys an urgent release writes into its tag annotation (WP3 of contexts/project/cicd.md): the tag's CI run reads them to back-fill the record. */
+export declare const URGENT_TRAILER = "Starci-Urgent";
+export declare const URGENT_REASON_TRAILER = "Starci-Urgent-Reason";
+/** What the trailers of an urgent tag say: who released it and why. */
+export interface UrgentTrailers {
+    role: string;
+    reason: string;
+}
+/** The trailer block of an urgent tag annotation: one `Starci-Urgent: <role>` and one `Starci-Urgent-Reason: <text>` line (the reason is one line, so it cannot forge a trailer). */
+export declare function urgentTrailerBlock(role: string, reason: string): string;
+/**
+ * The urgent trailers of a tag annotation, read from its last paragraph (the place `git interpret-trailers` reads), or null when it has none.
+ * Both keys must be there; the last occurrence of a key wins, like git's own parse.
+ */
+export declare function parseUrgentTrailers(message: string): UrgentTrailers | null;
 export {};

package/release/records.mjs

@@ -53,3 +53,28 @@ export function greenRow(dir, head, name, command) {
     const row = rows.find((known) => known?.name === name && known.command === command && known.pass === true);
     return row && row.log && fileSha256(row.log) === row.logSha256 ? row : null;
 }
+/** The trailer keys an urgent release writes into its tag annotation (WP3 of contexts/project/cicd.md): the tag's CI run reads them to back-fill the record. */
+export const URGENT_TRAILER = 'Starci-Urgent';
+export const URGENT_REASON_TRAILER = 'Starci-Urgent-Reason';
+/** The role as a trailer value: the caller's role name (letters, digits, dot, dash, underscore); anything else becomes a dash. */
+const trailerRole = (role) => role.replaceAll(/[^\w.-]/gu, '-');
+/** The trailer block of an urgent tag annotation: one `Starci-Urgent: <role>` and one `Starci-Urgent-Reason: <text>` line (the reason is one line, so it cannot forge a trailer). */
+export function urgentTrailerBlock(role, reason) {
+    return `${URGENT_TRAILER}: ${trailerRole(role)}\n${URGENT_REASON_TRAILER}: ${reason.replaceAll(/\s+/gu, ' ').trim()}`;
+}
+/**
+ * The urgent trailers of a tag annotation, read from its last paragraph (the place `git interpret-trailers` reads), or null when it has none.
+ * Both keys must be there; the last occurrence of a key wins, like git's own parse.
+ */
+export function parseUrgentTrailers(message) {
+    const last = message.replaceAll('\r\n', '\n').trim().split(/\n\s*\n/u).at(-1) ?? '';
+    const found = new Map();
+    for (const line of last.split('\n')) {
+        const match = /^([A-Za-z][A-Za-z0-9-]*):[ \t]*(.*)$/u.exec(line.trimEnd());
+        if (match)
+            found.set(match[1], match[2].trim());
+    }
+    const role = found.get(URGENT_TRAILER);
+    const reason = found.get(URGENT_REASON_TRAILER);
+    return role && reason ? { role, reason } : null;
+}

package/release/urgent.mjs

@@ -11,7 +11,7 @@ import { firstLine } from '../stack/context.mjs';
 import { failure, refusal } from '../stack/errors.mjs';
 import { assertUnmoved, git, inspect, releaseDir, runGate, summaryOf } from './gate.mjs';
 import { assertNames, branchRefs, probe, tagRefs } from './push.mjs';
-import { URGENT_RULING, URGENT_SCHEMA, greenRow, recordRow, writeUrgent } from './records.mjs';
+import { URGENT_RULING, URGENT_SCHEMA, greenRow, parseUrgentTrailers, recordRow, urgentTrailerBlock, writeUrgent } from './records.mjs';
 /**
  * The fast local checks of an urgent release, by gate name, in the order they run: what can break production, the types and the build
  * (owner ruling urgent-typecheck-build, 2026-10-30). App check, lint and the tests wait for the back-fill (`release gate --backfill`).
@@ -61,6 +61,25 @@ function planOf(checks) {
     return ['urgent checks (each must pass; a green row recorded for HEAD with the same command and log is reused):',
         ...checks.map((check) => `  ${check.name.padEnd(10)} ${check.gate ? check.gate.command.join(' ') : '(nothing to run)'}${check.note ? `  [${check.note}]` : ''}`)];
 }
+/**
+ * Writes the urgent trailers (`Starci-Urgent`, `Starci-Urgent-Reason`) into the annotation of the release tag, so the tag's own CI run knows the release was
+ * urgent and back-fills its record instead of deploying it again. A new tag carries them from the start; a tag the gate already put on HEAD and nobody has
+ * published yet is re-annotated (its message kept, the trailers appended); a tag already on the remote is never moved, so it stays without them and the line says so.
+ */
+function annotateTag(ctx, { tag, head, role, reason, onHead, unpublished }) {
+    const trailers = urgentTrailerBlock(role, reason);
+    if (!onHead) {
+        git(ctx, ['tag', '-a', tag, '-m', `URGENT release ${tag} on ${head.slice(0, 12)} by ${role}: ${reason} (fast local checks only; back-fill: starci app release gate --backfill ${tag})`, '-m', trailers, head]);
+        return { written: true, line: `tag trailers   ${tag}: Starci-Urgent, Starci-Urgent-Reason` };
+    }
+    const message = git(ctx, ['for-each-ref', '--format=%(contents)', `refs/tags/${tag}`]).stdout;
+    if (parseUrgentTrailers(message))
+        return { written: true, line: `tag trailers   ${tag}: already there` };
+    if (!unpublished)
+        return { written: false, line: `tag trailers   NONE: ${tag} is already published without them and a published tag is never moved; the deploy record still names the urgent role and reason` };
+    git(ctx, ['tag', '-a', '-f', tag, '-m', message.trim() === '' ? `release ${tag}` : message.trim(), '-m', trailers, head]);
+    return { written: true, line: `tag trailers   ${tag}: re-annotated (not yet published): Starci-Urgent, Starci-Urgent-Reason` };
+}
 /**
  * `starci app release push --urgent`. options: { execute, remote, reason, role, platform }. Dry run prints the checks, the tag and the push it would
  * make; --execute runs them, tags, pushes atomically and writes the urgent record. A red check is RELEASE_URGENT_CHECK_RED: nothing tagged, nothing pushed.
@@ -94,8 +113,8 @@ export async function releaseUrgentPush(ctx, config, options = {}) {
     if (failed)
         throw failure('RELEASE_URGENT_CHECK_RED', `${failed.name} is red (${failed.detail}; log ${failed.log}): nothing tagged, nothing pushed`);
     assertUnmoved(ctx, head);
-    if (chosen.state !== 'on-head')
-        git(ctx, ['tag', '-a', chosen.tag, '-m', `URGENT release ${chosen.tag} on ${head.slice(0, 12)} by ${role}: ${reason} (fast local checks only; back-fill: starci app release gate --backfill ${chosen.tag})`, head]);
+    const trailers = annotateTag(ctx, { tag: chosen.tag, head, role, reason, onHead: chosen.state === 'on-head', unpublished: refs.includes(`refs/tags/${chosen.tag}`) });
+    out.push(trailers.line);
     if (refs.length > 0) {
         const hook = probe(ctx, remote, refs, red);
         out.push(...hook.lines);
@@ -107,7 +126,7 @@ export async function releaseUrgentPush(ctx, config, options = {}) {
     }
     const record = {
         schema: URGENT_SCHEMA, head, tag: chosen.tag, createdAt: new Date(ctx.now()).toISOString(), producedBy: 'starci app release push --urgent',
-        role, reason, ruling: URGENT_RULING, remote, branch, refs, pushed: true, checks: rows, backfill: null,
+        role, reason, trailers: trailers.written, ruling: URGENT_RULING, remote, branch, refs, pushed: true, checks: rows, backfill: null,
     };
     writeUrgent(common, record);
     return { ok: true, lines: [...out, `pushed to ${remote}: ${refs.join(' ') || '(already there)'}`, `URGENT record written: ${path.join(common, `${head}.urgent.json`)}`, `back-fill later: starci app release gate --backfill ${chosen.tag} --execute (in a clean checkout of ${chosen.tag})`], data: { ...data, pushed: true, record: path.join(common, `${head}.urgent.json`) } };

package/runtime/knowledge/grammars/core/playbook.yaml

@@ -357,8 +357,8 @@ guidance:
       NumberField, DateField, TimeField, Select, ComboBox, DatePicker, DateRangePicker, Checkbox,
       CheckboxGroup, RadioGroup, OtpInput and PressableField resolve variant="secondary" inside it and
       variant="primary" outside. Compose the surface and omit the field variant.
-      Switch and Slider have no layer variant; a Radio follows its RadioGroup. ChatWorkspace's
-      compact drawer also establishes the context. SurfaceCard and bounded SurfaceAccordionCard derive
+      Switch and Slider have no layer variant; a Radio follows its RadioGroup. PaneGrid's
+      collapsed-pane drawer also establishes the context. SurfaceCard and bounded SurfaceAccordionCard derive
       data-grammar-surface-depth from the parent context. The top layer is raised and a nested layer is
       subordinate; never raise both. The family DNA owns their surface paint.
       FE_NESTED_VARIANT rejects a static field variant
@@ -597,23 +597,17 @@ presentation:
         Retained ownership reference, not proof of the current package/API. Verify actual installed source/props/tokens before use; correct outdated rows within selected maintenance scope using [source and maintenance](index.yaml#source-and-maintenance).
         A part that carries one rule per side or per property names that CSS property after the part (`item padding-inline`); one part and property has one rule.
       rows:
-        - component: ChatWorkspace
-          element: drawer body, hasRail, isCompactRail
+        - component: PaneGrid
+          element: drawer body, collapsing pane
           rule: PADDING-0
-        - component: ChatWorkspace
-          element: overlay rail, hasRail, isCompactRail
-          rule: PADDING-4
-        - component: ChatWorkspace
-          element: overlay rail, hasRail, not isCompactRail
-          rule: PADDING-4
-        - component: ChatWorkspace
-          element: rail trigger boundary padding-block, hasRail, isCompactRail
+        - component: PaneGrid
+          element: trigger bar padding-block, collapsing pane
           rule: PADDING-2
-        - component: ChatWorkspace
-          element: rail trigger boundary padding-inline, hasRail, isCompactRail
+        - component: PaneGrid
+          element: trigger bar padding-inline, collapsing pane
           rule: PADDING-4
-        - component: ChatWorkspace
-          element: rail trigger, hasRail, isCompactRail
+        - component: PaneGrid
+          element: drawer trigger, collapsing pane
           rule: PADDING-3
         - component: EmptyNotice
           element: root
@@ -959,8 +953,8 @@ presentation:
         source/props/tokens before use; correct outdated rows within selected maintenance scope using [source
         and maintenance](index.yaml#source-and-maintenance).
       rows:
-        - component: ChatWorkspace
-          element: rail trigger, hasRail, isCompactRail
+        - component: PaneGrid
+          element: drawer trigger, collapsing pane
           rule: FONT-2
         - component: Heading
           element: root, scale!="display", level=1

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -31,42 +31,42 @@ pins:
     source: packages/event-stream/package.json
     why: 'the one server-sent-events client of every front end (fe-stack event-stream, owner:event-stream-package): the transport client layer (modules/api/sse/clients) creates one instance for the app with the bearer token source and the stream operations follow on it; it carries Last-Event-ID resume, the capped doubling backoff, the heartbeat timeout, the single 401 renewal and the useSWRSubscription adapter, so no app keeps a hand-written reader.'
   '@starci/grammar':
-    version: 0.16.2
+    version: 0.16.5
     group: starci
     install: registry
     side: fe
     source: packages/grammar/package.json
     why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
   '@starci/eslint-canon-be':
-    version: 3.9.2
+    version: 3.10.0
     group: starci
     install: registry
     side: be
     source: packages/eslint-canon-be/package.json
     why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
   '@starci/eslint-canon-fe':
-    version: 9.6.2
+    version: 9.6.5
     group: starci
     install: registry
     side: fe
     source: packages/eslint-canon-fe/package.json
     why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
   '@starci/eslint-grammar-core':
-    version: 0.16.2
+    version: 0.16.5
     group: starci
     install: registry
     side: fe
     source: packages/eslint-grammar-core/package.json
     why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
   '@starci/eslint-grammar-offset-pop':
-    version: 0.16.2
+    version: 0.16.5
     group: starci
     install: registry
     side: fe
     source: packages/eslint-grammar-offset-pop/package.json
     why: 'the Offset Pop Grammar component API lint, versioned with @starci/grammar; its shared component contract comes from the StarCi family lint without copying rules.'
   '@starci/stylelint-canon':
-    version: 2.2.1
+    version: 2.3.0
     group: starci
     install: registry
     side: fe
@@ -85,7 +85,7 @@ pins:
     side: both
     source: packages/prettier-config/package.json
   '@starci/jest-preset':
-    version: 2.5.3
+    version: 2.6.0
     group: starci
     install: registry
     side: be
@@ -106,7 +106,7 @@ pins:
     source: packages/ai-router/package.json
     why: 'the AI pool router of a back end: a NestJS module that routes OpenAI-compatible chat, stream and embeddings calls across keys, models and providers, with @starci/ai-router/testing for its specs; @starci/jest-preset compiles it as an ESM-only dependency.'
   '@starci/hfs':
-    version: 4.12.2
+    version: 4.13.2
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/ci-standard.yaml

@@ -11,10 +11,18 @@ title: The one StarCi CI standard
 # over the runtime's own workflows) checks every item marked `check: ci-standard`; the other items are owned by the rule or render named in `by`.
 # Apps get the standard only through `starci app sync`: the managed CI files are sync targets, and `starci app sync` (the dry run) / the app check refuse drift.
 
-# The jobs of the managed app CI (job ids, in this order), per edition; `sonar` exists when the Sonar service is enabled.
+# The jobs of the managed app CI (job ids, in this order), per edition; `sonar` exists when the Sonar service is enabled. `plan` decides what a run does,
+# `images` builds the images once per commit beside the checks (a call of the reusable images.yml, so GitHub names its jobs `images / ...`), `verdict` is
+# the one job branch protection requires and the deploy waits for.
+#   required   the jobs a green run has concluded success. The CLI's `stack deploy --ci-run` reads this list from here and asks GitHub for each of them
+#              in the run it is given, so the list names the jobs GitHub reports under their own id; the verdict needs `images`, so it proves them.
+#   pipeline   the jobs the workflow must hold besides those, judged through the verdict
 jobs:
-  full: {required: [fast, lint, test, coverage, build], optional: [sonar]}
-  lite: {required: [fast, lint, test, coverage, build], optional: [db-types, sonar]}
+  full: {required: [plan, fast, lint, test, coverage, build, verdict], pipeline: [images], optional: [sonar]}
+  lite: {required: [plan, fast, lint, test, coverage, build, verdict], pipeline: [images], optional: [db-types, sonar]}
+
+# One job per environment with deploy.auto follows the verdict: its id starts with this prefix and it calls the reusable stack-deploy.yml.
+deployJobPrefix: deploy-
 
 # The per-job settings the managed CI renders when .starcistacks/application-stacks.yaml ci.jobs leaves them out (ci.jobs.<job>.timeoutMinutes,
 # ci.jobs.test.shards). Sized from a real run (NIVO v0.2.3 on the 2-vCPU GitHub runner, 2026-10-18): the be lint with the Sonar import took 11.5 minutes and the
@@ -34,14 +42,29 @@ heap:
 items:
   - id: candidate-trigger
     title: the release CI runs on the release candidate ref
-    requires: "ci.yml runs on push of branches ['main', 'release/candidate-*'] and tags ['v*'] (and workflow_dispatch); the release flows wait for the run of the release sha there"
+    requires: "ci.yml runs on push of branches ['main', 'release/candidate-*'] and tags ['v*'], on pull_request to main and on workflow_dispatch; the release flows wait for the run of the release sha there; pull_request_target, workflow_run and schedules are never triggers"
     covers: [app-ci, runtime]
     by: [R221 CI_TRIGGERS_RELEASE_ONLY, R251 HFS_APP_WORKFLOW_TRIGGER]
   - id: job-shape
-    title: the job shape fast / lint / test / coverage / build / sonar
-    requires: "the managed CI holds exactly the jobs of `jobs` for its edition; the unit run is a step of `test`; the merge, the coverage proof and the Codecov upload are steps of `coverage`, which alone holds the OIDC id-token"
+    title: the job shape plan / fast / lint / test / coverage / build / images / verdict / sonar and the deploy jobs
+    requires: "the managed CI holds exactly the jobs of `jobs` for its edition and one `deploy-<env>` job per environment with deploy.auto; the unit run is a step of `test`; the merge, the coverage proof and the Codecov upload are steps of `coverage`, which alone holds the OIDC id-token; the verdict needs every other job and runs always; a deploy job needs the verdict and calls the reusable stack-deploy.yml, and no other job deploys"
     covers: [app-ci]
     check: ci-standard
+  - id: pull-request-ci
+    title: a pull request runs the checks with no secret and no environment
+    requires: "a workflow that runs on pull_request has read-only workflow permissions, binds no job to an environment and reads no secret outside the jobs the plan skips for a pull request (sonar); it never checks out or runs the code of a pull request under pull_request_target"
+    covers: [app-ci]
+    by: [R221 CI_TRIGGERS_RELEASE_ONLY, R251 HFS_APP_WORKFLOW_TRIGGER]
+  - id: images-once
+    title: the images are built once per commit, in parallel with the checks, and pushed by digest
+    requires: "images.yml is a reusable workflow (workflow_call) that ci.yml calls beside the checks; every pushed image carries the immutable tag sha-<sha> (the release tag v<version> is a retag of that digest), an SBOM and provenance; the deploy takes digests only; no mutable environment tag is deployed; build arguments are public values"
+    covers: [app-ci]
+    by: [R271 HFS_RELEASE_TAG_MISMATCH, R269 HFS_SBOM_MISSING]
+  - id: deploy-brake
+    title: a green release tag deploys by itself, and STARCI_DEPLOY_PAUSED stops it
+    requires: "the deploy of an environment with deploy.auto starts only on a release tag run after the verdict, bound to that GitHub Environment (deployment refs restricted to v* tags); its variable STARCI_DEPLOY_PAUSED=true skips the automatic deploy without a code change; a manual dispatch of stack-deploy.yml ignores the brake"
+    covers: [app-ci]
+    by: [R251 HFS_DEPLOY_WORKFLOW]
   - id: full-history-base-ref
     title: full history and the lint base STARCI_BASE_REF
     requires: "every actions/checkout of the managed CI fetches the full history (fetch-depth: 0), and the lint job writes STARCI_BASE_REF to GITHUB_ENV before it lints"

package/runtime/knowledge/hfs/rules.yaml

@@ -3776,7 +3776,7 @@ rules:
       - {path: packages/hfs/src/hfs-lite-secrets.spec.mjs, edition: lite}
   - id: R221
     code: "CI_TRIGGERS_RELEASE_ONLY"
-    law: "Workflow triggers are push filtered to v* tags or release/candidate-* branches, and workflow_dispatch. Runtime workflows and app ci.yml also admit main. App ci.yml includes the candidate branch filter for starci app release push. Other branches, events, path filters and ignore filters are refused."
+    law: "Workflow triggers are push filtered to v* tags or release/candidate-* branches, workflow_call (a reusable workflow has no trigger of its own) and workflow_dispatch. Runtime workflows and app ci.yml also admit main, and app ci.yml admits pull_request to main (branches ['main'] only: a pull request run has no secret and no environment). App ci.yml includes the candidate branch filter for starci app release push. pull_request_target, workflow_run, schedules, other branches, events, path filters and ignore filters are refused."
     scope: runtime
     editions: [lite, full]
     docs: [docs/git-governance.md#r221]
@@ -4195,7 +4195,7 @@ rules:
     editions: [lite, full]
     docs:
       - {path: docs/application-stacks.md#r251-deploy-workflow, editions: [lite, full]}
-    law: "In lite and full apps, deployment jobs declare a protected environment, explicit permissions and concurrency, materialize sealed secrets through SOPS_AGE_KEY or starci app secret materialize, and reference only the age key and transport SSH key/known_hosts secrets; every job that reads secrets.SOPS_AGE_KEY, a deployment job or not, is bound to the GitHub Environment whose members it opens, so it reads that environment's server key and never a repository secret of that name. Deployment jobs never embed a dotenv blob or write a dotenv file. Every remote workflow action uses a 40-hex commit SHA (local actions are allowed and container actions require a full sha256 digest); supply-chain reports each unpinned uses reference at its source line, including disabled jobs and steps; installed tools are checksum or digest verified, or supplied by a pinned action. App workflows start only on release tags [v*], the release candidate branches release/candidate-* (required in ci.yml: starci app release push waits for that run, owner ruling candidate-ci 2026-10-18) or workflow_dispatch; ci.yml also runs on main, and other branch pushes are refused."
+    law: "In lite and full apps, deployment jobs declare a protected environment, explicit permissions and concurrency, materialize sealed secrets through SOPS_AGE_KEY or starci app secret materialize, and reference only the age key and transport SSH key/known_hosts secrets; every job that reads secrets.SOPS_AGE_KEY, a deployment job or not, is bound to the GitHub Environment whose members it opens, so it reads that environment's server key and never a repository secret of that name. Deployment jobs never embed a dotenv blob or write a dotenv file. Every remote workflow action uses a 40-hex commit SHA (local actions are allowed and container actions require a full sha256 digest); supply-chain reports each unpinned uses reference at its source line, including disabled jobs and steps; installed tools are checksum or digest verified, or supplied by a pinned action. App workflows start only on release tags [v*], the release candidate branches release/candidate-* (required in ci.yml: starci app release push waits for that run, owner ruling candidate-ci 2026-10-18), workflow_call or workflow_dispatch; ci.yml also runs on main and on pull_request to main (read-only workflow permissions, no environment bound in the file), and other branch pushes are refused. A release deploys through the reusable stack-deploy.yml (ruling app-cicd-auto-deploy): the job of ci.yml that calls it (deploy-<env>, after the verdict job) holds permissions, concurrency and with.environment, the called deploy job binds the GitHub Environment (deployment refs restricted to v* tags) and reads SOPS_AGE_KEY there, and the transport is the sealed member vps-ci opened with that key, so the CI deploy key, the host and the pinned host keys are never GitHub secrets, workflow text or log lines; STARCI_DEPLOY_PAUSED on the environment stops the automatic deploy. The secrets allowlist and the dotenv ban are judged on the deployment jobs, not on the check jobs beside them."
     kinds: [check]
     gates: [settle, land, ci]
     failureCodes: ["HFS_DEPLOY_WORKFLOW", "HFS_WORKFLOW_PIN", "HFS_CI_TOOL_INSTALL", "HFS_APP_WORKFLOW_TRIGGER"]
@@ -4205,7 +4205,7 @@ rules:
     proves:
       - {path: packages/hfs/src/hfs-deploy-workflow.spec.mjs, editions: [lite, full]}
     exemplifiedBy:
-      - {path: packages/hfs/templates/app/ci-workflows-lite/github/workflows/db-deploy.yml, edition: lite}
+      - {path: packages/hfs/templates/app/ci-workflows-lite/github/workflows/stack-deploy.yml, edition: lite}
       - {path: packages/hfs/templates/app/ci-workflows/github/workflows/ci.yml, edition: full}
       - {path: packages/hfs/src/hfs-deploy-workflow.spec.mjs, editions: [lite, full]}
     witness:
@@ -4224,7 +4224,7 @@ rules:
     proves:
       - {path: packages/hfs/src/hfs-script-hygiene.spec.mjs, editions: [lite, full]}
     exemplifiedBy:
-      - {path: packages/hfs/templates/app/ci-workflows-lite/github/workflows/db-deploy.yml, edition: lite}
+      - {path: packages/hfs/templates/app/ci-workflows-lite/github/workflows/stack-deploy.yml, edition: lite}
       - {path: packages/hfs/templates/app/ci-workflows/github/workflows/ci.yml, edition: full}
       - {path: packages/hfs/src/hfs-script-hygiene.spec.mjs, editions: [lite, full]}
     witness:
@@ -4331,7 +4331,7 @@ rules:
     editionWhy: "owner:lite-backing-services makes the db service lite's database; database configuration, extension, migration and seed requirements apply to that backing."
     docs: [docs/microservices.md#r259]
     templateNa: "Extension use, contract migrations, vault operations and seed literals are product-authored db content, rather than a scaffolded SQL surface."
-    law: "DB_CONFIG_EXT: extensions belong to the database allowlist, vault writes and migration role passwords are refused, and seed data holds no real email or phone. Destructive DDL belongs only to *_contract_* migrations whose targets are no longer referenced by back-end SQL or entities. Seeds contain no real email or phone literals."
+    law: "DB_CONFIG_EXT: extensions belong to the database allowlist, vault writes and migration role passwords are refused, and seed data holds no real email or phone. Destructive DDL belongs only to *_contract_* migrations whose targets are no longer referenced by back-end SQL or entities, and a contract migration that is new since the previous release tag (the newest v* tag HEAD contains) never destroys an object that the back-end sources of that tag still reference: the deploy applies it right after the accept, while that release is the rollback target, so the code change goes in one release and its contract migration in the next. Seeds contain no real email or phone literals."
     kinds: [check]
     gates: [settle, land, ci]
     failureCodes: ["DB_EXTENSION_ALLOWED", "DB_MIGRATION_DESTRUCTIVE", "HFS_SEED_PII", "DB_VAULT_WRITE"]
@@ -4600,7 +4600,7 @@ rules:
       - {path: packages/hfs/src/hfs-doc-fresh.spec.mjs, edition: full}
   - id: R271
     code: "HFS_RELEASE_TAG_MISMATCH"
-    law: "A lite or full product release uses a v-prefixed semantic version tag equal to package.json version; images.yml publishes images under that release tag, and every database deployment refuses a non-tag ref before migration."
+    law: "A lite or full product release uses a v-prefixed semantic version tag equal to package.json version; images.yml pushes each image under the immutable tag sha-<github.sha> and adds the release name v<version> only as a retag of that digest on a release tag run, under a guard that rejects any other ref; and every database deployment refuses a non-tag ref before migration (a lite app migrates inside its stack deploy, which stack-deploy.yml starts only from a release tag, so its db-deploy.yml is retired and starci app sync removes it)."
     kinds: [check]
     gates: ["settle","land","ci"]
     failureCodes: ["HFS_RELEASE_TAG_MISMATCH", "HFS_DB_DEPLOY_UNGUARDED"]
@@ -4614,7 +4614,7 @@ rules:
     exemplifiedBy:
       - {"path":"packages/hfs/templates/app/ci-workflows-lite/github/workflows/images.yml","edition":"lite"}
       - {"path":"packages/hfs/templates/app/ci-workflows/github/workflows/images.yml","edition":"full"}
-      - {"path":"packages/hfs/templates/app/ci-workflows-lite/github/workflows/db-deploy.yml","edition":"lite"}
+      - {"path":"packages/hfs/templates/app/ci-workflows-lite/github/workflows/stack-deploy.yml","edition":"lite"}
       - {path: packages/hfs/src/hfs-release-provenance.spec.mjs, edition: lite}
       - {path: packages/hfs/src/hfs-release-provenance.spec.mjs, edition: full}
     witness:
@@ -5979,3 +5979,93 @@ rules:
         source: owner
         quote: "A list inside another surface is outlined (BOUNDARY-5, DNA-COMMON-NO-RAISED-SURFACE-IN-SURFACE); SurfaceListCard takes its depth from the surface context (grammar 0.16.2)."
         ruling: "SurfaceListCard resolves its depth from the surface context like SurfaceCard and SurfaceAccordionCard; an app that forces depth=\"top\" on a surface nested in another surface raises a surface inside a surface, so the lint refuses it."
+  - id: R341
+    code: "FE_FREESTYLE_REASON_MISSING"
+    law: "A Grammar Freestyle region, the one sanctioned place where an app writes its own plain elements and CSS because no Grammar component fits, names its reason: a non-empty string literal saying why. The rules that judge hand-written elements, classes, styles and generated art leave the raw elements of a Freestyle subtree alone; a Grammar component inside it is judged as before. An element with a spread attribute is not judged."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["FE_FREESTYLE_REASON_MISSING"]
+    enforcers:
+      - {kind: eslint-grammar-core, id: freestyle-has-reason}
+    editions: [lite, full]
+    docs: [knowledge/patterns/fe/ui.yaml#FE-UI]
+    templateNa: "A template writes no Freestyle region; the app adds one only when no Grammar component fits."
+    proves:
+      - packages/eslint-grammar-core/src/freestyle.spec.ts
+    exemplifiedBy:
+      - {path: packages/eslint-grammar-core/src/freestyle.spec.ts, editions: [lite, full], codes: [FE_FREESTYLE_REASON_MISSING]}
+    witness:
+      - {path: packages/eslint-grammar-core/src/freestyle.spec.ts, editions: [lite, full], codes: [FE_FREESTYLE_REASON_MISSING]}
+    cases:
+      - id: case-1
+        date: "2026-10-31"
+        source: owner
+        quote: "cái trang này free style đi trò div và làm bth thôi, thêm 1 component Freestyle hoặc tên gì đó tương đương đi trò, ý là cho custom nhưng vẫm bám grammar trừ bất đắc dĩ ntn"
+        ruling: "The Grammar has one sanctioned escape hatch, Freestyle: a region where the app writes its own plain divs and CSS because no Grammar component fits; it names its reason (the lint requires it), and the rest of the page still follows the Grammar."
+  - id: R342
+    code: "BE_ENTITY_EXTENDS_BASE"
+    law: "An @Entity class does not repeat the columns every table shares: a database-set created_at or updated_at (CreateDateColumn, UpdateDateColumn, or a Column on those names, or on createdAt / updatedAt, with insert false, update false or a default) and, beside both, the generated uuid id are inherited from AbstractEntity or UuidAbstractEntity of @modules/platform/database (BE-PERSISTENCE-3, ruling entity-base). The finding names the base to extend: UuidAbstractEntity with the uuid key, AbstractEntity without it. A table whose timestamps the application sets (a plain Column), or that lacks one of them, extends nothing and maps its own; the base file platform/database/abstract.entity.ts is exempt."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["BE_ENTITY_EXTENDS_BASE"]
+    enforcers:
+      - {kind: eslint-be, id: entity-extends-base}
+    editions: [lite, full]
+    docs: [contexts/code/be/persistence.md]
+    proves:
+      - packages/eslint-canon-be/src/entity-base.spec.ts
+    exemplifiedBy:
+      - {path: packages/hfs/templates/be/table/entity.ts.tpl, editions: [lite, full]}
+      - {path: packages/eslint-canon-be/src/entity-base.spec.ts, editions: [lite, full], codes: [BE_ENTITY_EXTENDS_BASE]}
+    witness:
+      - {path: packages/eslint-canon-be/src/entity-base.spec.ts, editions: [lite, full], codes: [BE_ENTITY_EXTENDS_BASE]}
+    cases:
+      - id: case-1
+        date: "2026-10-31"
+        source: owner
+        quote: "Entities do not repeat the columns every table shares; the owner approved a lint so they never repeat them again (ruling entity-base, 2026-10-31)."
+        ruling: "A table whose migration has created_at, updated_at (set by the database) and the generated uuid id maps them by extending AbstractEntity or UuidAbstractEntity from @modules/platform/database; an entity that declares them itself is a finding. A table without them extends nothing."
+  - id: R343
+    code: "HFS_CHECK_CACHE_FORGED"
+    editions: ["lite", "full"]
+    law: "An app's committed check cache (.starcistacks/cache/) is trusted in CI only as it stands at the trusted base; a record whose key matches the tree and whose findings differ from the inherited or computed result is HFS_CHECK_CACHE_FORGED (a hard blocker at any count), a touched key without a current record is HFS_CHECK_CACHE_STALE and a missing cache is HFS_CHECK_CACHE_MISSING (both report-only warnings)."
+    kinds: [codemod]
+    gates: [ci]
+    failureCodes: ["HFS_CHECK_CACHE_FORGED", "HFS_CHECK_CACHE_STALE", "HFS_CHECK_CACHE_MISSING"]
+    enforcers:
+      - {kind: hfs, id: check-cache, at: packages/hfs/cache/trust.mjs}
+    proves:
+      - {path: packages/hfs/src/hfs-check-cache.spec.mjs, editions: [lite, full]}
+    exemplifiedBy:
+      - {path: packages/hfs/src/hfs-check-cache.spec.mjs, editions: [lite, full]}
+    witness:
+      - {path: packages/hfs/src/hfs-check-cache.spec.mjs, editions: [lite, full], codes: [HFS_CHECK_CACHE_FORGED, HFS_CHECK_CACHE_STALE, HFS_CHECK_CACHE_MISSING]}
+    cases:
+      - id: case-1
+        date: "2026-10-31"
+        source: owner
+        quote: "app check cache lại vào file dc không? sau chỉ check diff; chốt starcistacks lưu hết nhé và check diff và triển cho ci và local lun."
+        ruling: "The app commits its check results in .starcistacks/cache/; CI trusts only the cache at the trusted base, a forged record blocks at any count, stale and missing only warn (ruling app-check-cache)."
+  - id: R344
+    code: "BE_AI_VIRTUAL_KEY"
+    law: "An app's ai-router gateway has one client key, STARCI_AI_KEY (sk-starci-<app>-<48 hex>, sealed in the ai member, used by the integrations/ai LangChain client and the agent runtime alike), and no admin token: integrations/ai reads exactly that secret name with env.secret, as a literal, and the custody owner integrations/ai-gateway passes the gateway no adminToken."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["BE_AI_VIRTUAL_KEY"]
+    enforcers:
+      - {kind: eslint-be, id: ai-virtual-key-name}
+    editions: [lite, full]
+    docs: [contexts/code/be/ai.md]
+    templateNa: "The skeleton scaffolds no model call; an app adds the ai and ai-gateway integrations and the ai member when it calls a model."
+    proves:
+      - {path: packages/eslint-canon-be/src/ai-gateway.spec.ts, editions: [lite, full], codes: [BE_AI_VIRTUAL_KEY]}
+    exemplifiedBy:
+      - {path: packages/eslint-canon-be/src/ai-gateway.spec.ts, editions: [lite, full], codes: [BE_AI_VIRTUAL_KEY]}
+    witness:
+      - {path: packages/eslint-canon-be/src/ai-gateway.spec.ts, editions: [lite, full], codes: [BE_AI_VIRTUAL_KEY]}
+    cases:
+      - id: case-1
+        date: "2026-10-31"
+        source: owner
+        quote: "Xóa ai api key và openclaw ai key chỉnh thành starci ai key là key ảo"
+        ruling: "Per app and environment the ai member holds the upstream provider keys and one random virtual key STARCI_AI_KEY that the gateway mounts and every client uses; the gateway has no admin API (ruling be-ai-one-virtual-key)."

package/runtime/knowledge/hfs/slots.yaml

@@ -7,7 +7,7 @@
 # catalog READ this file through scripts/hfs/slots.mjs; none of them hardcodes a path.
 # Shape: modules/schemas/hfs-slots.schema.yaml. The repository side is hfs.json: modules/schemas/hfs-repo.schema.yaml.
 schema: starci/hfs-slots@3
-version: 3.14.0
+version: 3.15.0
 
 versioning:
   # MAJOR.MINOR.PATCH of this manifest. A repository pins only the MAJOR in hfs.json ("hfs": 3).
@@ -58,6 +58,7 @@ versioning:
 # 3.13.0 (rulings lite-pgmq-bus-bullmq-jobs and lite-db-image-in-stacks, 2026-10-29) is a change for lite only: ruleParams.db.extensions
 # admits pgmq, the event bus, ruleParams.db.queueOutbox is retired with the pg_cron half of R258, the lite event-bus functions replace
 # event_bus_write in ruleParams.be.dbFunctions, and app.db.image moves to .starcistacks/images/db/Dockerfile (db/ keeps schema and data).
+# 3.15.0 (ruling app-check-cache, 2026-10-31) adds the optional app.starcistacks.cache, the committed check cache of the app (.starcistacks/cache/, both editions).
 # 3.14.0 (ruling app-secrets-one-standard, 2026-10-29) adds the optional app.ci-stack-key-restore, the managed workflow that writes the
 # deploy server's age identity back from its GitHub Environment backup.
 
@@ -645,7 +646,7 @@ slots:
     since: 3.1.0
     profiles: [app]
     editionWhy: "ruling:R212/case-2 (with the Work boundary amended by ruling:R212/case-4): lite renders its image workflow; full renders images for its separately deployed services."
-    # Builds every image of the app (one matrix entry per declared app, path-filtered), never pushes: rendered by starci app sync.
+    # The reusable workflow ci.yml calls: builds every image of the app once per commit beside the checks, pushes the deployed ones to the registry by sha-<sha> with SBOM and provenance. Rendered by starci app sync.
     path: ".github/workflows/images.yml"
     presence: required
     tracked: tracked
@@ -657,23 +658,23 @@ slots:
   - id: app.ci-db
     profiles: [app]
     exemplifiedBy:
-      - packages/hfs/templates/app/ci-workflows-lite/github/workflows/db-deploy.yml
       - {path: packages/hfs/src/hfs-release-provenance.spec.mjs, edition: full}
-    editionWhy: "ruling:R212/case-2 (with the Work boundary amended by ruling:R212/case-4): lite manages its database deploy workflow; full owns an optional provider-specific workflow."
-    # The database deploy workflow: workflow_dispatch only (like app.ci-e2e); starci app sync renders it under the managed ci group.
+    editionWhy: "ruling:app-cicd-auto-deploy: a lite app migrates in the migrate phase of its stack deploy, so its database deploy workflow is retired (starci app sync --execute removes it); full owns an optional provider-specific workflow."
+    # The database deploy workflow: workflow_dispatch only (like app.ci-e2e). A lite app has none: the stack deploy backs up and migrates inside the database container.
     path: ".github/workflows/db-deploy.yml"
     presence: optional
+    litePresence: forbidden     # ruling:app-cicd-auto-deploy: retired in lite; migrations are the deploy's migrate phase
     tracked: tracked
     tier: none
     tests: none
-    liteManagedBy: ci-workflows-lite
+    goesTo: "the stack deploy: starci app stack deploy takes a verified backup, applies the expand migrations before the services update and the contract migrations after the accept (a full app keeps its own optional workflow)"
     rules: [HFS_MANAGED_FILE_DRIFT]
     since: 2.1.0
   - id: app.ci-stack-deploy
     since: 3.3.0
     profiles: [app]
     editionWhy: "ruling:R212/case-2 (with the Work boundary amended by ruling:R212/case-4): both editions deploy their images to a Docker Swarm stack through the same starci stack verbs; the workflow lists the images the app declares."
-    # The Swarm stack deploy workflow: workflow_dispatch only (like app.ci-db); a thin file that calls `starci app stack`, rendered by starci app sync.
+    # The Swarm stack deploy workflow: reusable (ci.yml calls it after the verdict for every environment with deploy.auto) and workflow_dispatch for the owner's manual operations; a thin file that calls `starci app stack`, rendered by starci app sync.
     path: ".github/workflows/stack-deploy.yml"
     presence: optional
     tracked: tracked
@@ -1023,6 +1024,17 @@ slots:
     tests: none
     since: 3.11.0
     rules: [HFS_MANAGED_FILE_DRIFT]
+  - id: app.starcistacks.cache
+    profiles: [app]
+    # The committed result cache of `starci app check` and `starci app lint` (ruling app-check-cache, contexts/project/check-cache.md): JSON Lines records keyed by
+    # content, one folder per family. App-owned and written only by the CLI; sync never renders, overwrites or judges it. Both editions.
+    path: ".starcistacks/cache/"
+    presence: optional
+    tracked: tracked
+    tier: none
+    tests: none
+    since: 3.15.0
+    allows: ["fingerprint.jsonl", "check/**", "lint/**", "test-coverage/**", "sonar-baseline/**", "codecov-baseline/**"]
   - id: app.db.bootstrap
     profiles: [app]
     editions: [lite]
@@ -1987,7 +1999,7 @@ slots:
     tests: unit-beside            # <name>.service.spec.ts beside each <name>.service.ts; plus src/tests/integration/<provider>/ (R112)
     coverage: required
     budget: {indexExports: 80}   # a provider's port surface includes clients, config, options, tokens and errors
-    rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT, BE_INTEGRATION_SPEC_MISSING, BE_AI_KEY_CUSTODY, BE_AI_GATEWAY_CLIENT]
+    rules: [BE_TIER_DIRECTION, BE_ERROR_HOME, BE_SECRET_DEFAULT, BE_INTEGRATION_SPEC_MISSING, BE_AI_KEY_CUSTODY, BE_AI_GATEWAY_CLIENT, BE_AI_VIRTUAL_KEY]
   - id: be.integrations.model
     since: 3.1.0
     profiles: [be]