@starci/hfs 4.0.8 → 4.0.9

package/runtime/knowledge/patterns/be/api.yaml

@@ -0,0 +1,369 @@
+schema: starci/knowledge-source@1
+id: be.api
+title: Backend api feature
+purpose: |-
+  Given a scenario a request or a background transport triggers, where does it live and how is it written? It is an api
+  feature, `be/src/features/api/<feature>/`, the trigger kind the api apps compose. Its application layer is CQRS: one
+  typed command or query per operation and one handler that owns the scenario, dispatched by a transport directly on the
+  bus. There is no use-case class and no forwarder service. Inside one bounded context the work is synchronous; an event
+  only crosses contexts or carries async work.
+appliesTo:
+  - backend
+family: be
+# The slot ids this topic teaches (knowledge/hfs/slots.yaml); scripts/gates/read-digest.mjs inverts these
+# into the READ-step slot -> pattern-topic map (knowledge/op-gate.yaml kinds), each slot's topics in index.yaml order.
+slots: [be.feature, be.feature.application]
+provenance:
+  reviewedAt: 2026-10-02
+  sources:
+    - knowledge/hfs/README.md
+    - knowledge/hfs/slots.yaml
+    - knowledge/hfs/rules.yaml
+    - owner-locked BE convention 2026-09-30
+    - owner decision 2026-10-02 (features grouped by trigger kind; synchronous inside a context)
+    - https://docs.nestjs.com/recipes/cqrs
+  limitations: |-
+    Static checks prove the shape of a feature, a message, its handler and the dispatch, and that SQL touches only tables its
+    owner may reach. They do not prove that a handler decides the right thing, that a transaction boundary is right, that a
+    context boundary is drawn where the business draws it or that a refusal is chosen over an exception correctly; the
+    service spec of the service the handler calls and the e2e run prove behavior, and design review proves the boundary.
+rules:
+  - id: BE-CQRS-1
+    title: The application folder holds messages, handlers, contracts and support only
+    kind: mandatory
+    hfsRules: [R87, R29]
+    requirement: |-
+      `be/src/features/api/<feature>/application/` holds `<action>.command.ts` or `<action>.query.ts`, `<action>.handler.ts`,
+      `<action>.contracts.ts` and the opt-in `support/` folder of helpers local to the feature. A
+      `*.use-case.ts` file, a forwarder `<op>.service.ts` and a folder named after a protocol do not exist. A read is a
+      query and a write is a command; a handler never serves both.
+    rationale: |-
+      One shape for every operation gives one interception point and one message object, so a reader finds the scenario
+      in the handler and never in a wrapper around it.
+    cases:
+      - id: case-1
+        when: A new write operation
+        write: 'application/start-checkout.command.ts, start-checkout.handler.ts, start-checkout.contracts.ts (the handler has no spec: its service does).'
+      - id: case-2
+        when: A new read operation
+        write: 'application/get-cart.query.ts, get-cart.handler.ts, get-cart.contracts.ts (the handler has no spec: its service does).'
+    verification:
+      automated:
+        - BE_CQRS_SHAPE
+        - BE_READONLY_BOUNDARY
+        - BE_FEATURE_SHAPE
+        - BE_FEATURE_LAYOUT_INVALID
+        - BE_APPLICATION_IMPORTS_TRANSPORT
+        - BE_APPLICATION_TRANSPORT_FRAMEWORK
+      manual:
+        - Confirm each operation is a command or a query and no handler mixes both.
+    relatedExamples: []
+  - id: BE-CQRS-2
+    title: A message is a typed Command or Query carrying one params field
+    kind: mandatory
+    hfsRules: [R87, R37]
+    requirement: |-
+      `export class <Action>Command extends Command<<Action>Result> { constructor(readonly params: ExecuteParams<<Action>Request>) { super() } }`
+      (`Query<R>` for reads). One `readonly params` field, no methods, no defaults. `ExecuteParams<T> = { request: T; principal: Principal }`
+      for an authenticated operation and `PublicExecuteParams<T> = { request: T }` for a `@Public` one, so the type states
+      whether the door is public and the principal is never optional. `Principal = { id: string; roles: ReadonlyArray<Role> }`
+      is owned by `platform/cqrs`. An entity never travels in params.
+    rationale: |-
+      `@nestjs/cqrs` 11 types `execute` with the message's result type, so the compiler proves what the transport gets
+      back, and a principal that cannot be absent removes a class of authorization bugs.
+    cases:
+      - id: case-1
+        when: An authenticated command
+        write: 'export class StartCheckoutCommand extends Command<StartCheckoutResult> { constructor(readonly params: ExecuteParams<StartCheckoutRequest>) { super() } }'
+      - id: case-2
+        when: A public query
+        write: 'export class CheckHealthQuery extends Query<CheckHealthResult> { constructor(readonly params: PublicExecuteParams<CheckHealthRequest>) { super() } }'
+    verification:
+      automated:
+        - BE_CQRS_SHAPE
+        - BE_READONLY_BOUNDARY
+        - BE_ENTITY_IN_CONTRACT
+      manual:
+        - Review that the request carries what the operation needs and nothing of the transport.
+    relatedExamples: []
+  - id: BE-CQRS-3
+    title: A handler overrides process and returns its declared result
+    kind: mandatory
+    hfsRules: [R87, R75, R48, R203]
+    requirement: |-
+      `@CommandHandler(X)` or `@QueryHandler(X)` on a class that `extends ICQRSHandler<X, XResult>` and implements
+      `protected override async process(message)`; it never overrides `execute`. `ICQRSHandler.execute` is load-bearing: it
+      logs `OperationFailed` with the operation name and the error and rethrows, and counts refused outcomes. `<Action>Result`
+      is a plain projection type or an `Outcome<Value, Code>` and the return type of `process` is declared. The handler opens
+      the transaction (`this.entityManager.transaction(async (manager) => ...)`), stamps `this.clock.now()` once and passes
+      it down. The handler is thin (R203 `BE_FEATURE_THIN`): its `process` maps the message, makes one delegating call to an
+      injected `*.service` and returns the result, so it has no unit spec; the decisions (persisted state, the `where` that
+      holds ownership, nothing written on a refusal) live in the service and its `<name>.service.spec.ts` asserts them.
+    rationale: |-
+      A single template gives every operation the same failure log and metric, and the service spec pins the decision the
+      handler delegates.
+    cases:
+      - id: case-1
+        when: A handler
+        write: |-
+          @CommandHandler(StartCheckoutCommand)
+          /** Opens a checkout, or refuses with a purchase code. */
+          export class StartCheckoutHandler extends ICQRSHandler<StartCheckoutCommand, StartCheckoutResult> {
+              constructor(
+                  @InjectPrimaryEntityManager() private readonly entityManager: EntityManager,
+                  @InjectClock() private readonly clock: Clock,
+                  private readonly purchaseService: PurchaseService,
+              ) { super() }
+
+              protected override async process(command: StartCheckoutCommand): Promise<StartCheckoutResult> {
+                  const at = this.clock.now()
+                  return this.entityManager.transaction(async (manager) => this.purchaseService.open({ manager, learnerId: command.params.principal.id, offerId: command.params.request.offerId, at }))
+              }
+          }
+    verification:
+      automated:
+        - BE_CQRS_SHAPE
+        - BE_READONLY_BOUNDARY
+        - BE_RETURN_TYPE
+        - BE_SPEC_QUALITY
+        - BE_FEATURE_THIN
+      manual:
+        - Confirm the service spec the handler calls asserts refusal paths and ownership, not only that a mock was called.
+    relatedExamples: []
+  - id: BE-CQRS-4
+    title: The bus is the only way into a handler; nothing forwards
+    kind: mandatory
+    hfsRules: [R87, R88, R90]
+    requirement: |-
+      A handler is reached only through `commandBus.execute` or `queryBus.execute` from a transport (the transport side is
+      transport.yaml BE-TRANSPORT-2). No `<op>.service.ts` sits between a transport and a handler. Work that stays
+      inside one context is synchronous: the handler calls the domain service in one transaction. A follow-up that must happen
+      anyway or that crosses a context is an event published inside that transaction (event-bus.yaml, BE-API-2), never an
+      in-process event: `EventBus`, `@EventsHandler`, `EventEmitter2`, `@OnEvent` and NATS bridges are not used.
+    rationale: |-
+      A forwarder is pure indirection where logic creeps in, and an in-process event does not survive a crash between the
+      commit and the delivery.
+    cases:
+      - id: case-1
+        when: A resolver needs an operation
+        write: '`constructor(@InjectCommandBus() private readonly commandBus: CommandBus) {}` then `this.commandBus.execute(new StartCheckoutCommand({ request, principal }))`.'
+      - id: case-2
+        when: A follow-up effect in another context after a write
+        write: 'the domain service the handler calls publishes the event with eventBus.publish(event, tx) in its own transaction; a reactor or job consumes it (event-bus.yaml).'
+    verification:
+      automated:
+        - BE_CQRS_SHAPE
+        - BE_READONLY_BOUNDARY
+        - BE_TRANSPORT_SHAPE
+        - BE_INFRA_OWNER
+      manual: []
+    relatedExamples: []
+  - id: BE-API-1
+    title: An api feature has one fixed shape and is composed only by apps
+    kind: mandatory
+    hfsRules: [R29, R28, R30, R31, R45]
+    requirement: |-
+      An api feature is `be/src/features/api/<feature>/` (slot `be.feature`) and holds `index.ts`, `<feature>.module.ts`,
+      `application/` (`be.feature.application`, with the opt-in `support/`, `be.feature.application.support`),
+      `transport/<protocol>/` and, when it has copy, `messages/` (`be.feature.messages`), and nothing else. A protocol lives
+      in `transport/graphql`, `transport/http` (`be.transport.{graphql,http}`, composed by an api app) or
+      `transport/message` (`be.transport.message`, composed by the api app that owns it or by a worker app), each with
+      exactly one Nest module `<feature>-<protocol>.module.ts`, its resolvers, controllers or consumers, their `<action>.mapper.ts` and `dto/` where the protocol has DTOs (shapes in
+      transport.yaml). The feature imports only downward into `src/modules/*`, never another api feature and never another
+      trigger kind such as `features/cli`; only `be/apps/*` composes it (folder.yaml BE-FOLDER-2).
+    rationale: |-
+      Several entry protocols share one operation without importing transport DTOs into the application layer, and an app can
+      compose only the transports it serves.
+    cases:
+      - id: case-1
+        when: An operation reachable over HTTP and GraphQL
+        write: application/place-order.command.ts and its handler once; transport/http/place-order.controller.ts and transport/graphql/place-order.resolver.ts each dispatch it.
+      - id: case-2
+        when: A conversion has substance
+        write: transport/graphql/place-order.mapper.ts with toPlaceOrderType and toPlaceOrderRequest.
+      - id: case-3
+        when: A feature grows past 250 source files
+        write: Split it by product capability into api features, moving shared behavior into a domain capability.
+      - id: case-4
+        when: An api feature imports features/cli/seed/subs/demo.cli.ts to reuse its rows
+        write: 'Refused (BE_FEATURE_IMPORTS_FEATURE): both kinds import the domain capability that owns the rows instead.'
+    verification:
+      automated:
+        - BE_FEATURE_SHAPE
+        - BE_FEATURE_LAYOUT_INVALID
+        - BE_APPLICATION_IMPORTS_TRANSPORT
+        - BE_APPLICATION_TRANSPORT_FRAMEWORK
+        - BE_FEATURE_IMPORTS_FEATURE
+        - BE_PUBLIC_SURFACE
+        - ARCH_OWNER_EXPORT_BYPASS
+        - ARCH_OWNER_EXPORT_STAR
+        - HFS_ALIAS_REEXPORT
+        - ARCH_PACKAGE_EXPORT_BYPASS
+        - BE_FEATURE_NOT_COMPOSED
+        - BE_MODULE_SHAPE
+        - BE_MODULE_HANDLER_REGISTRATION
+        - BE_MODULE_PROVIDER_REREGISTRATION
+      manual:
+        - Review application contracts for request-context, ORM entity and protocol DTO leaks.
+    relatedExamples: []
+  - id: BE-API-2
+    title: Inside one context the work is synchronous; events only cross contexts or carry async work
+    kind: mandatory
+    hfsRules: [R87, R26, R86, R82]
+    requirement: |-
+      A context is one bounded context: one domain capability set under `src/modules/domain/`, which may own one Postgres
+      schema. Work inside one context is synchronous: the handler calls that context's domain service directly, in one
+      transaction it opens, and emits no event to reach code of the same context. An event (an outbox message consumed in
+      `transport/message/`) exists only to cross into another context or to carry work that runs later. A feature never reads
+      or writes another context's tables or state directly; it receives that context's facts through an event or reads a
+      projection its own context owns.
+    rationale: |-
+      An event inside one context turns one atomic decision into a chain that can half-fail, while a direct read of another
+      context's state couples two owners through their storage and bypasses the owner's rules.
+    cases:
+      - id: case-1
+        when: add-cart-item (passing)
+        write: 'AddCartItemHandler opens one transaction and calls `this.cartService.addItem({ manager, buyerId, productId, quantity, at })`; the cart rows and the quantity check commit together, with no event.'
+      - id: case-2
+        when: The order feature needs the payment state (violating)
+        write: 'Refused: PlaceOrderHandler querying the payment tables or calling PaymentService to read whether a payment settled. The payment context publishes PaymentSettled through its outbox, and an order consumer in transport/message records it in an order-owned projection the order handler reads.'
+      - id: case-3
+        when: A confirmation mail after the order commits (async)
+        write: 'The order handler enqueues OrderPlaced in its transaction; the mail runs later from a consumer, never inside the order transaction.'
+    verification:
+      automated:
+        - BE_CQRS_SHAPE
+        - BE_READONLY_BOUNDARY
+        - BE_TIER_DIRECTION
+        - FE_TIER_DIRECTION
+        - ARCH_PACKAGE_IMPORTS_APP
+        - BE_SQL_TABLE_OWNER
+        - BE_TRANSACTION_EXTERNAL_CALL
+      manual:
+        - Confirm each event crosses a context boundary or carries deferred work, and that no handler waits on an event of its own context.
+    relatedExamples: []
+  - id: BE-API-3
+    title: Every operation has an e2e flow on the real app
+    kind: mandatory
+    hfsRules: [R46, R41]
+    requirement: |-
+      Each resolver method and controller action of an api feature is driven by an e2e spec (`src/tests/e2e/<area>/*.e2e-spec.ts`) that boots the
+      app's real AppModule and calls it as a client does: the happy path, the refusal the command declares and the denial of an unauthenticated caller.
+    rationale: |-
+      A transport is thin (R203 `BE_FEATURE_THIN`) and has no logic to unit-test; what can break is the wiring, the guards and the mapping, which only the booted app exercises.
+    cases:
+      - id: case-1
+        when: A new mutation
+        write: 'checkout.e2e-spec.ts signs a shopper in, runs startCheckout, asserts the typed payload, then asserts the same call without a token is refused.'
+    verification:
+      automated:
+        - BE_BACKGROUND_UNOWNED
+        - BE_DEFAULT_DENY
+      manual:
+        - Confirm the spec asserts the error code of each refusal, not only a status.
+    relatedExamples: [api]
+  - id: BE-OPERATIONS-1
+    title: A versioned operation is declared once in the app's typed operation table
+    kind: mandatory
+    hfsRules: [R95, R88, R23]
+    requirement: |-
+      A versioned operation `<name>@<version>` (for example `sales.policy@1`) that an app serves over one operation route is
+      declared once, in the app's operation table `be/apps/<app>/src/operations.ts`, which exports `OPERATIONS`. The table is made by
+      `defineOperations` of the platform capability `operations` (`be/src/modules/platform/operations/`, which declares
+      `OperationContract<Input, Output, RefusalCode>`, `query`, `mutation`, `defineOperations`, `OperationRequest<Table>` and
+      `OperationReply<Table>`). `Input` and `Output` are named, closed types: never `any`, `unknown`, `Record<string, unknown>`,
+      `object`, an unbound generic, a function or `Date`. `RefusalCode` is a closed union of string literals, or omitted for an
+      operation that never refuses. The one route of the app takes `@Body() request: OperationRequest<Table>` and answers
+      `Promise<OperationReply<Table>>` of the same table; the wire is `{ operation, requestId, input }` in and `{ operation, requestId,
+      outcome }` out, `outcome` being the canon Outcome `{ kind: "ok", value }` or `{ kind: "refused", code }`. `starci app emit`
+      derives `be/contracts/<app>/openapi.json` (OpenAPI 3.1, `x-operation: "<name>@<version>"`, a oneOf over the operations) from the
+      table with the type checker, and the full `starci app check` fails when the committed file is stale.
+    rationale: |-
+      The operation set of an app is a contract the front end (`fe/`, through the root codegen) and other consumers generate a client from. A name-to-string registry with `unknown`
+      bodies and results forces every client to hand-type the wire; one typed table gives the client generator, the route and the
+      handlers the same types.
+    cases:
+      - id: case-1
+        when: A query with two refusals and a mutation with none
+        write: |-
+          // be/apps/core/src/operations.ts
+          export const OPERATIONS = defineOperations({
+              "sales.policy@1": query<SalesPolicyAsk, SalesPolicyView, "DENIED" | "INVALID">(),
+              "sales.close@1": mutation<SalesCloseAsk, SalesOpportunityView>(),
+          })
+          // features/api/sales/transport/http/operations.controller.ts
+          @Post("operations")
+          async invoke(@Body() request: OperationRequest<typeof OPERATIONS>): Promise<OperationReply<typeof OPERATIONS>> { ... }
+    verification:
+      automated:
+        - BE_OPERATION_CONTRACT
+        - BE_TRANSPORT_SHAPE
+        - HFS_CONTRACT_SNAPSHOT_DRIFT
+      manual:
+        - Confirm each refusal code is one the operation's owner can actually answer.
+    relatedExamples: [api]
+files:
+  - path: src/features/api/<feature>/index.ts
+    slot: be.feature
+    role: The public surface of the feature; only apps import it.
+    rules: [BE_PUBLIC_SURFACE]
+    template: api/feature.index.ts.tpl
+  - path: src/features/api/<feature>/<feature>.module.ts
+    slot: be.feature
+    role: Composes the application handlers.
+    template: api/feature.module.ts.tpl
+  - path: src/features/api/<feature>/application/<action>.command.ts
+    slot: be.feature.application
+    role: One command (or `.query.ts`) carrying one `params` field.
+    template: api/application.command.ts.tpl
+  - path: src/features/api/<feature>/application/<action>.handler.ts
+    slot: be.feature.application
+    role: Overrides `process` and calls the domain service of its context.
+    template: api/application.handler.ts.tpl
+  - path: src/features/api/<feature>/application/<action>.contracts.ts
+    slot: be.feature.application
+    role: The plain request and result types of the action.
+    template: api/application.contracts.ts.tpl
+  - path: src/features/api/<feature>/transport/graphql/<action>.resolver.ts
+    slot: be.transport.graphql
+    role: The GraphQL door of one operation; dispatches one message.
+    rules: [BE_TRANSPORT_SHAPE, BE_DEFAULT_DENY]
+    template: api/graphql.resolver.ts.tpl
+  - path: src/features/api/<feature>/transport/graphql/dto/<action>.input.ts
+    slot: be.transport.graphql
+    role: The bounded input of the operation.
+    rules: [BE_INPUT_BOUNDED]
+    template: api/graphql.input.ts.tpl
+  - path: src/features/api/<feature>/transport/graphql/dto/<action>.type.ts
+    slot: be.transport.graphql
+    role: The typed output of the operation.
+    template: api/graphql.type.ts.tpl
+  - path: src/features/api/<feature>/transport/graphql/<action>.mapper.ts
+    slot: be.transport.graphql
+    role: Maps the input to the request and the result to the type.
+    template: api/graphql.mapper.ts.tpl
+  - path: src/features/api/<feature>/transport/graphql/<feature>-graphql.module.ts
+    slot: be.transport.graphql
+    role: One module for the whole GraphQL transport of the feature.
+    template: api/graphql.module.ts.tpl
+  - path: src/features/api/<feature>/transport/http/<action>.controller.ts
+    slot: be.transport.http
+    role: A REST door, only where GraphQL cannot serve (health, byte streams, the operation route).
+    optional: true
+    rules: [BE_TRANSPORT_SHAPE, BE_DEFAULT_DENY]
+  - path: src/features/api/<feature>/transport/http/<feature>-http.module.ts
+    slot: be.transport.http
+    role: One module for the whole HTTP transport of the feature.
+    optional: true
+  - path: src/features/api/<feature>/messages/<feature>.messages.ts
+    slot: be.feature.messages
+    role: The keyed vi and en text of the feature.
+    optional: true
+  - path: contracts/<app>/schema.graphql
+    slot: be.contract.graphql
+    role: The emitted GraphQL snapshot of the app; a stale file fails the full check.
+    optional: true
+  - path: src/tests/e2e/<area>/<action>.e2e-spec.ts
+    slot: be.tests.e2e
+    role: The operation on the booted app, refusal and unauthenticated call included.
+    optional: true

package/runtime/knowledge/patterns/be/cli.yaml

@@ -0,0 +1,297 @@
+schema: starci/knowledge-source@1
+id: be.cli
+title: Backend cli
+purpose: |-
+  Given a one-off action (migrate, seed, sync, backup, an operator command), where does it live and how is it written? Every
+  one-off action is a nest-commander command of the cli feature root `be/src/features/cli/`, compiled into the one cli app
+  `be/apps/cli` and shipped as one image run as `cli <group> <command>`. A command is an action runner: thin (R203
+  `BE_FEATURE_THIN`) like every other feature file — it maps the command line and makes one delegating call into the
+  modules — and it still owes its unit spec beside it (the `cli` role of `ruleParams.be.unitRoles`). Its slot is
+  `coverage: none`, so a command is never a coverage target.
+appliesTo:
+  - backend
+family: be
+# The slot ids this topic teaches (knowledge/hfs/slots.yaml); scripts/gates/read-digest.mjs inverts these
+# into the READ-step slot -> pattern-topic map (knowledge/op-gate.yaml kinds), each slot's topics in index.yaml order.
+slots: [be.app.cli, be.cli]
+pattern: cli
+provenance:
+  reviewedAt: 2026-10-02
+  sources:
+    - knowledge/hfs/README.md
+    - knowledge/hfs/slots.yaml
+    - knowledge/hfs/rules.yaml
+    - owner decision 2026-10-02 (one cli app on nest-commander; features grouped by trigger kind)
+    - https://docs.nestjs.com/recipes/nest-commander
+  limitations: |-
+    Static checks prove where a command is declared, how the cli app boots, that every command has its spec beside it and
+    that nothing else parses the command line. They do not prove that a migration or a seed is right for live data, that a
+    deploy runs the migrate command first and once, or that an operator command is safe to re-run; the command's spec, the
+    test world's migration run and the deploy review prove those.
+rules:
+  - id: BE-CLI-1
+    title: One cli app boots nest-commander and never serves
+    kind: mandatory
+    hfsRules: [R147, R148]
+    requirement: |-
+      Every one-off action of a back end runs in ONE app, `be/apps/cli` (slot `be.app.cli`, kind `cli`, named `cli`). It is
+      required as soon as the back end declares a connection in `hfs.json` `sides.be.connections` (its migrations run as
+      `cli migrate run`) or tracks a command under `src/features/cli/`, and it tracks its image `be/apps/cli/Dockerfile`: one
+      image, run as `cli <group> <command>`. `apps/cli/src/main.ts` boots with `CommandFactory.run(AppModule, logger)` of
+      nest-commander and never serves: no `NestFactory.create*`, no `.listen()`, no microservice connection, no
+      `@nestjs/platform-*` adapter and no `@nestjs/microservices`. `apps/cli/src/app.module.ts` composes the platform modules
+      the commands need (the database capability over every connection with its entities and migrations, like an api app) and
+      the static cli feature root module `CliModule`; `apps/cli/src/cli.options.ts` carries what the cli reads from the
+      environment, the connections it migrates among them.
+    rationale: |-
+      One image for every operator action gives one place to find, deploy and audit them, and a process that never listens
+      cannot become a second, unguarded door into the application.
+    cases:
+      - id: case-1
+        when: The cli entry
+        write: |-
+          // be/apps/cli/src/main.ts
+          async function bootstrap(): Promise<void> {
+              await CommandFactory.run(AppModule.register(parseCliOptions(EnvSource.fromProcess())), new JsonLinesLogger())
+          }
+          void bootstrap()
+      - id: case-2
+        when: The cli app calls `NestFactory.createApplicationContext` or `app.listen()`
+        write: 'Refused (BE_CLI_BOOTSTRAP): the cli app boots only through CommandFactory.run.'
+      - id: case-3
+        when: A back end declares a connection and has no apps/cli
+        write: 'Refused (BE_CLI_REQUIRED): add be/apps/cli with main.ts, app.module.ts, cli.options.ts and its Dockerfile, declared as { "name": "cli", "kind": "cli" } in hfs.json sides.be.apps.'
+    verification:
+      automated:
+        - BE_CLI_REQUIRED
+        - BE_CLI_BOOTSTRAP
+      manual:
+        - Confirm the deploy runs the cli image as a job and never as a long-running service.
+    relatedExamples: []
+  - id: BE-CLI-2
+    title: Commands live in the cli feature root as groups and sub-commands
+    kind: mandatory
+    hfsRules: [R149]
+    requirement: |-
+      A nest-commander command (`@Command` or `@SubCommand`) is declared only in the cli feature root `src/features/cli/`
+      (slot `be.cli`). The root holds `index.ts` and `cli.module.ts` and one folder per group: `<group>/<group>.cli.ts` (the
+      group `@Command` with its `subCommands`), `<group>/<group>.module.ts` and `<group>/subs/<name>.cli.ts` (a `@SubCommand`
+      class extending `CommandRunner`), one command per file. The cli feature root is a feature, so every module of it is a
+      static `@Module({ imports, providers })` with no module definition, no options file and no `register`: `CliModule`
+      imports each group module and a group module provides its commands. A command makes its one delegating call on an
+      injected runner service of the modules (the migrate and seed runners of `platform/database`) and takes its options
+      from a nest-commander `@Option` of its own (`cli seed run --env <name>`). The suffix is
+      `.cli.ts`, because `.command.ts` is the CQRS message (api.yaml).
+    rationale: |-
+      A fixed group and sub-command layout maps the command line `cli <group> <command>` to one file path, so an operator
+      command and its spec are found from the name alone.
+    cases:
+      - id: case-1
+        when: The migrate group
+        write: |-
+          // be/src/features/cli/migrate/migrate.cli.ts
+          @Command({ name: "migrate", subCommands: [RunCli], description: "Schema migrations of every connection" })
+          /** The migrate group; without a sub-command it shows its help. */
+          export class MigrateCli extends CommandRunner {
+              async run(): Promise<void> { this.command.help() }
+          }
+      - id: case-2
+        when: A `@SubCommand` declared in src/modules/platform/database/reindex.cli.ts or in features/api/
+        write: 'Refused (BE_CLI_COMMAND_SHAPE, BE_CLI_OWNER): move it to src/features/cli/<group>/subs/reindex.cli.ts and register it in the group module.'
+    verification:
+      automated:
+        - BE_CLI_COMMAND_SHAPE
+      manual: []
+    relatedExamples: []
+  - id: BE-CLI-3
+    title: A command is an action runner with its own unit spec
+    kind: mandatory
+    hfsRules: [R149, R47, R102, R203]
+    requirement: |-
+      A cli command is thin (R203 `BE_FEATURE_THIN`) like every other file of a feature-tier slot: `run` maps the command
+      line and makes one delegating call into the modules (a service, a platform capability or a modules function), with no
+      branch, loop, `try`, `throw` or computation. As an action runner it is exempt from the transport-shape law R88 (the
+      `exempt` of the `cli` entry of `ruleParams.be.unitRoles`), and it still owes its unit spec `<name>.cli.spec.ts` beside
+      it, built like a service spec (test.yaml BE-TEST-2), which asserts the delegation. The slot `be.cli` is
+      `coverage: none`, so a command is never a coverage target. A command never imports an api feature: what it shares
+      with a request lives in a domain capability (folder.yaml BE-FOLDER-2).
+    rationale: |-
+      An operator action runs against production data, often once; its delegation has no request path that an e2e run
+      exercises, so the unit spec is the only automatic proof that the command hands its inputs to the right module.
+    cases:
+      - id: case-1
+        when: A seed command
+        write: 'features/cli/seed/subs/demo.cli.ts (`@SubCommand({ name: "demo" })`, `DemoSeedCli extends CommandRunner`) reads its options and calls the seed runner of a platform or domain capability; demo.cli.spec.ts beside it asserts the delegation.'
+      - id: case-2
+        when: A command with no spec
+        write: 'Refused (BE_CLI_COMMAND_SHAPE, unit-test-colocated): features/cli/db/subs/backup.cli.ts without backup.cli.spec.ts beside it.'
+    verification:
+      automated:
+        - BE_CLI_COMMAND_SHAPE
+        - BE_TEST_TOPOLOGY
+        - BE_CONTRACT_UNGUARDED
+        - BE_SPEC_PLACEMENT
+        - BE_FEATURE_THIN
+      manual:
+        - Confirm a command that writes is safe to re-run or refuses a second run explicitly.
+    relatedExamples: []
+  - id: BE-CLI-4
+    title: Only the cli parses the command line
+    kind: mandatory
+    hfsRules: [R150]
+    requirement: |-
+      `nest-commander` is imported only by `be/apps/cli` and `src/features/cli/`. No back-end source parses command-line
+      arguments itself: `process.argv` and the parsers `commander`, `yargs` and `minimist` are refused everywhere, the cli
+      included. A one-off action anywhere but a cli command is a door this rule closes.
+    rationale: |-
+      A flag read in an api app's main.ts or a script beside the source is an operator door no review sees and no spec
+      covers.
+    cases:
+      - id: case-1
+        when: An api main.ts reads `process.argv.includes("--seed")` to seed before listening
+        write: 'Refused (BE_CLI_OWNER): the seed is `cli seed demo`, run as its own job.'
+    verification:
+      automated:
+        - BE_CLI_OWNER
+      manual: []
+    relatedExamples: []
+  - id: BE-CLI-5
+    title: Migrations and seeds run only as cli commands
+    kind: mandatory
+    hfsRules: [R34, R147]
+    requirement: |-
+      Migrations run only through the cli migrate command (`cli migrate run`) and through the test world over the same
+      connection list (`cli.options.ts`); `starci gate run --root <app>` verifies that path. Seed data never sits in a
+      migration: it is a sub-command of the `seed` group. Api and worker apps neither migrate nor seed (persistence.yaml
+      BE-PERSISTENCE-2).
+    rationale: |-
+      One runner per connection removes the race of two processes migrating, and one list shared with the test world makes
+      the tested schema the deployed one.
+    cases:
+      - id: case-1
+        when: The migrate command
+        write: 'features/cli/migrate/subs/run.cli.ts (`@SubCommand({ name: "run" })`, `RunCli extends CommandRunner`) makes one call on `MigrationRunnerService` of `platform/database`, which migrates every connection in order and fails the process on the first error; run.cli.spec.ts beside it.'
+      - id: case-2
+        when: A module runs `dataSource.runMigrations()` at boot of an api app
+        write: 'Refused (BE_SCHEMA_AUTHORITY): only the cli and the test world run migrations.'
+    verification:
+      automated:
+        - BE_SCHEMA_AUTHORITY
+        - BE_CLI_REQUIRED
+      manual:
+        - Confirm the deploy runs `cli migrate run` to completion before the api and worker apps start.
+    relatedExamples: []
+files:
+  - path: apps/cli/Dockerfile
+    slot: repo.app-image
+    optional: true
+    role: the one cli image, run as `cli <group> <command>`
+    rules:
+      - BE_CLI_REQUIRED
+  - path: apps/cli/src/main.ts
+    slot: be.app.cli
+    optional: true
+    role: CommandFactory.run(AppModule, logger); never serves
+    rules:
+      - BE_CLI_BOOTSTRAP
+      - BE_ENTRYPOINT_ONLY_IN_APPS
+  - path: apps/cli/src/app.module.ts
+    slot: be.app.cli
+    optional: true
+    role: composes the platform modules and CliModule; no business code
+    rules:
+      - BE_APP_COMPOSITION_ONLY
+      - BE_CLI_BOOTSTRAP
+  - path: apps/cli/src/cli.options.ts
+    slot: be.app.cli
+    optional: true
+    role: what the cli reads from the environment, the connection list it migrates among them
+    rules:
+      - BE_CLI_REQUIRED
+      - BE_SCHEMA_AUTHORITY
+  - path: src/features/cli/index.ts
+    slot: be.cli
+    optional: true
+    role: exports CliModule to the cli app
+    rules:
+      - BE_PUBLIC_SURFACE
+  - path: src/features/cli/cli.module.ts
+    slot: be.cli
+    optional: true
+    role: the static cli feature root module; imports each group module
+    rules:
+      - BE_CLI_COMMAND_SHAPE
+      - BE_MODULE_SHAPE
+  - path: src/features/cli/migrate/migrate.cli.ts
+    slot: be.cli
+    optional: true
+    role: the migrate group @Command and its subCommands
+    rules:
+      - BE_CLI_COMMAND_SHAPE
+      - BE_CLI_OWNER
+    spec: src/features/cli/migrate/migrate.cli.spec.ts
+  - path: src/features/cli/migrate/migrate.module.ts
+    slot: be.cli
+    optional: true
+    role: "the static migrate group module: provides its command and sub-commands"
+    rules:
+      - BE_CLI_COMMAND_SHAPE
+      - BE_MODULE_SHAPE
+  - path: src/features/cli/migrate/subs/run.cli.ts
+    slot: be.cli
+    optional: true
+    role: "`cli migrate run`: one delegating call on the migration runner of `platform/database`, the one runner of the schema"
+    rules:
+      - BE_CLI_COMMAND_SHAPE
+      - BE_SCHEMA_AUTHORITY
+    spec: src/features/cli/migrate/subs/run.cli.spec.ts
+  - path: src/features/cli/seed/seed.cli.ts
+    slot: be.cli
+    optional: true
+    role: the seed group @Command and its subCommands
+    rules:
+      - BE_CLI_COMMAND_SHAPE
+      - BE_CLI_OWNER
+    spec: src/features/cli/seed/seed.cli.spec.ts
+  - path: src/features/cli/seed/seed.module.ts
+    slot: be.cli
+    optional: true
+    role: "the static seed group module: provides its command and sub-commands"
+    rules:
+      - BE_CLI_COMMAND_SHAPE
+      - BE_MODULE_SHAPE
+  - path: src/features/cli/seed/subs/run.cli.ts
+    slot: be.cli
+    optional: true
+    role: "`cli seed run [--env <name>]`: one delegating call on the seed runner of `platform/database`"
+    rules:
+      - BE_CLI_COMMAND_SHAPE
+    spec: src/features/cli/seed/subs/run.cli.spec.ts
+  - path: src/features/cli/<group>/<group>.cli.ts
+    slot: be.cli
+    role: the group @Command and its subCommands
+    template: cli/group.cli.ts.tpl
+    rules:
+      - BE_CLI_COMMAND_SHAPE
+      - BE_CLI_OWNER
+  - path: src/features/cli/<group>/<group>.cli.spec.ts
+    slot: be.cli
+    role: the unit spec of the group, beside it
+    template: cli/group.cli.spec.ts.tpl
+  - path: src/features/cli/<group>/<group>.module.ts
+    slot: be.cli
+    role: "the static group module: provides its command and sub-commands"
+    template: cli/group.module.ts.tpl
+    rules:
+      - BE_CLI_COMMAND_SHAPE
+      - BE_MODULE_SHAPE
+  - path: src/features/cli/<group>/subs/run.cli.ts
+    slot: be.cli
+    role: the first sub-command of the group; one delegating call on the injected runner service
+    template: cli/sub.run.cli.ts.tpl
+    rules:
+      - BE_CLI_COMMAND_SHAPE
+  - path: src/features/cli/<group>/subs/run.cli.spec.ts
+    slot: be.cli
+    role: the unit spec of the sub-command, beside it
+    template: cli/sub.run.cli.spec.ts.tpl