@starci/hfs 4.11.21 → 4.12.0

package/runtime/knowledge/hfs/rules.yaml

@@ -19,7 +19,7 @@
 schema: starci/hfs-rules@3
 version: 3.1.0
 gates:
-  pre-commit: the managed L0 hook runs app hygiene, managed-file drift, ESLint per side and stylelint on staged source, and prettier on staged files; typecheck and targeted specs belong to the op gate under R225
+  pre-commit: the managed L0 hook runs app check --staged, managed-file drift, ESLint per side and stylelint on staged source, and prettier on staged files; typecheck and targeted specs belong to the op gate under R225
   pre-push: the managed app hook invokes the bundled push policy under R225; it starts no source check, build or test
   settle: the op gate `starci gate run` over the op's changed files (merge guard, starci app lint --changed, codegen, tsc, the slice's specs; only findings new against the workflow's previous checkpoint block), re-read at starci kernel settle, which refuses a red done; a green settle commits the op's checkpoint on wf-<workflowId>
   land: the workflow's finish, the only time main is touched - gate.mjs over the whole workflow branch against its merge-base with main, the merge guard, review.verify of the exact head that lands, the branch rebased onto main, then main fast-forwarded and pushed
@@ -918,7 +918,7 @@ rules:
     code: "BE_TEST_TOPOLOGY"
     editions: [lite, full]
     docs: [docs/quality-bar.md#r47-test-topology]
-    law: "One jest config, projects `unit`, `integration`, `e2e` and `contract`, live by folder, `diagnostics: false`; unit specs are `<name>.<role>.spec.ts` beside the file they test: required for the roles of `ruleParams.be.unitRoles` (`<name>.service.spec.ts` beside a `<name>.service.ts`, `<name>.cli.spec.ts` beside a cli command `<name>.cli.ts` of `src/features/cli`), optional for any other logic role (`ruleParams.be.logicRoles`) inside a slot whose `coverage` is required and beside a logic file such a slot declares (`logic`: `passport.tokens.spec.ts` beside `passport.tokens.ts`), except that the commit adding a measured logic file stages its `<name>.<role>.spec.ts` beside it (owner 2026-10-20, judged by `starci app hygiene` in the pre-commit hook), and nowhere else but beside a webhook or realtime door that has no service of its own (`<provider>.webhook.spec.ts`, `<channel>.gateway.spec.ts`, `<x>.subscription.spec.ts`) (every unit-tested subject has exactly one; any other `*.spec.ts` outside `be/src/tests/{world,integration,e2e,contract}` is a finding, including specs in apps), and the unit project collects coverage from the logic roles of the measured roots and the logic files their slots declare only (the scope derived from the slot manifest, R204) with a per-file threshold of 100 on lines, branches, functions and statements (`test` runs `--coverage`; `importHelpers` and `tslib`); `be/src/tests/world/` is the ONLY test infrastructure: `global-setup.ts` starts the app's own stack (`.starcistacks/<env>`, named by `stack` in `test-world.config.ts`, the declaration of the test-world library in its one named form `export const { useTestWorld, useSandbox } = defineTestWorld({...})` (a default export is not read): every service it declares runs REAL, behind toxiproxy, images and versions read from the stack at run time, never spelled in test source) or attaches to a warm one that answers, and runs the migrations once over the cli app's connections (the runner of the cli migrate command); `global-teardown.ts` stops only what its setup started; `use-test-world.ts` exports `useTestWorld({ apps } | { modules })` (`world.apps.<name>.api`, `world.db.<connection>`, `world.infra.<service>` with `latency(ms)`, `cut()` and `restore()` on the real service, `world.fake.<provider>`, `world.waitFor`) and `fakes/<provider>/` holds the network-edge fakes (`failNext`, `replayWebhook`, `delay`, payload fixtures) of external SaaS the team does not operate ONLY: a fake of a service the stack declares is refused, except stateless compute that needs special hardware or an external model (GPU inference, a self-hosted embedding model), whose `stacks` entry in `test-world.config.ts` declares `{ fakedBy: <fake>, reason }` with a non-empty `reason` (a stateful service, or one with a persistent volume, is never accepted); it alone owns containers, DataSource, migrations and `process.env`; nothing under `be/src/tests` overrides a provider or DI token; `be/src/tests/integration/<capability>/*.integration-spec.ts` (`{ modules }`, with the real peer apps its client calls beside them as `apps`; real infrastructure, no HTTP door of ours), `be/src/tests/e2e/<area>/*.e2e-spec.ts` (`{ apps }`) and `be/src/tests/contract/<provider>/*.contract-spec.ts` (provider sandboxes, skipped without sandbox config, run only by `test:contract`, never by `test` or `test:e2e`) agree folder with suffix; an integration or e2e spec passes `useTestWorld` one object literal with plain keys (no variable, spread or computed key) and calls it; the contract layer has no skip either: a contract spec writes `sandbox.describe(...)` from the test-world library's `useSandbox(...)`, and when the sandbox config is absent that describe registers one failing test naming the missing keys (the body never runs), and every `fakes/<provider>/` that serves payload fixtures (`payloads/*.json`) has a `contract/<provider>/*.contract-spec.ts` that references those fixtures and asserts `shapeOf(real)` equals `shapeOf(fixture)` (the helper `shapeOf` is named by `ruleParams.be.contractShape` of the slot manifest; fakes the test-world library provides are guarded by the library); no `.test.ts`, `int-spec` or `harness-spec`, no `live/` and no `be/src/tests/e2e/world`."
+    law: "One jest config, projects `unit`, `integration`, `e2e` and `contract`, live by folder, `diagnostics: false`; unit specs are `<name>.<role>.spec.ts` beside the file they test: required for the roles of `ruleParams.be.unitRoles` (`<name>.service.spec.ts` beside a `<name>.service.ts`, `<name>.cli.spec.ts` beside a cli command `<name>.cli.ts` of `src/features/cli`), optional for any other logic role (`ruleParams.be.logicRoles`) inside a slot whose `coverage` is required and beside a logic file such a slot declares (`logic`: `passport.tokens.spec.ts` beside `passport.tokens.ts`), except that the commit adding a measured logic file stages its `<name>.<role>.spec.ts` beside it (owner 2026-10-20, judged by `starci app check --staged` in the pre-commit hook), and nowhere else but beside a webhook or realtime door that has no service of its own (`<provider>.webhook.spec.ts`, `<channel>.gateway.spec.ts`, `<x>.subscription.spec.ts`) (every unit-tested subject has exactly one; any other `*.spec.ts` outside `be/src/tests/{world,integration,e2e,contract}` is a finding, including specs in apps), and the unit project collects coverage from the logic roles of the measured roots and the logic files their slots declare only (the scope derived from the slot manifest, R204) with a per-file threshold of 100 on lines, branches, functions and statements (`test` runs `--coverage`; `importHelpers` and `tslib`); `be/src/tests/world/` is the ONLY test infrastructure: `global-setup.ts` starts the app's own stack (`.starcistacks/<env>`, named by `stack` in `test-world.config.ts`, the declaration of the test-world library in its one named form `export const { useTestWorld, useSandbox } = defineTestWorld({...})` (a default export is not read): every service it declares runs REAL, behind toxiproxy, images and versions read from the stack at run time, never spelled in test source) or attaches to a warm one that answers, and runs the migrations once over the cli app's connections (the runner of the cli migrate command); `global-teardown.ts` stops only what its setup started; `use-test-world.ts` exports `useTestWorld({ apps } | { modules })` (`world.apps.<name>.api`, `world.db.<connection>`, `world.infra.<service>` with `latency(ms)`, `cut()` and `restore()` on the real service, `world.fake.<provider>`, `world.waitFor`) and `fakes/<provider>/` holds the network-edge fakes (`failNext`, `replayWebhook`, `delay`, payload fixtures) of external SaaS the team does not operate ONLY: a fake of a service the stack declares is refused, except stateless compute that needs special hardware or an external model (GPU inference, a self-hosted embedding model), whose `stacks` entry in `test-world.config.ts` declares `{ fakedBy: <fake>, reason }` with a non-empty `reason` (a stateful service, or one with a persistent volume, is never accepted); it alone owns containers, DataSource, migrations and `process.env`; nothing under `be/src/tests` overrides a provider or DI token; `be/src/tests/integration/<capability>/*.integration-spec.ts` (`{ modules }`, with the real peer apps its client calls beside them as `apps`; real infrastructure, no HTTP door of ours), `be/src/tests/e2e/<area>/*.e2e-spec.ts` (`{ apps }`) and `be/src/tests/contract/<provider>/*.contract-spec.ts` (provider sandboxes, skipped without sandbox config, run only by `test:contract`, never by `test` or `test:e2e`) agree folder with suffix; an integration or e2e spec passes `useTestWorld` one object literal with plain keys (no variable, spread or computed key) and calls it; the contract layer has no skip either: a contract spec writes `sandbox.describe(...)` from the test-world library's `useSandbox(...)`, and when the sandbox config is absent that describe registers one failing test naming the missing keys (the body never runs), and every `fakes/<provider>/` that serves payload fixtures (`payloads/*.json`) has a `contract/<provider>/*.contract-spec.ts` that references those fixtures and asserts `shapeOf(real)` equals `shapeOf(fixture)` (the helper `shapeOf` is named by `ruleParams.be.contractShape` of the slot manifest; fakes the test-world library provides are guarded by the library); no `.test.ts`, `int-spec` or `harness-spec`, no `live/` and no `be/src/tests/e2e/world`."
     kinds: [check, codemod, lint]
     gates: [land, ci]
     failureCodes: ["BE_TEST_TOPOLOGY", "BE_CONTRACT_UNGUARDED", "BE_UNIT_SPEC_NOT_STAGED"]
@@ -3619,7 +3619,7 @@ rules:
     docs: [docs/lite-edition.md#edition-validation]
     templateNa: "The hfs.json edition declaration is generated programmatically by packages/hfs/scaffold/app.mjs; no managed declaration template exists. Forbidden paths are rejected rather than scaffolded."
     code: "HFS_EDITION_INVALID"
-    law: "hfs.json names an edition the manifest knows (full, or lite; absent means full). Lite is a minimal production (case-10): the same monorepo, code structure, slots, patterns and back-end unit specs, one stateless instance type that scales horizontally, its own PostgreSQL db service, Passport identity and S3-compatible storage (ruling:lite-self-hosted-postgres-passport-minio), and one minimal instance of each backing service a declared capability needs (hfs.json sides.be.backing: Redis for the queue, with AOF persistence); vector search uses pgvector in the db service (owner:lite-vector-is-pgvector, which excludes Qdrant from lite); a backing service is declared or absent, never on by default. The queue is BullMQ on Redis in both editions, fed by the Postgres outbox; pg_cron ticks enqueue through that outbox; the event bus keeps its lite adapter (pgmq-backed topics or in-process delivery) because full's event bus is Kafka, not Redis; cache and locks are Postgres unless Redis is declared; the api and sidecars run on docker-swarm on a VPS. The realtime pattern serves SSE (the default for one-way push), the same socket.io gateway or the restricted GraphQL subscription inside the be api process (scales horizontally and stateless: the memory hub is for a single replica or tests only, and replicas > 1 use the Redis hub and the sharded @socket.io/redis-adapter when Redis is declared, else the Postgres hub and @socket.io/postgres-adapter; both shared socket adapters force websocket-only connections with no sticky sessions; R212 case-9, which amends the realtime clauses of case-2, case-3 and case-5; the GraphQL subscription door is R212 case-7 and owner:lite-graphql-subscription-door), and both editions share knowledge/hfs/fe-stack.yaml. Lite requires application-stacks.yaml and permits environment metadata, runbooks, infra/swarm and encrypted-secret custody, while refusing infra/compose, infra/k8s, infra/terraform and backing components other than its db service (runtime/{config,env}, seeds and the sealed secrets of its environments are allowed). Contract specs and `test:contract` are allowed (owner 2026-10-14); it has no e2e spec, `test:e2e`, `test:stack` or `test:browser` script, e2e workflow, browser journey, Work catalog, shell, features, resources, UAT or br records, test container, toxiproxy, browser-runner or Kafka dependency, client library of an undeclared backing service (HFS_BACKING_UNDECLARED), declared backing service without a consumer (HFS_BACKING_UNUSED), or a supabase/ tree (LITE_DB_MIGRATION). Its .starciwork is optional and admits only .gitignore, workspace.yaml and brand/**; workspace.yaml is optional and carries project identity and repo roles for the Work tools."
+    law: "hfs.json names an edition the manifest knows (full, or lite; absent means full). Lite is a minimal production (case-10): the same monorepo, code structure, slots, patterns and back-end unit specs, one stateless instance type that scales horizontally, its own PostgreSQL db service, Passport identity and S3-compatible storage (ruling:lite-self-hosted-postgres-passport-minio), and one minimal instance of each backing service a declared capability needs (hfs.json sides.be.backing: Redis for the queue, with AOF persistence); vector search uses pgvector in the db service (owner:lite-vector-is-pgvector, which excludes Qdrant from lite); a backing service is declared or absent, never on by default. The queue is BullMQ on Redis in both editions, fed by the Postgres outbox; pg_cron ticks enqueue through that outbox; the event bus keeps its lite adapter (pgmq-backed topics or in-process delivery) because full's event bus is Kafka, not Redis; cache and locks are Postgres unless Redis is declared; the api and sidecars run on docker-swarm on a VPS. The realtime pattern serves SSE (the default for one-way push), the same socket.io gateway or the restricted GraphQL subscription inside the be api process (scales horizontally and stateless: the memory hub is for a single replica or tests only, and replicas > 1 use the Redis hub and the sharded @socket.io/redis-adapter when Redis is declared, else the Postgres hub and @socket.io/postgres-adapter; both shared socket adapters force websocket-only connections with no sticky sessions; R212 case-9, which amends the realtime clauses of case-2, case-3 and case-5; the GraphQL subscription door is R212 case-7 and owner:lite-graphql-subscription-door), and both editions share knowledge/hfs/fe-stack.yaml. Lite requires application-stacks.yaml and permits environment metadata, runbooks, infra/swarm and encrypted-secret custody, while refusing infra/compose, infra/k8s, infra/terraform and backing components other than its db service (runtime/{config,env}, seeds and the sealed secrets of its environments are allowed). Contract specs and `test:contract` are allowed (owner 2026-10-14); it has no e2e spec, `test:e2e`, `test:world` or `test:browser` script, e2e workflow, browser journey, Work catalog, shell, features, resources, UAT or br records, test container, toxiproxy, browser-runner or Kafka dependency, client library of an undeclared backing service (HFS_BACKING_UNDECLARED), declared backing service without a consumer (HFS_BACKING_UNUSED), or a supabase/ tree (LITE_DB_MIGRATION). Its .starciwork is optional and admits only .gitignore, workspace.yaml and brand/**; workspace.yaml is optional and carries project identity and repo roles for the Work tools."
     kinds: [check]
     gates: [settle, land, ci]
     failureCodes: ["HFS_EDITION_INVALID", "HFS_EDITION_FORBIDDEN_PRESENT", "HFS_STARCIWORK_LITE_FORBIDDEN", "HFS_BACKING_UNDECLARED", "HFS_BACKING_UNUSED"]
@@ -4157,7 +4157,7 @@ rules:
     code: "ENV_VALUE_SHAPE"
     editions: [lite, full]
     docs: [docs/host-secrets.md#r249]
-    law: "A stored environment value parses as the type its `EnvSource` reader declares (an integer, `true`/`false`, an absolute URL, a duration `250`/`30s`/`5m`/`2h`, a member of the declared enum, a nonempty string or secret): `starci app secret verify <env>` decrypts every member in memory and reports each key and its violated shape, never a value, and a concrete (non-placeholder) value of a `*.env.example` parses the same way."
+    law: "A stored environment value parses as the type its `EnvSource` reader declares (an integer, `true`/`false`, an absolute URL, a duration `250`/`30s`/`5m`/`2h`, a member of the declared enum, a nonempty string or secret): `starci app secret verify --env <env>` decrypts every member in memory and reports each key and its violated shape, never a value, and a concrete (non-placeholder) value of a `*.env.example` parses the same way."
     kinds: [check]
     gates: [settle, land, ci]
     failureCodes: ["ENV_VALUE_SHAPE"]
@@ -5242,7 +5242,7 @@ rules:
       - {path: packages/hfs/src/mcp-tools-snapshot.spec.mjs, editions: [lite, full], codes: [HFS_MCP_TOOLS_SNAPSHOT]}
   - id: R303
     code: "HFS_BYPASS_MARKER"
-    law: "A product repository holds no bypass of a check (owner ruling loosening-always-red): no inline disable of any tool (eslint, stylelint, tslint, prettier, biome), no ts-ignore, ts-expect-error or ts-nocheck directive, no Sonar exclusion comment, no istanbul, c8 or v8 coverage ignore, no skipped, focused or todo test or skip option, and no failure swallowed in a hook, script or workflow (`|| true`, `; true`, `continue-on-error`, `set +e`, `HUSKY=0`, `--no-verify`, `fail_ci_if_error: false`, `--passWithNoTests`, `--coverageThreshold`, `--no-error-on-unmatched-pattern`, a `--max-warnings` budget). A marker is read where it acts: a suppression word opens a comment, a test marker stands in code, a swallowed failure stands in a shell line or in the string a script hands a shell; the same words quoted as data are no bypass. The runtime tree is judged by the same library (R236). A front end has no specs, but its source is still judged for the inline disables. `starci app check` reads the tracked tree and `starci app hygiene` (the managed pre-commit hook) the staged files from the index, so the bypass fails at the commit."
+    law: "A product repository holds no bypass of a check (owner ruling loosening-always-red): no inline disable of any tool (eslint, stylelint, tslint, prettier, biome), no ts-ignore, ts-expect-error or ts-nocheck directive, no Sonar exclusion comment, no istanbul, c8 or v8 coverage ignore, no skipped, focused or todo test or skip option, and no failure swallowed in a hook, script or workflow (`|| true`, `; true`, `continue-on-error`, `set +e`, `HUSKY=0`, `--no-verify`, `fail_ci_if_error: false`, `--passWithNoTests`, `--coverageThreshold`, `--no-error-on-unmatched-pattern`, a `--max-warnings` budget). A marker is read where it acts: a suppression word opens a comment, a test marker stands in code, a swallowed failure stands in a shell line or in the string a script hands a shell; the same words quoted as data are no bypass. The runtime tree is judged by the same library (R236). A front end has no specs, but its source is still judged for the inline disables. `starci app check` reads the tracked tree and `starci app check --staged` (the managed pre-commit hook) the staged files from the index, so the bypass fails at the commit."
     kinds: [check]
     gates: [pre-commit, land, ci]
     failureCodes: ["HFS_BYPASS_MARKER"]
@@ -5803,7 +5803,7 @@ rules:
         ruling: "The lite database is self-hosted PostgreSQL in the app stack; its migrations live in db/migrations and starci app db migrate applies them."
   - id: R333
     code: "BE_ENTITY_SCHEMA_DRIFT"
-    law: "Every TypeORM entity column of an app's entity list (be/src/modules/platform/database/entities.ts) matches the schema its SQL migrations build: `starci app db drift` applies db/bootstrap.sql and every active db/migrations/*.sql to a scratch database (a container of the app's db image, or the empty database --url-env names), reads information_schema.columns and pg_catalog, and refuses a missing table, a missing column, a type that differs once both are normalised to PostgreSQL's format_type names (an enum by its type name), and a nullability that differs. A database column no entity maps is fine. A host that cannot provide the scratch database gets no verdict (exit 2, needs a database), never a green."
+    law: "Every TypeORM entity column of an app's entity list (be/src/modules/platform/database/entities.ts) matches the schema its SQL migrations build: `starci app db drift` applies db/bootstrap.sql and every active db/migrations/*.sql to a scratch database (a container of the app's db image, or the empty database --db-url-env names), reads information_schema.columns and pg_catalog, and refuses a missing table, a missing column, a type that differs once both are normalised to PostgreSQL's format_type names (an enum by its type name), and a nullability that differs. A database column no entity maps is fine. A host that cannot provide the scratch database gets no verdict (exit 2, needs a database), never a green."
     kinds: [check]
     gates: [ci]
     failureCodes: ["BE_ENTITY_SCHEMA_DRIFT"]
@@ -5890,3 +5890,69 @@ rules:
       - {path: packages/eslint-canon-be/src/event-bus-lite.spec.ts, edition: lite, codes: [BE_EVENT_BUS_LITE_SHAPE]}
     witness:
       - {path: packages/eslint-canon-be/src/event-bus-lite.spec.ts, edition: lite, codes: [BE_EVENT_BUS_LITE_SHAPE]}
+  - id: R337
+    code: "HFS_AUTH_COOKIE_DOMAIN_MISSING"
+    law: "In a lite app whose api uses the skeleton's passport (a tracked src/modules/integrations/passport/passport.config.ts), a docker-swarm environment whose rendered stack serves the web and the api on different hosts gives the api an AUTH_COOKIE_DOMAIN: a declared value in services.api.environment, a row of the environment's runtime/env/KEYS.md or a key sealed under its secrets/. Otherwise the refresh cookie is host-only on the api host, is absent from the Cookie header the web server forwards to the api, the api refuses the session and the user loops back to sign-in. The hosts are read from the rendered stack (web: NEXT_PUBLIC_SITE_URL, AUTH_WEB_ORIGIN, deploy.verify.http, HTTP_SECURITY_ALLOWED_ORIGINS; api: AUTH_JWT_ISSUER, GOOGLE_CALLBACK_URL, NEXT_PUBLIC_API_URL, deploy.verify.http), ports ignored, an unknown host is not judged. The finding names both hosts and their common parent domain as the value to set. A declared AUTH_COOKIE_DOMAIN that is not a bare domain (no scheme, port, path, leading dot or IP) or is not a parent of the web and the api hosts is a finding too. Same host: no key is required."
+    kinds: [check]
+    gates: [settle, land, ci]
+    failureCodes: ["HFS_AUTH_COOKIE_DOMAIN_MISSING"]
+    enforcers:
+      - {kind: hfs, id: stacks-auth-cookie-domain, at: scripts/hfs/rules/stacks-auth-cookie-domain.mjs}
+    editions: [lite]
+    docs:
+      - contexts/project/stacks.md
+    proves:
+      - {path: packages/hfs/src/hfs-stacks-auth-cookie-domain.spec.mjs, edition: lite}
+    exemplifiedBy:
+      - {path: packages/hfs/templates/app/skeleton-lite/.starcistacks, edition: lite}
+      - {path: packages/hfs/templates/be/skeleton-lite/src/modules/integrations/passport/passport.config.ts, edition: lite}
+      - {path: packages/hfs/src/hfs-stacks-auth-cookie-domain.spec.mjs, edition: lite}
+    witness:
+      - {path: packages/hfs/src/hfs-stacks-auth-cookie-domain.spec.mjs, edition: lite}
+
+  - id: R338
+    code: "FE_GENERATED_ART_OUTSIDE_FRAME"
+    law: "Generated art, a .webp or .png under the public /images/ tree, renders only through Grammar's Mascot (the character size scale sm, md, lg, hero) or inside a MediaFrame; a bare Image, img or other src-taking element drawing it takes whatever box its page gives, so the same art comes out at a different size on every screen."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["FE_GENERATED_ART_OUTSIDE_FRAME"]
+    enforcers:
+      - {kind: eslint-grammar-core, id: generated-art-in-mascot-or-media-frame}
+    editions: [lite, full]
+    docs: [knowledge/patterns/fe/ui.yaml#FE-UI]
+    templateNa: "A template draws no generated art; the art is the app's."
+    proves:
+      - packages/eslint-grammar-core/src/mascot.spec.ts
+    exemplifiedBy:
+      - {path: packages/eslint-grammar-core/src/mascot.spec.ts, editions: [lite, full], codes: [FE_GENERATED_ART_OUTSIDE_FRAME]}
+    witness:
+      - {path: packages/eslint-grammar-core/src/mascot.spec.ts, editions: [lite, full], codes: [FE_GENERATED_ART_OUTSIDE_FRAME]}
+    cases:
+      - id: case-1
+        date: "2026-10-30"
+        source: owner
+        quote: "Generated art renders at one consistent size across screens (relayed by the nivo-lite app)."
+        ruling: "Grammar's Mascot owns the character size scale (sm 96px, md 160px, lg 240px, hero up to its cap), always contained on a transparent ground; generated art under /images/ renders through Mascot or inside MediaFrame, never a bare Image."
+  - id: R339
+    code: "FE_MASCOT_ASSET_SLOT_MISSING"
+    law: "Every Grammar Mascot names its assetSlot (a non-empty value), tying the rendered art to the asset workflow's request; an element with a spread attribute is not judged."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["FE_MASCOT_ASSET_SLOT_MISSING"]
+    enforcers:
+      - {kind: eslint-grammar-core, id: mascot-asset-slot-required}
+    editions: [lite, full]
+    docs: [knowledge/patterns/fe/ui.yaml#FE-UI]
+    templateNa: "A template draws no mascot; the art is the app's."
+    proves:
+      - packages/eslint-grammar-core/src/mascot.spec.ts
+    exemplifiedBy:
+      - {path: packages/eslint-grammar-core/src/mascot.spec.ts, editions: [lite, full], codes: [FE_MASCOT_ASSET_SLOT_MISSING]}
+    witness:
+      - {path: packages/eslint-grammar-core/src/mascot.spec.ts, editions: [lite, full], codes: [FE_MASCOT_ASSET_SLOT_MISSING]}
+    cases:
+      - id: case-1
+        date: "2026-10-30"
+        source: owner
+        quote: "A Mascot reuses the provenance props of Image and MediaFrame; a Mascot without an assetSlot is a finding (relayed by the nivo-lite app)."
+        ruling: "Mascot takes AssetSlotProps (assetSlot, assetSha256, assetPrompt) and emits them as data-asset-* on its root; the lint requires assetSlot on every Mascot."

package/runtime/knowledge/hfs/slots.yaml

@@ -53,7 +53,7 @@ versioning:
 # 3.10.0 is a minor (2026-10-29): it ADDS the lite be.platform.database.entities slot, the entity registry (slot fields role and importedBy), so the
 # tier matrix and the public-entry rules admit exactly its <c>Entities imports and its deep importers (persistence.md BE-PERSISTENCE-3).
 # 3.11.0 (ruling:lite-official-postgres-image, 2026-10-29) is, like 3.9.0, a change for lite only: it ADDS the managed app.db.image slot
-# (db/Dockerfile, written by `starci app sync --write`), narrows ruleParams.db.extensions to the extensions that image carries, and gives
+# (db/Dockerfile, written by `starci app sync --execute`), narrows ruleParams.db.extensions to the extensions that image carries, and gives
 # @nestjs/schedule and cron one owner, platform/jobs (R335).
 # 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
@@ -686,7 +686,7 @@ slots:
     since: 3.14.0
     profiles: [app]
     editionWhy: "ruling:app-secrets-one-standard: both editions deploy to a Docker Swarm server whose own age identity the owner backs up as a protected GitHub Environment secret; this workflow writes it back."
-    # The server identity restore workflow: workflow_dispatch only (like app.ci-stack-deploy); `starci app secret server-key <env> --restore github` dispatches it, rendered by starci app sync.
+    # The server identity restore workflow: workflow_dispatch only (like app.ci-stack-deploy); `starci app secret server-key --env <env> --restore github` dispatches it, rendered by starci app sync.
     path: ".github/workflows/stack-key-restore.yml"
     presence: optional
     tracked: tracked
@@ -959,7 +959,7 @@ slots:
 
   # ----- app root: the database of a lite app (ruling:lite-self-hosted-postgres-passport-minio): a self-hosted PostgreSQL in the app's
   # stack (the `db` service, built from the managed .starcistacks/images/db/Dockerfile: the official postgres image plus pgvector and pgmq, ruling:lite-db-image-in-stacks), migrated by
-  # `starci app db migrate --url-env <NAME>`. A full app keeps its TypeORM migrations under be/ and has no such folder.
+  # `starci app db migrate --db-url-env <NAME>`. A full app keeps its TypeORM migrations under be/ and has no such folder.
   - id: app.db
     profiles: [app]
     editions: [lite]

package/runtime/knowledge/sonar-gate.yaml

@@ -41,7 +41,7 @@ newCode:
     minReviewedPercent: 100
     unreviewedMax: 0
 # The whole code, not only the new code. Every finding of the HFS canon reaches Sonar through ONE entry, `starci app lint`
-# (packages/hfs, contract changes hfs-sonar-import and hfs-lint-entry). CI runs it per side with --side and --sonar,
+# (packages/hfs, contract changes hfs-sonar-import and hfs-lint-entry). CI runs it per side with --side and --out,
 # then merges rules by id and joins issues into ONE file, reports/lint.sonar.json, named by sonar.externalIssuesReportPaths; the gate holds the open-issue count of
 # the whole project at zero. The file carries three engines:
 #   starci-hfs   the repository findings of `starci app check` (managed files, tree, pins, CI, contracts; the rule id is the finding code)

package/runtime/modules/kernel/failure-codes.yaml

@@ -96,7 +96,7 @@ ARCH_KNOWLEDGE_UNAVAILABLE:
   meaning_vi: "Bộ kiểm kiến trúc cần một tệp tri thức đi kèm (danh sách tệp gốc do framework ghim) nhưng không đọc được hoặc sai khuôn, nên không phán xét bằng hợp đồng khác."
   causes_vi:
     - "Bản đóng gói của `hfs` thiếu hoặc hỏng tệp tri thức, hoặc tệp tri thức trong runtime bị sửa sai khuôn."
-  nextStep_vi: "Cài lại `@starci/hfs` đúng phiên bản đã ghim; nếu là runtime thì sửa tệp tri thức rồi chạy `starci release sync-runtime`."
+  nextStep_vi: "Cài lại `@starci/hfs` đúng phiên bản đã ghim; tri thức đi kèm gói, nên `npm ci` ở gốc app cài lại đúng bản."
   owner: runtime-core
   kind: check-finding
 
@@ -217,8 +217,8 @@ ARCH_TYPESCRIPT_MISSING:
   title_vi: "Kho được kiểm chưa cài TypeScript"
   meaning_vi: "Bộ kiểm kiến trúc chỉ dùng TypeScript cài trong chính kho được kiểm, không thay bằng bộ phân tích khác, nên không kiểm được."
   causes_vi:
-    - "Kho thiếu `package.json` hoặc chưa chạy `starci npm ci` nên `node_modules/typescript` không có."
-  nextStep_vi: "Chạy `starci npm ci` trong kho rồi chạy lại `starci app check`."
+    - "Kho thiếu `package.json` hoặc chưa chạy `npm ci` nên `node_modules/typescript` không có."
+  nextStep_vi: "Chạy `npm ci` trong kho rồi chạy lại `starci app check`."
   owner: op-retry
   kind: check-finding
 
@@ -1550,7 +1550,7 @@ BE_TEST_TOPOLOGY:
   title_vi: "Cấu hình test lệch chuẩn"
   meaning_vi: "Cấu hình test lệch chuẩn: `<detail>`."
   causes_vi:
-    - "Vi phạm luật R47: một `jest.config.js` (preset `@starci/jest-preset`) với bốn project `unit`, `integration`, `e2e`, `contract`; thư mục và hậu tố spec luôn khớp nhau; `diagnostics: false` + `isolatedModules: true`; `test:integration`, `test:e2e`, `test:contract` chạy qua `starci gate run --root <app> --tests <tên>`; `src/tests/world/` là nơi duy nhất dựng hạ tầng test và chỉ chứa `global-setup.ts`, `global-teardown.ts`, `use-test-world.ts`, `fakes/` và file gốc có hậu tố vai trò (kể cả `test-world.config.ts`)."
+    - "Vi phạm luật R47: một `jest.config.js` (preset `@starci/jest-preset`) với bốn project `unit`, `integration`, `e2e`, `contract`; thư mục và hậu tố spec luôn khớp nhau; `diagnostics: false` + `isolatedModules: true`; `test:integration`, `test:e2e`, `test:contract` là script npm của app (`npm run test:integration`); `src/tests/world/` là nơi duy nhất dựng hạ tầng test và chỉ chứa `global-setup.ts`, `global-teardown.ts`, `use-test-world.ts`, `fakes/` và file gốc có hậu tố vai trò (kể cả `test-world.config.ts`)."
     - "Vi phạm luật R47 về stack thật: mọi dịch vụ khai trong `.starcistacks/<env>` (Postgres, Redis, Keycloak, mail host, k3s...) chạy THẬT trong world qua toxiproxy, world đọc dịch vụ và phiên bản image từ stack lúc chạy; `fakes/<provider>/` chỉ giả SaaS bên ngoài mà đội không vận hành. Ngoại lệ duy nhất: dịch vụ stateless cần phần cứng đặc biệt hoặc model bên ngoài (GPU inference, embedding tự host) được giả khi mục `stacks` của dịch vụ đó trong `test-world.config.ts` khai `{ fakedBy, reason }` với `reason` không rỗng; dịch vụ có trạng thái (database, cache, identity, storage, mail, queue, search hoặc có volume bền) không bao giờ được giả, và mục `fakedBy` trỏ tới dịch vụ hoặc fake (mục `fakes` hay thư mục `fakes/`) không tồn tại bị coi là cũ. `test-world.config.ts` khai world theo đúng một dạng export có tên `export const { useTestWorld, useSandbox } = defineTestWorld({...})` (`stack`, `stacks` theo từng dịch vụ, `fakes`); export default không được đọc và bị báo lỗi."
   nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra (nợ hàng loạt có codemod của HFS); không cần ai can thiệp thêm."
   owner: op-retry
@@ -1628,9 +1628,9 @@ BE_UNIT_SPEC_NOT_STAGED:
   title_vi: "Tệp logic back-end mới được commit mà không có unit spec"
   meaning_vi: "Commit thêm `<file>`, một tệp `<name>.<role>.ts` có vai trò logic mà unit coverage đo ở mức 100 mỗi tệp, nhưng index không có `<name>.<role>.spec.ts` bên cạnh nó: mã được viết trước, spec để sau. Tệp chỉ có hằng số và kiểu (không có hàm, phương thức nào để chạy) không cần spec riêng."
   causes_vi:
-    - "Agent viết mã trước rồi định sửa lint và spec sau, thay vì chạy vòng op `starci gate read` → mã + spec → `starci gate run`"
+    - "Agent viết mã trước rồi định sửa lint và spec sau, thay vì viết mã cùng spec rồi chạy `npm test -- <pattern>` và `starci app check --fast`"
     - "Spec đã viết nhưng chưa được stage cùng tệp"
-  nextStep_vi: "Viết `<name>.<role>.spec.ts` bên cạnh tệp trong cùng thay đổi, chạy `starci gate run --root <app> --changed <files> --tests <pattern>`, rồi stage cả hai tệp và commit lại qua hook. Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra; không thêm ngoại lệ."
+  nextStep_vi: "Viết `<name>.<role>.spec.ts` bên cạnh tệp trong cùng thay đổi, chạy `npm test -- <pattern>` và `starci app check --fast`, rồi stage cả hai tệp và commit lại qua hook. Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra; không thêm ngoại lệ."
   owner: op-retry
   kind: check-finding
 
@@ -1757,7 +1757,7 @@ CI_STANDARD:
   meaning_vi: "Workflow CI (của app, của ví dụ hoặc của runtime) không đáp ứng một mục của knowledge/hfs/ci-standard.yaml; mục bị vi phạm được nêu trong ngoặc vuông."
   causes_vi:
     - "Vi phạm R301: job shape, lịch sử đầy đủ và STARCI_BASE_REF, heap cho bước nặng, lint Sonar theo từng phía, probe nhà cung cấp tùy chọn, timeout hoặc ghim action theo sha."
-  nextStep_vi: "App: chạy starci app sync --write để render lại CI chuẩn (không sửa tay); runtime: sửa workflow theo mục được nêu."
+  nextStep_vi: "App: chạy starci app sync --execute để render lại CI chuẩn (không sửa tay); runtime: sửa workflow theo mục được nêu."
   owner: op-retry
   kind: check-finding
 
@@ -1768,7 +1768,7 @@ CI_TRIGGERS_RELEASE_ONLY:
   causes_vi:
     - "Khai báo nhánh, sự kiện hoặc bộ lọc không thuộc R221"
     - "Khai báo nhánh, sự kiện hoặc bộ lọc không thuộc R221"
-  nextStep_vi: "Sửa on theo R221 rồi chạy starci app sync --write để tạo lại workflow ứng dụng."
+  nextStep_vi: "Sửa on theo R221 rồi chạy starci app sync --execute để tạo lại workflow ứng dụng."
   owner: supervisor
   kind: check-finding
 
@@ -1779,7 +1779,7 @@ CI_UPLOAD_NOT_SILENT:
   causes_vi:
     - "Dùng token trong repository secret và đặt điều kiện if theo secret đó"
     - "Để continue-on-error hoặc quên fail_ci_if_error cho bước tải"
-  nextStep_vi: "Người giám sát đặt use_oidc: true và fail_ci_if_error: true cho bước, cấp permissions id-token: write cho job, bỏ continue-on-error và điều kiện theo secret, rồi render lại workflow bằng starci app sync --write."
+  nextStep_vi: "Người giám sát đặt use_oidc: true và fail_ci_if_error: true cho bước, cấp permissions id-token: write cho job, bỏ continue-on-error và điều kiện theo secret, rồi render lại workflow bằng starci app sync --execute."
   owner: supervisor
   kind: check-finding
 
@@ -1821,7 +1821,7 @@ DB_BASELINE_SHAPE:
   meaning_vi: "Archive có migration nhưng thiếu hoặc thừa baseline đang hoạt động, marker không nêu stamp cuối của archive, hoặc stamp baseline không hợp lệ và không có bản đồ restamp rõ ràng."
   causes_vi:
     - "Vi phạm R257: chuyển chuỗi migration vào archive mà không tạo baseline đúng marker và stamp."
-  nextStep_vi: "Chạy app db baseline để xem kế hoạch, kiểm tra marker và bản đồ restamp, rồi thi hành với --apply khi kế hoạch đã đúng."
+  nextStep_vi: "Chạy app db baseline để xem kế hoạch, kiểm tra marker và bản đồ restamp, rồi thi hành với --execute khi kế hoạch đã đúng."
   owner: op-retry
   kind: check-finding
 
@@ -2022,7 +2022,7 @@ ENV_REQUIRED_UNSET:
   causes_vi:
     - "Vi phạm luật R248: khoá mà code đọc, khoá được niêm phong và khoá stack truyền vào phải là cùng một tập; khoá bắt buộc thiếu cả chỗ niêm phong lẫn khai báo sẽ làm app không boot được."
     - "Khoá được thêm vào `<app>.env.ts` hoặc `*.config.ts` nhưng quên `starci app secret set` và quên khai báo trong `KEYS.md` hoặc stack."
-  nextStep_vi: "Niêm phong khoá bằng `starci app secret set <env> <slug> <KEY>` hoặc khai báo nó trong `.starcistacks/<env>/runtime/env/KEYS.md` / phần `environment:` của stack."
+  nextStep_vi: "Niêm phong khoá bằng `starci app secret set --env <env> <slug> <KEY>` hoặc khai báo nó trong `.starcistacks/<env>/runtime/env/KEYS.md` / phần `environment:` của stack."
   owner: op-retry
   kind: check-finding
 
@@ -2040,11 +2040,11 @@ ENV_SEALED_UNREAD:
 ENV_VALUE_SHAPE:
   title: "A stored env value does not parse as its reader's type"
   title_vi: "Giá trị env đã lưu không đúng kiểu reader khai báo"
-  meaning_vi: "Một giá trị trong member niêm phong (kiểm bằng `starci app secret verify <env>`) hoặc trong `*.env.example` không parse được theo kiểu reader EnvSource khai báo (int, bool `true`/`false`, url tuyệt đối, duration `250`/`30s`/`5m`/`2h`, hoặc một giá trị enum đã khai báo)."
+  meaning_vi: "Một giá trị trong member niêm phong (kiểm bằng `starci app secret verify --env <env>`) hoặc trong `*.env.example` không parse được theo kiểu reader EnvSource khai báo (int, bool `true`/`false`, url tuyệt đối, duration `250`/`30s`/`5m`/`2h`, hoặc một giá trị enum đã khai báo)."
   causes_vi:
     - "Vi phạm luật R249: app boot sẽ fail hoặc đọc sai ngầm khi giá trị không khớp parser — như `OPENCLAW_MANAGE_AGENTS=1` cho `env.bool` (D2-03)."
     - "Giá trị được set bằng định dạng khác (`1` thay `true`, `1000` thay `1s`, URL thiếu scheme)."
-  nextStep_vi: "Sửa giá trị qua `starci app secret set <env> <slug> <KEY>` cho đúng kiểu reader khai báo, hoặc sửa example; verify in ra tên khoá và kiểu bị vi phạm, không in giá trị."
+  nextStep_vi: "Sửa giá trị qua `starci app secret set --env <env> <slug> <KEY>` cho đúng kiểu reader khai báo, hoặc sửa example; verify in ra tên khoá và kiểu bị vi phạm, không in giá trị."
   owner: op-retry
   kind: check-finding
 
@@ -2911,7 +2911,7 @@ FE_STACK_FAMILY_LINT_MISSING:
   meaning_vi: "hfs.json chọn sides.fe.grammar (starci hoặc offset-pop) và front end khai báo @starci/eslint-canon-fe 9 trở lên, nhưng không manifest nào khai báo gói lint của họ đó; từ canon-fe 9 các luật component Grammar nằm trong gói này, thiếu gói thì các luật ấy không chạy."
   causes_vi:
     - "Nâng @starci/eslint-canon-fe lên 9 mà chưa thêm @starci/eslint-grammar-core (Grammar StarCi) hoặc @starci/eslint-grammar-offset-pop (Grammar Offset Pop)."
-  nextStep_vi: "Thêm @starci/eslint-grammar-core (hoặc @starci/eslint-grammar-offset-pop) cạnh @starci/eslint-canon-fe, ghép coreGrammarConfig({ hfs }) (hoặc offsetPopGrammarConfig({ hfs })) sau starciFeConfig({ hfs }) trong fe/eslint.config.mjs, hoặc chạy starci app sync."
+  nextStep_vi: "Thêm @starci/eslint-grammar-core (hoặc @starci/eslint-grammar-offset-pop) cạnh @starci/eslint-canon-fe, ghép coreGrammarConfig({ hfs }) (hoặc offsetPopGrammarConfig({ hfs })) sau starciFeConfig({ hfs }) trong fe/eslint.config.mjs, hoặc chạy starci app sync --execute."
   owner: op-retry
   kind: check-finding
 
@@ -3183,7 +3183,7 @@ HFS_APP_WORKFLOW_TRIGGER:
   meaning_vi: "Workflow ứng dụng khai báo trigger ngoài R251; ci.yml được chạy trên main và nhánh release candidate, các workflow khác giữ phạm vi trigger của R251."
   causes_vi:
     - "Khai báo trigger không thuộc R251"
-  nextStep_vi: "Sửa trigger theo R251 và chạy starci app sync --write."
+  nextStep_vi: "Sửa trigger theo R251 và chạy starci app sync --execute."
   owner: op-retry
   kind: check-finding
 
@@ -3228,6 +3228,17 @@ HFS_AUDIT_STEP_MISSING:
   owner: op-retry
   kind: check-finding
 
+HFS_AUTH_COOKIE_DOMAIN_MISSING:
+  title: "The api's refresh cookie cannot reach a web served on another host"
+  title_vi: "Cookie refresh của api không tới được web chạy ở host khác"
+  meaning_vi: "Web và api của một môi trường chạy ở hai host khác nhau nhưng môi trường của api không có AUTH_COOKIE_DOMAIN (hoặc giá trị khai báo không phải tên miền trần, hoặc không phải miền cha của cả hai host), nên cookie refresh chỉ gắn với host của api và không có trong header Cookie mà máy chủ web chuyển tiếp: api từ chối phiên và người dùng bị đưa về trang đăng nhập."
+  causes_vi:
+    - "Vi phạm R337: passport của skeleton lite đặt cookie refresh theo host khi AUTH_COOKIE_DOMAIN không được đặt."
+    - "AUTH_COOKIE_DOMAIN có scheme, cổng, dấu chấm đầu, hoặc là miền không bao trùm host của web hay của api."
+  nextStep_vi: "Đặt AUTH_COOKIE_DOMAIN bằng miền cha chung của hai host (thông báo nêu giá trị) trong environment của api, KEYS.md hoặc một khoá sealed, rồi chạy lại starci app check."
+  owner: op-retry
+  kind: check-finding
+
 HFS_BACKING_UNDECLARED:
   title: "A lite app uses undeclared Redis or full-only Qdrant instead of Supabase pgvector"
   title_vi: "App lite dùng Redis chưa khai báo hoặc Qdrant chỉ thuộc full thay cho Supabase pgvector"
@@ -3331,7 +3342,7 @@ HFS_COVERAGE_SCOPE_DRIFT:
     - "Sửa tay be/jest.config.js, codecov.yml hoặc dòng sonar.coverage.exclusions để đo ít tệp hơn hoặc thêm ngoại lệ"
     - "Đổi trường coverage của slot hoặc ruleParams.be.logicRoles nhưng chưa chạy lại starci app sync"
     - "Thêm service app hoặc capability mới nên các component của codecov.yml đã cũ"
-  nextStep_vi: "Chạy `npx starci app sync --write` để sinh lại ba tệp từ slot manifest; muốn đổi phạm vi thì đổi trường `coverage` của slot (và ruleParams.be.logicRoles) trong .claude runtime, không sửa tệp sinh. Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra (nợ hàng loạt có codemod của HFS); không cần ai can thiệp thêm."
+  nextStep_vi: "Chạy `npx starci app sync --execute` để sinh lại ba tệp từ slot manifest; muốn đổi phạm vi thì đổi trường `coverage` của slot (và ruleParams.be.logicRoles) trong .claude runtime, không sửa tệp sinh. Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra (nợ hàng loạt có codemod của HFS); không cần ai can thiệp thêm."
   owner: op-retry
   kind: check-finding
 
@@ -3431,10 +3442,10 @@ HFS_DOCKER_BASE_PIN:
 HFS_DOCKER_BUILD_CONTEXT:
   title: "The Dockerfile does not build from the app root"
   title_vi: "Dockerfile không build từ gốc app"
-  meaning_vi: "Dockerfile của app phải ghi trong comment đầu tệp lệnh `starci docker build <app>` đúng app của chính nó (context là gốc app, nơi có `package.json` và lockfile duy nhất), và mọi nguồn của COPY/ADD nằm trong context (không có `..`, không có đường dẫn tuyệt đối)."
+  meaning_vi: "Dockerfile của app phải ghi trong comment đầu tệp lệnh `docker build -f <side>/apps/<app>/Dockerfile -t <image> .` đúng app của chính nó (context là gốc app, nơi có `package.json` và lockfile duy nhất), và mọi nguồn của COPY/ADD nằm trong context (không có `..`, không có đường dẫn tuyệt đối)."
   causes_vi:
     - "Vi phạm luật R187: context build là gốc app; lệnh build sai hoặc nguồn COPY vượt ra ngoài context khiến image build được trên máy này nhưng hỏng trên CI hoặc trộn lẫn dữ liệu của app khác."
-  nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra: đặt lệnh `starci docker build <app>` vào comment đầu Dockerfile và sửa các nguồn COPY/ADD về đường dẫn tương đối trong gốc app."
+  nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra: đặt lệnh `docker build -f <side>/apps/<app>/Dockerfile -t <image> .` vào comment đầu Dockerfile và sửa các nguồn COPY/ADD về đường dẫn tương đối trong gốc app."
   owner: op-retry
   kind: check-finding
 
@@ -3471,10 +3482,10 @@ HFS_DOCKER_SECRETS:
 HFS_DOCKER_STAGES:
   title: "The Dockerfile stages, user or install break the canon"
   title_vi: "Các stage, user hoặc lệnh cài của Dockerfile sai chuẩn"
-  meaning_vi: "Dockerfile phải nhiều stage: một stage tên `build` (cài và build) và stage cuối tên `runtime` (thứ được chạy); runtime kết thúc bằng `USER node` và không chạy build; mọi lệnh cài đi qua `starci npm ci` (không dùng `starci npm install`); runtime của be chỉ cài dependency production và bỏ lifecycle scripts, runtime của fe không cài gì."
+  meaning_vi: "Dockerfile phải nhiều stage: một stage tên `build` (cài và build) và stage cuối tên `runtime` (thứ được chạy); runtime kết thúc bằng `USER node` và không chạy build; mọi lệnh cài là `npm ci` (không dùng `npm install`); runtime của be chỉ cài dependency production và bỏ lifecycle scripts, runtime của fe không cài gì."
   causes_vi:
     - "Vi phạm luật R188: image chạy bằng root, mang theo công cụ build hoặc cài không theo lockfile thì vừa lớn vừa kém an toàn, và không tái lập được."
-  nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra: tách Dockerfile thành stage `build` và stage cuối `runtime`, thêm `USER node`, đổi `starci npm install` thành `starci npm ci`, và chuyển mọi lệnh build ra khỏi runtime."
+  nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra: tách Dockerfile thành stage `build` và stage cuối `runtime`, thêm `USER node`, đổi `npm install` thành `npm ci`, và chuyển mọi lệnh build ra khỏi runtime."
   owner: op-retry
   kind: check-finding
 
@@ -3581,7 +3592,7 @@ HFS_EDITION_INVALID:
   meaning_vi: "Trường edition của hfs.json chỉ nhận một giá trị thuộc danh sách editions của bảng kê ô (full, lite); vắng mặt nghĩa là full. Một giá trị khác là lỗi khai báo, kiểm tra bị từ chối."
   causes_vi:
     - "hfs.json ghi edition với giá trị ngoài full/lite (gõ sai, hoặc một ấn bản bảng kê không biết)"
-    - "`starci app check --edition <ấn bản>` hoặc `starci app upgrade --edition <ấn bản>` chọn ấn bản khác với ấn bản hfs.json khai: ấn bản cố định từ lúc scaffold"
+    - "`starci app check --edition <ấn bản>` chọn ấn bản khác với ấn bản hfs.json khai: ấn bản cố định từ lúc scaffold (`starci app upgrade` không nhận `--edition`: HFS_UPGRADE_USAGE)"
   nextStep_vi: "Sửa edition thành một giá trị trong danh sách editions của bảng kê, hoặc bỏ trường để về full. Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra; không cần ai can thiệp thêm."
   owner: op-retry
   kind: check-finding
@@ -3657,9 +3668,9 @@ HFS_FORMAT_TOOL_MISSING:
   title_vi: "Kho chưa cài prettier của chính nó"
   meaning_vi: "Kiểm tra định dạng (R19) chạy prettier của chính kho. Kho chưa cài prettier nên không thể xác nhận định dạng, và trạng thái đó không bao giờ được tính là đạt."
   causes_vi:
-    - "Chưa chạy `starci npm ci` trong kho"
+    - "Chưa chạy `npm ci` trong kho"
     - "prettier không nằm trong devDependencies của kho"
-  nextStep_vi: "Cài đúng phiên bản prettier ghi trong canon-pins.yaml bằng `starci npm ci` rồi chạy lại `starci app check`."
+  nextStep_vi: "Cài đúng phiên bản prettier ghi trong canon-pins.yaml bằng `npm ci` rồi chạy lại `starci app check`."
   owner: op-retry
   kind: input-invalid
 
@@ -3687,7 +3698,7 @@ HFS_GHOST_TREE:
 HFS_GITIGNORE_BLOCK_DRIFT:
   title: "The managed `.gitignore` block equals its render"
   title_vi: "Khối .gitignore lệch bản render"
-  meaning_vi: "Khối .gitignore chuẩn đã bị sửa tay hoặc thiếu dòng `<rule>`. Chạy `starci app sync`."
+  meaning_vi: "Khối .gitignore chuẩn đã bị sửa tay hoặc thiếu dòng `<rule>`. Chạy `starci app sync --execute`."
   causes_vi:
     - "Vi phạm luật R04: Khối `.gitignore` do `.claude` quản lý phải trùng bản render (never-tracked list, deny `.env*`, cache)."
   nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra (nợ hàng loạt có codemod của HFS); không cần ai can thiệp thêm."
@@ -3701,7 +3712,7 @@ HFS_HOOKS_NOT_INSTALLED:
   causes_vi:
     - "Cài phụ thuộc với `--ignore-scripts` nên script `prepare` (husky) không chạy"
     - "Worktree mới tạo chưa từng chạy husky; runtime chỉ ghi hook riêng của nó vào `.husky/_`"
-  nextStep_vi: "Chạy `starci npm ci` ở gốc app (lệnh này chạy trình cài hook husky `prepare` của app kể cả khi lifecycle script bị bỏ qua), rồi commit lại qua hook; không dùng `--no-verify`. Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra."
+  nextStep_vi: "Chạy `npm ci` ở gốc app (script `prepare` của app là trình cài hook husky; sau một lần cài `--ignore-scripts` thì chạy `npm run prepare`), rồi commit lại qua hook; không dùng `--no-verify`. Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra."
   owner: op-retry
   kind: check-finding
 
@@ -3780,7 +3791,7 @@ HFS_LITE_SECRET_CUSTODY:
 HFS_MANAGED_FILE_DRIFT:
   title: "A managed file equals its template render"
   title_vi: "Tệp do .claude quản lý bị lệch"
-  meaning_vi: "`<file>` do `.claude` quản lý nhưng nội dung lệch bản render từ template. Chạy `starci app sync --write`, không sửa tay."
+  meaning_vi: "`<file>` do `.claude` quản lý nhưng nội dung lệch bản render từ template. Chạy `starci app sync --execute`, không sửa tay."
   causes_vi:
     - "Vi phạm luật R05: Tệp trong slot có `managedBy` của slots.yaml (tsconfig, jest.config.js, .prettierrc, .prettierignore, husky, workflows, sonar, khối `scripts` của package.json) phải bằng bản render từ template; danh sách tệp nằm trong slots.yaml, không nằm trong mã."
   nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra (nợ hàng loạt có codemod của HFS); không cần ai can thiệp thêm."
@@ -3869,7 +3880,7 @@ HFS_MONO_WORKSPACES:
   meaning_vi: "`package.json` ở gốc app phải khai báo `workspaces` đúng `[\"fe/apps/*\", \"fe/packages/*\"]`, `packageManager` là `npm@<phiên bản cụ thể>` và `turbo` trong devDependencies; gốc app giữ `turbo.json` do starci app sync sinh ra."
   causes_vi:
     - "Vi phạm luật R143: mọi sản phẩm luôn là monorepo, kể cả khi chỉ có một service, nên hình dạng hfs đồng nhất; thiếu workspaces hoặc turbo thì các app fe không được build qua turbo."
-  nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra: đặt `workspaces`, `packageManager` và devDependency `turbo` (đúng bản ghim) trong `package.json` ở gốc, rồi chạy `npx starci app sync --write` để sinh `turbo.json`."
+  nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra: đặt `workspaces`, `packageManager` và devDependency `turbo` (đúng bản ghim) trong `package.json` ở gốc, rồi chạy `npx starci app sync --execute` để sinh `turbo.json`."
   owner: op-retry
   kind: check-finding
 
@@ -3878,7 +3889,7 @@ HFS_MONO_WORKSPACE_DEP:
   title_vi: "Một workspace fe import gói mà nó không khai báo"
   meaning_vi: "Mọi gói mà các tệp của một workspace fe import phải được khai báo trong `package.json` của chính workspace đó (gói workspace anh em ghi `\"*\"`); `package.json` ở gốc không bao giờ khai báo một gói workspace."
   causes_vi:
-    - "Vi phạm luật R146: một app chỉ chạy được nhờ gói được hoist từ gốc sẽ hỏng khi build riêng bằng `starci docker build <app>` hoặc khi turbo không biết thứ tự phụ thuộc."
+    - "Vi phạm luật R146: một app chỉ chạy được nhờ gói được hoist từ gốc sẽ hỏng khi build riêng image của app (`starci app stack build`) hoặc khi turbo không biết thứ tự phụ thuộc."
   nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra: thêm gói vào dependencies của workspace đó (cùng một phiên bản trong cả workspace), hoặc bỏ gói workspace khỏi `package.json` ở gốc."
   owner: op-retry
   kind: check-finding
@@ -4102,7 +4113,7 @@ HFS_ROOT_SRC_FORBIDDEN_FE:
 HFS_RULE_OFF_WITHOUT_REPLACEMENT:
   title: "The ESLint configuration (and a front end's stylelint configuration) is the rendered one-liner, so no rule is off, warned or redefined in a repository"
   title_vi: "Cấu hình ESLint hoặc stylelint lệch bản render"
-  meaning_vi: "`eslint.config.mjs` (hoặc `stylelint.config.mjs` của front end) khác bản render (một dòng gọi `starciBeConfig`, `starciFeConfig` hoặc `starciStylelintConfig`). Factory không nhận tham số ghi đè, nên một luật chỉ có thể bị tắt, hạ mức hoặc định nghĩa lại trong repo khi tệp này khác bản render. Chạy `starci app sync --write`, không sửa tay."
+  meaning_vi: "`eslint.config.mjs` (hoặc `stylelint.config.mjs` của front end) khác bản render (một dòng gọi `starciBeConfig`, `starciFeConfig` hoặc `starciStylelintConfig`). Factory không nhận tham số ghi đè, nên một luật chỉ có thể bị tắt, hạ mức hoặc định nghĩa lại trong repo khi tệp này khác bản render. Chạy `starci app sync --execute`, không sửa tay."
   causes_vi:
     - "Vi phạm luật R17: `eslint.config.mjs` phải đúng bằng bản render; luật thay thế nằm trong plugin của `.claude`, không bao giờ tắt trong repo."
   nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra; không cần ai can thiệp thêm."
@@ -4552,7 +4563,7 @@ RIGHTS_PUSH_NOT_RELEASE:
     - "Đẩy main không phải fast-forward của main trên remote (force push, rewind hoặc nhánh rẽ)"
     - "Vùng đẩy chứa ứng viên bí mật (tên tệp, dòng và mẫu, không bao giờ giá trị)"
     - "Đẩy thẻ v* không phải thẻ annotated"
-  nextStep_vi: "Gỡ hoặc mã hóa ứng viên bí mật, fetch main rồi đẩy lại bằng starci release push; thẻ thì tạo bằng starci release cut --tag v<version> (thêm --plan để xem trước)."
+  nextStep_vi: "Gỡ hoặc mã hóa ứng viên bí mật, fetch main rồi đẩy lại bằng starci release push; thẻ thì tạo bằng starci release cut (thêm --dry-run để xem trước)."
   owner: supervisor
   kind: verb-refusal
 
@@ -4964,7 +4975,7 @@ RT_HOOK_SHAPE:
   causes_vi:
     - "Thêm lại npm run typecheck hoặc test:affected vào pre-commit"
     - "Đưa build, typecheck, lint hay test vào pre-push hoặc bỏ lời gọi chính sách push dùng chung"
-  nextStep_vi: "Khôi phục template theo R225 rồi chạy starci app sync --write để tạo lại hook."
+  nextStep_vi: "Khôi phục template theo R225 rồi chạy starci app sync --execute để tạo lại hook."
   owner: supervisor
   kind: check-finding
 
@@ -5515,7 +5526,7 @@ STACK_TOOLING_REIMPLEMENTED:
   causes_vi:
     - "Vi phạm R293: kho mã giữ bản sao công cụ Swarm riêng (docker stack deploy, docker secret create, docker swarm init...) thay vì gọi động từ của canon."
     - "Một workflow hoặc script trong deploy/, scripts/ hay package.json gọi trực tiếp docker cho việc canon đã làm."
-  nextStep_vi: "Xóa tệp hoặc lệnh đó và gọi động từ được nêu trong thông báo (starci app stack render, deploy, converge, verify, prune, rollback, prepare, doctor), đặt hằng số của ứng dụng vào khối deploy của application-stacks.yaml."
+  nextStep_vi: "Xóa tệp hoặc lệnh đó và gọi động từ được nêu trong thông báo (starci app stack render, deploy, converge, verify, prune, rollback, prepare), đặt hằng số của ứng dụng vào khối deploy của application-stacks.yaml."
   owner: op-retry
   kind: check-finding
 

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

@@ -582,7 +582,7 @@ $defs:
         propertyNames: {$ref: '#/$defs/deployName'}
         additionalProperties: {$ref: '#/$defs/deployImage'}
       volumes:
-        description: External volumes prepare creates and doctor checks.
+        description: External volumes prepare creates (with --execute) and checks (dry run).
         type: array
         items: {$ref: '#/$defs/deployVolumeName'}
       secrets: {$ref: '#/$defs/deploySecrets'}
@@ -650,10 +650,10 @@ $defs:
         pattern: '^[A-Za-z0-9][A-Za-z0-9._-]*$'
       releasesBase: {$ref: '#/$defs/deployAbsolutePath'}
       sealed:
-        description: 'Owner-machine session for prepare, doctor and deploy: the one member of .starcistacks/<environment>/secrets holding VPS_HOST, VPS_USER, privateKey and knownHosts.'
+        description: 'Owner-machine session for prepare and deploy: the one member of .starcistacks/<environment>/secrets holding VPS_HOST, VPS_USER, privateKey and knownHosts.'
         $ref: '#/$defs/deployName'
       serverRecipient:
-        description: The deploy server's public age recipient, recorded by starci app secret server-key <env> --execute.
+        description: The deploy server's public age recipient, recorded by starci app secret server-key --env <env> --execute.
         type: string
         pattern: '^age1[a-z0-9]+$'
   deployImage:

package/runtime/packages/cli/src/catalog.generated.d.mts

@@ -0,0 +1,13 @@
+// catalog.generated.d.mts - the types of catalog.generated.mjs, the command table runtime/scripts/cli/gen-catalog.mjs writes from the
+// starci CLI registry (cli/src/registry.ts). Hand-written: the generated module carries no types of its own.
+import type { CatalogFlag, CatalogVerb } from './validate-args.mjs';
+
+/** One catalogued verb: its summary and the flags, positionals, editions and json mode validateArgs judges a command line by. */
+export interface CatalogEntry extends CatalogVerb { summary: string; flags: CatalogFlag[] }
+
+/** The starci command catalog: the global flags, and per group its verbs and, for a group that is itself a command, `self`. */
+export declare const CATALOG: {
+  readonly schema: string;
+  readonly global: CatalogFlag[];
+  readonly groups: Record<string, { readonly verbs: Record<string, CatalogEntry>; readonly self?: CatalogEntry }>;
+};