@starci/hfs 4.0.8 → 4.0.9

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

@@ -0,0 +1,221 @@
+schema: starci/knowledge-source@1
+id: be.feature.webhooks
+title: Provider webhooks
+purpose: |-
+  Given a delivery a payment, identity or shipping provider POSTs to us, how is it received? A webhook is a feature KIND:
+  `be/src/features/webhooks/<provider>/` holds one signed door that proves the delivery came from the provider (signature and
+  replay window), then hands it to exactly ONE domain intake method. That method records the delivery (deduplicated through the
+  inbox) and publishes the domain event with `eventBus.publish(event, tx)` inside its own transaction, because publishing is
+  allowed only from `modules/domain`. The door writes nothing and decides nothing; everything after the proof is an event.
+appliesTo:
+  - backend
+family: be
+provenance:
+  reviewedAt: 2026-10-02
+  sources:
+    - knowledge/hfs/README.md
+    - knowledge/hfs/slots.yaml
+    - knowledge/hfs/rules.yaml
+    - knowledge/patterns/be/api-auth.yaml
+    - knowledge/patterns/be/idempotency.yaml
+    - owner decision 2026-10-02 (feature kinds: webhooks, realtime, reactors, saga, jobs, cli; no kind imports another)
+  limitations: |-
+    Static checks prove the door's shape, that the proof is its first statement and that the only thing it can call after it is
+    one domain service method. They do not prove the HMAC scheme matches the provider's documentation, that the replay window
+    is the right length or that the intake is idempotent; the provider fake of the test world and the three
+    `webhooks/*` scenarios prove those against the real stack.
+rules:
+  - id: BE-WEBHOOK-1
+    title: A webhook is a kind folder with one door, its module and its own spec
+    kind: mandatory
+    hfsRules: [R01, R02, R47]
+    requirement: |-
+      A provider webhook lives in `be/src/features/webhooks/<provider>/` (slot `be.feature.webhooks`), enabled by declaring the pattern
+      `webhooks` in `hfs.json` `sides.be.patterns`. The folder holds `index.ts` (the module class an app composes), `transport/http/<provider>-http.module.ts`, `transport/http/<provider>.webhook.ts` (the
+      door), `<provider>.webhook.spec.ts` (its spec — the kind's door has no service of its own, so the door carries it) and an optional `transport/http/dto/` of typed
+      payload classes (`<event>.request.ts`). Nothing else exists there: no application layer, no handler, no consumer. The kind
+      imports only `modules/*`, never another kind, and only an api-kind app composes `<provider>-http.module.ts`.
+    rationale: |-
+      A webhook is an external caller we do not control, so its door is kept apart from the api features a client uses. One place
+      and one shape let a reader find every public signed door and its proof in one folder.
+    cases:
+      - id: case-1
+        when: A new provider (a payment gateway)
+        write: 'features/webhooks/payment-gateway/ with index.ts, transport/http/payment-gateway-http.module.ts, transport/http/payment-gateway.webhook.ts, transport/http/payment-gateway.webhook.spec.ts and transport/http/dto/payment-notification.request.ts.'
+    verification:
+      automated:
+        - HFS_SLOT_UNDECLARED
+        - HFS_SLOT_AMBIGUOUS
+        - HFS_SLOT_NOT_ENABLED
+        - HFS_FORBIDDEN_PRESENT
+        - HFS_TRACKED_MUST_BE_IGNORED
+        - HFS_ROOT_ENTRY_FORBIDDEN
+        - HFS_ROOT_MARKDOWN_FORBIDDEN
+        - HFS_ROOT_SRC_FORBIDDEN_FE
+        - HFS_SRC_LAYOUT_INVALID
+        - HFS_MODULE_TIER_INVALID
+        - HFS_WORK_IN_FE
+        - HFS_STACKS_IN_SIDE
+        - HFS_SLOT_REQUIRED_MISSING
+        - HFS_MIN_INSTANCES
+        - HFS_REQUIRED_FILE_MISSING
+        - HFS_ROOT_ENTRY_MISSING
+        - HFS_APPS_REQUIRED
+        - HFS_APP_LAYOUT_INVALID
+        - HFS_README_TITLE_INVALID
+        - HFS_README_DESCRIPTION_INVALID
+        - HFS_README_SECTION_MISSING
+        - HFS_README_SECTION_ORDER
+        - HFS_README_DEVELOPMENT_INCOMPLETE
+        - HFS_README_WORK_POINTER_MISSING
+        - HFS_README_PRIVATE_URL
+        - HFS_README_BADGE_NOT_LIVE
+        - BE_TEST_TOPOLOGY
+        - BE_CONTRACT_UNGUARDED
+      manual:
+        - Confirm the provider endpoint is one door and that a second endpoint of the same provider is a second door only when it has a different proof.
+    relatedExamples: [webhooks]
+  - id: BE-WEBHOOK-2
+    title: The door verifies first, then makes one domain call
+    kind: mandatory
+    hfsRules: [R182, R183, R41, R42, R203]
+    requirement: |-
+      `<provider>.webhook.ts` is one `@Controller` with one `@Post` handler declared
+      `@Public({ reason: PublicReason.SignedWebhook })`, thin (R203 `BE_FEATURE_THIN`). The handler's FIRST statement is the unconditional
+      `this.<signature>.verify({ provider, rawBody, signature, timestamp })` of the `WebhookSignatureService` of `platform/http-security`
+      (HMAC-SHA256 over `<timestamp>.<raw body>` with the provider's secret, a constant-time comparison and a replay window on the signed timestamp; it throws before anything else runs). The provider key and its secret and tolerance are options of `platform/http-security` (`options.webhooks[provider]`). The
+      second and last call is one method of a domain service, the intake. The door injects only that service and the signature
+      service (injected with `@InjectWebhookSignature()`), holds no branch, loop or `try`, calls nothing else (no parsing, mapping or publishing) and returns nothing: the
+      provider gets its status code and an empty body. `@RateLimit(RateTier.Strict)` is required by the signed-webhook reason.
+    rationale: |-
+      The signature is the authentication of a public door. Making the proof the first statement removes every path to the intake
+      that skips it, and a door with one call and no decision has nothing left to test except the proof and the hand-over.
+    cases:
+      - id: case-1
+        when: The door of a payment gateway
+        write: |-
+          @Controller("webhooks/payment-gateway")
+          export class PaymentGatewayWebhook {
+              constructor(
+                  @InjectWebhookSignature() private readonly signature: WebhookSignatureService,
+                  private readonly payments: PaymentService,
+              ) {}
+
+              @Post()
+              @HttpCode(HttpStatus.NO_CONTENT)
+              @Public({ reason: PublicReason.SignedWebhook })
+              @RateLimit(RateTier.Strict)
+              async receive(@Req() request: RawBodyRequest<Request>, @Headers("x-signature") signature: string | undefined, @Headers("x-timestamp") timestamp: string | undefined, @Body() body: PaymentNotificationRequest): Promise<void> {
+                  this.signature.verify({ provider: "payment-gateway", rawBody: request.rawBody, signature, timestamp })
+                  await this.payments.acceptNotification(body)
+              }
+          }
+      - id: case-2
+        when: A delivery whose raw body must be hashed
+        write: 'enable the raw body for the app (`NestFactory.create(..., { rawBody: true })` in the api app) and read `request.rawBody`; never hash a re-serialized `body`.'
+    verification:
+      automated:
+        - BE_WEBHOOK_SHAPE
+        - BE_WEBHOOK_UNVERIFIED
+        - BE_DEFAULT_DENY
+        - BE_INPUT_BOUNDED
+        - BE_FEATURE_THIN
+      manual:
+        - Review that the raw body, not a re-serialized one, is verified, and that the replay window matches the provider's tolerance.
+    relatedExamples: [webhooks]
+  - id: BE-WEBHOOK-3
+    title: The intake publishes the event inside its own transaction
+    kind: mandatory
+    hfsRules: [R80, R152, R151]
+    requirement: |-
+      The domain intake method (`PaymentService.acceptNotification`) is the delivery method of R80: its first awaited expression
+      claims `(source, eventId)` in the `Inbox` and it returns when the claim answers false, so a redelivery is a no-op. It then
+      records the delivery and calls `this.eventBus.publish(PaymentConfirmedEvent.create({...}), manager)` inside the same
+      transaction (`entityManager.transaction`). The events are typed classes in `modules/events/<service>/<event>.event.ts` that
+      equal their `be/contracts/<service>/events.json` entry (`payment.confirmed`, `payment.failed`). The webhook door never
+      imports `modules/events` or the event bus.
+    rationale: |-
+      Recording the delivery and writing the outbox row in one transaction means a crash cannot lose or duplicate the event, and
+      keeping the publish in `modules/domain` keeps one place that owns the transaction boundary.
+    cases:
+      - id: case-1
+        when: A confirmed payment arrives
+        write: 'acceptNotification claims the inbox row, updates the payment row and publishes PaymentConfirmedEvent in one transaction; a second delivery of the same eventId changes nothing.'
+    verification:
+      automated:
+        - BE_INBOX_DEDUPE_MISSING
+        - BE_OUTBOX_WRITE_TX
+        - BE_EVENT_CLASS_CONTRACT
+      manual:
+        - Confirm each provider event kind maps to exactly one published event and that an unknown kind is acknowledged and ignored, not published.
+    relatedExamples: [webhooks]
+  - id: BE-WEBHOOK-4
+    title: Three behaviours are proven on the test world
+    kind: mandatory
+    hfsRules: [R155]
+    requirement: |-
+      Declaring the pattern `webhooks` requires e2e or integration tests titled `webhooks/<scenario>: ...` for each scenario
+      `bad-signature-is-refused` (a tampered body is refused and nothing is published), `replay-is-refused` (a stale timestamp is
+      refused and nothing is published) and `accepted-delivery-publishes-once` (a valid delivery publishes the event once and a
+      redelivery publishes nothing more). The provider is the network-edge fake of the test world (`world.fake.<provider>`), which
+      signs with the test secret; a real provider is never called. The unit spec `<provider>.webhook.spec.ts` covers the door
+      itself with the Nest testing module, a real `WebhookSignatureService` configured with a test secret and a double of the
+      domain service.
+    rationale: |-
+      The door has no logic of its own, so the risk is in the wiring: the raw body, the headers, the real signature scheme and the
+      transaction behind the intake. Only a signed request through the real app proves it.
+    cases:
+      - id: case-1
+        when: The e2e of the payment gateway
+        write: 'e2e/payment/payment-gateway-webhook.e2e-spec.ts has `it("webhooks/bad-signature-is-refused: ...")`, `it("webhooks/replay-is-refused: ...")` and `it("webhooks/accepted-delivery-publishes-once: ...")`.'
+    verification:
+      automated:
+        - BE_PATTERN_SPEC_MISSING
+      manual:
+        - Confirm the fake signs exactly as the provider documents and that a contract spec guards its payload fixtures.
+    relatedExamples: [webhooks]
+files:
+  - path: src/features/webhooks/<provider>/index.ts
+    slot: be.feature.webhooks
+    template: webhooks/webhook.index.ts.tpl
+    role: The public surface of the kind folder, the module class an api-kind app composes.
+  - path: src/features/webhooks/<provider>/transport/http/<provider>-http.module.ts
+    slot: be.feature.webhooks.http
+    template: webhooks/webhook.http.module.ts.tpl
+    role: Nest module of the door, composed only by an api-kind app.
+  - path: src/features/webhooks/<provider>/transport/http/<provider>.webhook.ts
+    slot: be.feature.webhooks.http
+    template: webhooks/webhook.door.ts.tpl
+    role: The signed door, one controller with one POST handler.
+    rules: [BE_WEBHOOK_SHAPE, BE_WEBHOOK_UNVERIFIED, BE_DEFAULT_DENY, BE_INPUT_BOUNDED]
+    spec: src/features/webhooks/<provider>/transport/http/<provider>.webhook.spec.ts
+  - path: src/features/webhooks/<provider>/transport/http/<provider>.webhook.spec.ts
+    slot: be.feature.webhooks.http
+    template: webhooks/webhook.door.spec.ts.tpl
+    role: Unit spec of the door beside it.
+  - path: src/features/webhooks/<provider>/transport/http/dto/<event>.request.ts
+    slot: be.feature.webhooks.dto
+    role: The typed, bounded provider payload.
+    rules: [BE_INPUT_BOUNDED]
+    template: webhooks/webhook.request.ts.tpl
+  - path: src/modules/platform/http-security/webhook-signature.service.ts
+    slot: be.platform
+    role: WebhookSignatureService, the one owner of the signature and replay proof.
+    spec: src/modules/platform/http-security/webhook-signature.service.spec.ts
+    optional: true
+  - path: src/modules/domain/<capability>/<capability>.service.ts
+    slot: be.domain
+    role: The intake method, which claims the inbox and publishes the event in its transaction.
+    rules: [BE_INBOX_DEDUPE_MISSING, BE_OUTBOX_WRITE_TX]
+    optional: true
+  - path: src/modules/events/<service>/<event>.event.ts
+    slot: be.events
+    role: The typed event the intake publishes.
+    rules: [BE_EVENT_CLASS_CONTRACT]
+    optional: true
+  - path: src/tests/e2e/<area>/<provider>-webhook.e2e-spec.ts
+    slot: be.tests.e2e
+    role: "Titles webhooks/<scenario>: ... prove the pattern against the provider fake."
+    spec: webhooks/bad-signature-is-refused, webhooks/replay-is-refused, webhooks/accepted-delivery-publishes-once
+    rules: [BE_PATTERN_SPEC_MISSING]
+    optional: true

package/runtime/knowledge/patterns/fe/folder.yaml

@@ -23,14 +23,16 @@ rules:
   - id: FE-FOLDER-1
     title: Responsibility directories
     kind: mandatory
-    hfsRules: [R01, R02, R59, R64]
+    hfsRules: [R01, R02, R59, R64, R26, R54, R56, R91, R94]
     requirement: |
-      The front end of every app (`fe/`) is an fe/apps/<app>/ monorepo even with one app, named by its role (for example
-      web), and all product source lives under fe/apps/<app>/src. An fe/src/ does not exist. Each Next source root
+      The front end of every app (`fe/`) is an fe/apps/<app>/ monorepo even with one app — each app declared in
+      `hfs.json` `sides.fe.apps` with kind `next` (slot `fe.app.next`; the scaffold writes `landing` and `app`) — and all
+      product source lives under fe/apps/<app>/src. An fe/src/ does not exist. Each Next source root
       (fe/apps/<app>/src) uses app/ for framework adapters; features/{pages,layouts,overlays} for route-facing product
       composition; components/{blocks,composites,branches,leaves} for product visuals; hooks/<domain> for React hooks;
-      and modules/<capability> for cohesive reusable technical and domain capabilities. Every app has the modules api,
-      config, i18n and routes, and one brand.css under modules/brand when it sets brand tokens. No other empty role
+      and modules/<capability> for cohesive reusable technical and domain capabilities. Every app carries the required
+      module instances of slot `fe.modules` and one brand.css under modules/brand when it sets brand tokens
+      (`fe.modules.brand`). No other empty role
       folder is required. Grammar remains a separate product-agnostic package. The only files that may sit directly in the
       source root (the directory holding app/) are the framework-pinned root files listed in frameworkPinnedRootFiles
       below: Next.js loads them from that exact place. Each is a thin framework adapter whose internal imports enter
@@ -46,9 +48,8 @@ rules:
       # keep is decided by the slot fe.source-root-pinned and FE_NEXT_CONVENTIONS, not by this list.
       # Machine list read by scripts/hfs/architecture/framework-pinned.mjs (FE_SOURCE_LAYOUT_INVALID
       # accepts exactly these basenames directly in a Next source root;
-      # their imports follow the FE_TIER_DIRECTION matrix). Exact names, case-sensitive, no globs. Supervisor rulings for nivo
-      # wf-nivo-fe-debt-mug06w7h inc-2e42a24b74e4 and inc-846867b9a34e (proxy is the Next 16 name of
-      # middleware, listed so the list survives the upgrade).
+      # their imports follow the FE_TIER_DIRECTION matrix). Exact names, case-sensitive, no globs. Supervisor rulings
+      # (proxy is the Next 16 name of middleware, listed so the list survives the upgrade).
       - middleware.ts
       - middleware.js
       - middleware.mjs
@@ -82,7 +83,7 @@ rules:
           fe/apps/<app>/src/modules/api/ or fe/apps/<app>/src/modules/session/ with one explicit public index.ts entry
       - id: case-3
         when: "A reusable product visual without scenario ownership"
-        write: "fe/apps/<app>/src/components/{blocks,composites,branches,leaves}/<Name>/index.tsx"
+        write: "an owner folder of slot `fe.components` under the layer it belongs to — for example fe/apps/<app>/src/components/leaves/<Name>/index.tsx"
       - id: case-4
         when: "A React hook"
         write: "fe/apps/<app>/src/hooks/<domain>/useAutoScroll.ts; built-in React hook calls may remain in visuals"
@@ -94,7 +95,7 @@ rules:
           fe/apps/<app>/src/modules/i18n/ and the adapter imports it; the names the framework mandates there
           (frameworkPinnedRootExports, for example export const config = { matcher }) keep their framework spelling
       - id: case-6
-        when: "Any other file or folder directly under the source root (fe/apps/<app>/src/i18n/request.ts, fe/apps/<app>/src/config.ts), and an fe/src/"
+        when: "Any other file or folder directly under the source root (an `i18n/request.ts` or a `config.ts` there), and an fe/src/"
         write: >
           Move it to its owner, for example fe/apps/<app>/src/modules/i18n/request.ts, and point framework configuration
           (fe/apps/<app>/next.config.ts) at the new path
@@ -106,13 +107,53 @@ rules:
     verification:
       automated:
         - HFS_SLOT_UNDECLARED
+        - HFS_SLOT_AMBIGUOUS
+        - HFS_SLOT_NOT_ENABLED
+        - HFS_FORBIDDEN_PRESENT
+        - HFS_TRACKED_MUST_BE_IGNORED
+        - HFS_ROOT_ENTRY_FORBIDDEN
+        - HFS_ROOT_MARKDOWN_FORBIDDEN
+        - HFS_ROOT_SRC_FORBIDDEN_FE
+        - HFS_SRC_LAYOUT_INVALID
+        - HFS_MODULE_TIER_INVALID
+        - HFS_WORK_IN_FE
+        - HFS_STACKS_IN_SIDE
         - HFS_SLOT_REQUIRED_MISSING
-        - FE_SOURCE_LAYOUT_INVALID
-        - FE_NEXT_CONVENTIONS
+        - HFS_MIN_INSTANCES
+        - HFS_REQUIRED_FILE_MISSING
+        - HFS_ROOT_ENTRY_MISSING
+        - HFS_APPS_REQUIRED
+        - HFS_APP_LAYOUT_INVALID
+        - HFS_README_TITLE_INVALID
+        - HFS_README_DESCRIPTION_INVALID
+        - HFS_README_SECTION_MISSING
+        - HFS_README_SECTION_ORDER
+        - HFS_README_DEVELOPMENT_INCOMPLETE
+        - HFS_README_WORK_POINTER_MISSING
+        - HFS_README_PRIVATE_URL
+        - HFS_README_BADGE_NOT_LIVE
+        - FE_I18N_PLACEMENT
+        - FE_I18N_NAVIGATION
+        - FE_I18N_FORMATTER
+        - FE_APP_ISOLATION
+        - BE_TIER_DIRECTION
         - FE_TIER_DIRECTION
+        - ARCH_PACKAGE_IMPORTS_APP
+        - FE_ROUTE_FILES_THIN
+        - FE_NEXT_CONVENTIONS
+        - FE_PAGE_METADATA_MISSING
+        - FE_ROUTE_ONE_PAGE
+        - FE_ROUTE_DRAWING_DECISION
+        - FE_ROUTE_CLIENT_BOUNDARY
+        - FE_ROUTE_CLIENT_HOOK
+        - FE_ROUTE_DEFAULT_EXPORT
+        - FE_HOOKS_ARE_HOOKS
         - FE_CUSTOM_HOOK_LOCATION
-        - HFS_APPS_REQUIRED
-        - HFS_ROOT_SRC_FORBIDDEN_FE
+        - FE_BLOCK_PRODUCT_HOOK_DEFINITION
+        - FE_COMPONENT_DEEP_HOOK_IMPORT
+        - FE_SOURCE_FORM
+        - FE_SOURCE_LAYOUT_INVALID
+        - FE_SLOT_FILE_ROLE
       manual:
         - Confirm the unit's responsibility and public entry, rather than assigning it by consumer count.
     relatedExamples:
@@ -121,7 +162,7 @@ rules:
   - id: FE-FOLDER-2
     title: Discoverable files for one unit
     kind: mandatory
-    hfsRules: [R02, R55, R65]
+    hfsRules: [R02, R55, R65, R20, R92]
     requirement: |
       A split unit (a connected block, and a feature page, layout or overlay) uses index.tsx for the connected X and
       sibling component.tsx for the pure XBase, its XBaseProps and xDefaultState, plus XState when the shape is its own union
@@ -149,12 +190,40 @@ rules:
         write: "hooks/<domain>/useX.ts or modules/<capability>/...; do not create visual twins"
     verification:
       automated:
-        - class-names-in-colocated-file
-        - no-inline-class-name
-        - FE_CONNECTED_BLOCK_RENDER_PAIR
+        - HFS_SLOT_REQUIRED_MISSING
+        - HFS_MIN_INSTANCES
+        - HFS_REQUIRED_FILE_MISSING
+        - HFS_ROOT_ENTRY_MISSING
+        - HFS_APPS_REQUIRED
+        - HFS_APP_LAYOUT_INVALID
+        - HFS_README_TITLE_INVALID
+        - HFS_README_DESCRIPTION_INVALID
+        - HFS_README_SECTION_MISSING
+        - HFS_README_SECTION_ORDER
+        - HFS_README_DEVELOPMENT_INCOMPLETE
+        - HFS_README_WORK_POINTER_MISSING
+        - HFS_README_PRIVATE_URL
+        - HFS_README_BADGE_NOT_LIVE
+        - FE_CLIENT_BOUNDARY
+        - FE_CLIENT_SERVER_IMPORT
+        - FE_CLIENT_REACHES_SERVER
+        - FE_SERVER_ONLY_MARK
+        - FE_STORAGE_OUTSIDE_MODULES
+        - FE_DANGEROUS_HTML
         - FE_SIZE_AND_STATE_BUDGET
+        - FE_LIST_KEY
+        - FE_EFFECT_CLEANUP
+        - FE_SWALLOWED_ERROR
+        - FE_CONSOLE_CALL
         - HFS_SIZE_GROWTH
-        - starci-fe/base-import-pair
+        - HFS_SIZE_SOFT_BACKLOG
+        - FE_COMPONENT_API
+        - FE_COMPONENT_WORLD_OWNERSHIP
+        - FE_WORLD_OWNER_RENDER_BOUNDARY
+        - FE_CONNECTED_BLOCK_RENDER_PAIR
+        - FE_PURE_REACHES_DATA
+        - FE_PURE_WORLD_HOOK
+        - FE_PURE_WORLD_IMPORT
       manual:
         - Confirm each file owns a real responsibility; do not add a component.tsx twin by habit.
     relatedExamples:
@@ -163,7 +232,7 @@ rules:
   - id: FE-FOLDER-3
     title: Route files adapt to one visual owner and every app has its boundaries
     kind: mandatory
-    hfsRules: [R53, R54, R55, R57]
+    hfsRules: [R53, R54, R55, R57, R26]
     requirement: |
       Route files under app/[locale]/ (page, layout, template, loading, not-found) are server components. A route may
       resolve framework server inputs (params, searchParams, headers, cookies), then mounts one page-level visual owner.
@@ -192,10 +261,27 @@ rules:
     verification:
       automated:
         - FE_ERROR_BOUNDARY_MISSING
+        - FE_SUSPENSE_NULL_FALLBACK
         - FE_ROUTE_FILES_THIN
+        - FE_NEXT_CONVENTIONS
+        - FE_PAGE_METADATA_MISSING
+        - FE_ROUTE_ONE_PAGE
+        - FE_ROUTE_DRAWING_DECISION
+        - FE_ROUTE_CLIENT_BOUNDARY
+        - FE_ROUTE_CLIENT_HOOK
+        - FE_ROUTE_DEFAULT_EXPORT
         - FE_CLIENT_BOUNDARY
+        - FE_CLIENT_SERVER_IMPORT
+        - FE_CLIENT_REACHES_SERVER
+        - FE_SERVER_ONLY_MARK
+        - FE_STORAGE_OUTSIDE_MODULES
+        - FE_DANGEROUS_HTML
         - FE_OWNER_REACHABLE
+        - FE_ROUTE_HARDCODED
+        - FE_HREF_RESOLVES
+        - BE_TIER_DIRECTION
         - FE_TIER_DIRECTION
+        - ARCH_PACKAGE_IMPORTS_APP
       manual:
         - Confirm visual routes have one page owner and redirect-only routes have no visual tree.
     relatedExamples: []
@@ -203,7 +289,7 @@ rules:
   - id: FE-FOLDER-4
     title: Hooks are hooks; readers and transport live in modules
     kind: mandatory
-    hfsRules: [R56, R50, R49]
+    hfsRules: [R56, R50, R49, R21, R26]
     requirement: |
       hooks/<domain>/ holds React hooks (use*.ts, one hook per file) and exactly one <domain>.shared.ts for shared
       non-hook helpers of that domain (key builders, token readers). A file in hooks/ that is not a hook and is not the shared
@@ -235,8 +321,19 @@ rules:
       automated:
         - FE_HOOKS_ARE_HOOKS
         - FE_CUSTOM_HOOK_LOCATION
+        - FE_BLOCK_PRODUCT_HOOK_DEFINITION
+        - FE_COMPONENT_DEEP_HOOK_IMPORT
+        - FE_TRANSPORT_OWNER
+        - FE_EFFECT_FETCH
+        - FE_SWR_KEY_IDENTITY
+        - FE_SWR_MUTATION_RESOURCE_IDENTITY
+        - FE_ENV_OWNER
         - HFS_DUPLICATE_CODE
+        - HFS_DUPLICATE_SYMBOL
+        - FE_CROSS_APP_DUPLICATE
+        - BE_TIER_DIRECTION
         - FE_TIER_DIRECTION
+        - ARCH_PACKAGE_IMPORTS_APP
       manual:
         - Confirm each lifecycle has one feature owner and transport mechanics have one module owner.
     relatedExamples:
@@ -274,7 +371,7 @@ rules:
   - id: FE-FOLDER-6
     title: Keep units cohesive
     kind: mandatory
-    hfsRules: [R49, R21]
+    hfsRules: [R49, R21, R91, R92]
     requirement: |
       A unit folder contains files that change for the same responsibility. Do not create generic helpers/ or utils/
       buckets inside components, read deployment configuration in presentation, or split files solely to meet a count.
@@ -301,9 +398,18 @@ rules:
     verification:
       automated:
         - FE_ENV_OWNER
-        - class-names-in-colocated-file
-        - no-inline-class-name
-        - no-helper-folder-in-components
+        - HFS_DUPLICATE_CODE
+        - HFS_DUPLICATE_SYMBOL
+        - FE_CROSS_APP_DUPLICATE
+        - FE_SOURCE_FORM
+        - FE_SOURCE_LAYOUT_INVALID
+        - FE_COMPONENT_API
+        - FE_COMPONENT_WORLD_OWNERSHIP
+        - FE_WORLD_OWNER_RENDER_BOUNDARY
+        - FE_CONNECTED_BLOCK_RENDER_PAIR
+        - FE_PURE_REACHES_DATA
+        - FE_PURE_WORLD_HOOK
+        - FE_PURE_WORLD_IMPORT
       manual:
         - Confirm extraction is justified by ownership or lifecycle rather than file length or count.
     relatedExamples: []

package/runtime/knowledge/sonar-gate.yaml

@@ -13,16 +13,16 @@ purpose: |
   vulnerability, every hotspot reviewed, no duplicated-lines excess, no cognitive-complexity issue). The one Sonar
   mechanism of the HFS canon is packages/hfs/README.md section "Sonar".
 gate:
-  name: starci-new-code
-  # A project with no new-code baseline judges the whole project as new code (nivo inc-f92febebbb64); a fixed
+  name: starci-quality
+  # A project with no new-code baseline judges the whole project as new code; a fixed
   # window keeps "new code" the recent work on main, so the server gate is passable on a healthy main.
   newCodePeriod: {type: NUMBER_OF_DAYS, value: 30}
 newCode:
-  # Coverage of the services only. The be unit run writes coverage/lcov.info (@starci/jest-preset coverageReporters lcov) and the
+  # Coverage of the measured logic files only (the `ruleParams.be.logicRoles` roles of the `coverage: required` slots). The be unit run writes coverage/lcov.info (@starci/jest-preset coverageReporters lcov) and the
   # managed sonar-project.properties imports it (sonar.javascript.lcov.reportPaths=be/coverage/lcov.info) with
-  # sonar.coverage.exclusions = the complement of be/src/**/*.service.ts (SonarQube has no coverage inclusions), rendered by hfs sync from the preset's COVERAGE_SOURCES and the slot manifest (codecov.yml
-  # is rendered from the same constant). A handler, resolver, controller, module, config file or test is not a coverage target and
-  # fe/ is outside coverage entirely, so coverage on these conditions is the services' coverage alone.
+  # sonar.coverage.exclusions = the complement of the measured files (SonarQube has no coverage inclusions), rendered by starci app sync from the one derivation scripts/hfs/coverage-scope.mjs (be/jest.config.js and codecov.yml
+  # are rendered from it too; a hand edit of any of them is R204 HFS_COVERAGE_SCOPE_DRIFT). The feature tier, declaration files, tests and
+  # fe/ are never coverage targets, so coverage on these conditions is the coverage of the modules' logic alone.
   coverage:
     metric: new_coverage
     minPercent: 100
@@ -40,11 +40,11 @@ newCode:
     metric: new_security_hotspots_reviewed
     minReviewedPercent: 100
     unreviewedMax: 0
-# The whole code, not only the new code. Every finding of the HFS canon reaches Sonar through ONE entry, `hfs lint`
+# 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), which writes ONE file, reports/lint.sonar.json
-# (`npm run lint -- --sonar reports/lint.sonar.json`), named by sonar.externalIssuesReportPaths; the gate holds the open-issue count of
+# (`starci app lint --sonar 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 `hfs check` (managed files, tree, pins, CI, contracts; the rule id is the finding code)
+#   starci-hfs   the repository findings of `starci app check` (managed files, tree, pins, CI, contracts; the rule id is the finding code)
 #   eslint       ESLint's json over the repository (the BE and FE canon plugins alike, per-file and project-graph rules)
 #   stylelint    stylelint's json over the style glob (front ends)
 # The engines share ONE placement rule (a finding on a file Sonar does not index is filed on the first source file); Sonar's own
@@ -63,9 +63,9 @@ overall:
   hotspots:
     metric: security_hotspots_reviewed
     minReviewedPercent: 100
-  # The services' coverage (see newCode.coverage), overall and per file: with the inclusions in place each `*.service.ts` is its
-  # own measure, so one service below 100 fails the slice verdict (sonar-local evaluateSlice) and the dashboard verdict
-  # (sonar-local dashboard) although the project average may round to 100. A file outside the inclusions is never read.
+  # The measured files' coverage (see newCode.coverage), overall and per file: with the exclusions in place each measured file is its
+  # own measure, so one measured file below 100 fails the slice verdict (sonar-local evaluateSlice) and the dashboard verdict
+  # (sonar-local dashboard) although the project average may round to 100. A file outside the scope is never read.
   coverage:
     metric: coverage
     minPercent: 100
@@ -81,6 +81,40 @@ overall:
   cognitiveComplexity:
     rule: typescript:S3776
     via: overall.issues
+# Lite is the same quality policy without a test or coverage world. Readers select this block from hfs.json edition;
+# keeping both gates in this document makes every threshold data, never a branch-local restatement.
+lite:
+  gate:
+    name: starci-quality-lite
+    newCodePeriod: {type: NUMBER_OF_DAYS, value: 30}
+  newCode:
+    ignoreBelowChangedLines: 20
+    duplication:
+      metric: new_duplicated_lines_density
+      maxPercent: 3
+    issues:
+      blockingSeverities: [BLOCKER, CRITICAL]
+      metrics: {BLOCKER: new_blocker_violations, CRITICAL: new_critical_violations}
+      max: 0
+    hotspots:
+      metric: new_security_hotspots_reviewed
+      minReviewedPercent: 100
+      unreviewedMax: 0
+  overall:
+    issues:
+      metric: violations
+      max: 0
+      engines: [starci-hfs, eslint, stylelint]
+      types: {bugs: BUG, code_smells: CODE_SMELL, vulnerabilities: VULNERABILITY}
+    hotspots:
+      metric: security_hotspots_reviewed
+      minReviewedPercent: 100
+    duplication:
+      metric: duplicated_lines_density
+      maxPercent: 3
+    cognitiveComplexity:
+      rule: typescript:S3776
+      via: overall.issues
 # The Sonar enforcers of the rule catalog (knowledge/hfs/rules.yaml): the failure code each condition above is the gate of.
 enforces:
   - {rule: R20, code: HFS_SIZE_GROWTH, enforcer: cognitive-complexity, condition: cognitiveComplexity}
@@ -91,19 +125,19 @@ enforcedOps: [backend.implement, interface.implement, code.refactor]
 reasoning: |
   Chosen against the four projects the local server holds on 2026-09-29 (whole-project duplicated lines
   1.6 / 2.1 / 1.7 / 0.0 percent), so new code that meets them is at or below what main already carries.
-  coverage 100 on services, overall and new code (owner 2026-10-01): the unit project already fails below its per-file
-  100 threshold on `*.service.ts`; Sonar imports the same run's lcov with the same scope, so the dashboard, the slice
-  verdict and the server gate show the number the runner enforces, file by file. Only services count: business logic
-  lives there, the thin layers are covered through them, and the front end has no unit tests.
+  coverage 100 on the measured logic files, overall and new code (owner 2026-10-01): the unit project already fails below its per-file
+  100 threshold on the `ruleParams.be.logicRoles` files of the `coverage: required` slots; Sonar imports the same run's lcov with the same scope, so the dashboard, the slice
+  verdict and the server gate show the number the runner enforces, file by file. Only the modules' logic counts: business logic
+  lives there, the feature tier is thin (R203) and proven by integration and e2e, and the front end has no unit tests.
   duplication 3: the Sonar way value; the worst project today is 2.1, so 3 rejects a real copy-paste block and
   passes ordinary work.
   blocker/critical 0: the two severities that are defects, not style. main carries old debt of both kinds
-  (nivo-backend 3 blocker, 137 critical), so the SLICE verdict reads only changed lines and never main's backlog;
+  (one product repository carries 3 blocker and 137 critical), so the SLICE verdict reads only changed lines and never main's backlog;
   major and lower are reported on the summary and never fail a slice.
   overall issues 0 and overall duplication 3: the server gate is also the owner's definition of done for the HFS canon:
   a repository that carries any open ESLint, stylelint or HFS finding is not green, whatever the age of the line. The
   op slice keeps judging changed lines (an op cannot fix a repository's whole backlog); the dashboard and CI show the
-  whole-project condition. Adopting a repository therefore means clearing its imported findings, which `hfs check`,
+  whole-project condition. Adopting a repository therefore means clearing its imported findings, which `starci app check`,
   eslint and stylelint already demand at land.
   hotspots 0 unreviewed: a hotspot is a question the author must answer; on changed lines it is answered in the
   same slice.