@starci/eslint-canon-be 2.0.1 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 2.1.0 - 2026-10-01
+
+- New: the `project-graph` law: the TS-attached architecture checks (tiers, owners, dead exports, composition, data, paths) as eslint rules at error on the offending line, from one cached project graph per lint run.
+- New: `spec-exact-values` (R48): `expect.any(String|Number|Date)` in a `*.service.spec.ts` is refused; ids come from `fakeIds()` and dates from `FakeClock` and are asserted exactly.
+
+- Changed: Back-end apps have no composition spec, including the migrate app. `unit-test-colocated` has no app exception; only service unit specs and the integration, e2e and contract layers remain.
+
 ## 2.0.1 - 2026-10-01
 
 - Fixed: `e2e-asserts-persisted-state` accepts `<world>.db.<connection>` and `<world>.services.<name>.api` state reads, the world identified by its `TestWorld` type (from `@starci/test-world` or the `be.tests.world` slot), not by a variable name.
@@ -8,6 +15,7 @@
 
 - Changed (lane PORT): `ruleParams.be.infraOwners` names `@nestjs/cache-manager` (the `CACHE_MANAGER` token) beside `cache-manager`: it is reached only by `integrations/cache` and `integrations/redis`, which is the retired repository rule `must-use-cache-service`; `infra-import-owner` (R90) covers it with a passing and a violating case.
 - Changed (lane UT): `inbox-dedupe-required` (R80) moves from the door to the service. It judges the public methods of a `*.service.ts` whose first parameter TYPE has an `eventId` property: the first awaited expression must be `claim(source, eventId, ...)` on the `Inbox` port, with an early return on `false`. Consumers and `SignedWebhook` controllers are no longer judged by it, and `transport-is-thin` no longer allows an `Inbox` injection or an inbox guard in a door.
+- New `spec-exact-values` (R48, unit-spec law): a `*.service.spec.ts` never asserts `expect.any(String)`, `expect.any(Number)` or `expect.any(Date)` (`expect` resolved as the jest global or the `@jest/globals` import); ids come from `fakeIds()` and dates from `FakeClock`, so the spec asserts the exact value.
 - Changed: `transport-is-thin` allows `unwrapOutcome` of `platform/primitives` (resolved by its symbol) beside the bus call and pure mapper functions.
 - Fixed: `infra-needs-injector` (R85) no longer judges the constructor of a CQRS message (`extends Command<R>` / `Query<R>` of `@nestjs/cqrs`): its `params` is data built with `new`.
 - Changed (lane UT, unit-test standard 2026-09-30): `unit-test-colocated` (R47) no longer keeps twin specs for handlers, guards, mappers, policies, clients and row mappers. Only a service is unit-tested: a `<name>.service.ts` has its `<name>.service.spec.ts` beside it (message `missing`), a unit spec (a `*.spec.ts` outside `src/tests/{e2e,integration,contract,world}` and `apps/migrate`) must be a `<name>.service.spec.ts` beside its service (`notService`, `orphan`), and a composition spec is no longer a unit kind.

package/README.md

@@ -49,7 +49,7 @@ A sample, not the list:
 | **Log safety** | A call on the `Logger` port (found by the receiver's type) passes no `Secret` or `Pii` value and no value named like a credential or a personal identifier (`no-secret-in-log`) |
 | **Async and types** | An `async` function awaits; handlers and public methods declare a return type; no `Function` type, no `eval`; an inline object type takes a name; no `const enum`. Casts, `x!` and `any` are refused in every file, specs included, by the typescript-eslint rules the factory turns on (`async-needs-await`, `explicit-handler-return-type`, `no-function-or-eval`, `no-inline-param-type`, `no-inline-object-type`, `no-const-enum`) |
 | **Migrations and input** | A migration's `down()` reverses its `up()`; every property of an input class has the `class-validator` decorators its type calls for (string `@MaxLength`, enum `@IsEnum`, array `@ArrayMaxSize`, nested `@ValidateNested()` and `@Type`); reads page by cursor, never by `skip`, `offset` or `OFFSET` (`migration-down-reversible`, `input-bounded`, `no-offset-pagination`) |
-| **Spec quality** | A spec does not read repository source with `fs` (`spec-no-source-read`); the borrowed `consistent-type-assertions` (`never`) and `no-non-null-assertion` leave no `as` and no `x!` in a spec, and `no-ambient-clock` and `no-direct-env-read` cover specs, so no `Date.now()`, argless `new Date()` or `process.env`. A unit spec is `<name>.service.spec.ts`: it builds its subject with `Test.createTestingModule({ providers })` from `@nestjs/testing`, `.compile()` and `moduleRef.get(...)` (`spec-builds-with-testing-module`), never `new` on the service (`spec-no-new-subject`), no `imports` key and no `override*` (`spec-module-definition-only-providers`), no `jest.mock`/`doMock`/`unstable_mockModule`/`requireMock` of an own module or a library (`spec-no-module-mock`), no cast-laundering helper in a spec or fixture: a return-only generic, an `unknown` handed back as another type, `JSON.parse(JSON.stringify(x))`, `Object.assign(new X(), y)` returned as another type (`no-return-only-generic`); a provider `{ provide: TOKEN, useValue: X }` takes X from the matching `@starci/jest-preset` double, the token table being `ruleParams.be.specDoubles` of the slot manifest (`spec-infra-double-from-kit`); the EntityManager double is the kit's `mockEntityManager()`/`fakeTransaction()`, never ad hoc (`spec-typed-entity-manager`); test data goes through builders, see the **Test data builders** row |
+| **Spec quality** | A spec does not read repository source with `fs` (`spec-no-source-read`); the borrowed `consistent-type-assertions` (`never`) and `no-non-null-assertion` leave no `as` and no `x!` in a spec, and `no-ambient-clock` and `no-direct-env-read` cover specs, so no `Date.now()`, argless `new Date()` or `process.env`. A unit spec is `<name>.service.spec.ts`: it builds its subject with `Test.createTestingModule({ providers })` from `@nestjs/testing`, `.compile()` and `moduleRef.get(...)` (`spec-builds-with-testing-module`), never `new` on the service (`spec-no-new-subject`), no `imports` key and no `override*` (`spec-module-definition-only-providers`), no `jest.mock`/`doMock`/`unstable_mockModule`/`requireMock` of an own module or a library (`spec-no-module-mock`), no cast-laundering helper in a spec or fixture: a return-only generic, an `unknown` handed back as another type, `JSON.parse(JSON.stringify(x))`, `Object.assign(new X(), y)` returned as another type (`no-return-only-generic`); a provider `{ provide: TOKEN, useValue: X }` takes X from the matching `@starci/jest-preset` double, the token table being `ruleParams.be.specDoubles` of the slot manifest (`spec-infra-double-from-kit`); a unit spec asserts exact values, never `expect.any(String)`, `expect.any(Number)` or `expect.any(Date)` (`expect` being the jest global or the `@jest/globals` import): ids come from `fakeIds()` and dates from `FakeClock` (`spec-exact-values`); the EntityManager double is the kit's `mockEntityManager()`/`fakeTransaction()`, never ad hoc (`spec-typed-entity-manager`); test data goes through builders, see the **Test data builders** row |
 | **Test data builders** (R98 to R101) | Builders live only in `src/tests/fixtures/builders/<area>.builder.ts`: a module of the test tree that exports a function creating persisted rows through an EntityManager, DataSource or QueryRunner is a builder wherever it sits (`persisting-builder-in-builders-slot`, R98); a spec never runs a raw INSERT/UPDATE/DELETE or a direct write (`save`, `insert`, `upsert`, `update`, `delete`, `remove`) on a typeorm receiver and never builds the same `@Entity` class as an object literal twice (`spec-no-raw-insert`, `spec-no-repeated-row-literal`, R99); a builder never asserts and has deterministic defaults (`builder-arranges-only`, R101); nothing under `src/tests` disables or drops a constraint (`tests-keep-constraints`, R100) |
 | **CQRS** | A message extends `Command<R>` / `Query<R>` from `@nestjs/cqrs`, carries one `readonly params: ExecuteParams<X>` (no entity reachable from `X`), a handler extends `ICQRSHandler` and overrides `process`; a handler is thin: it injects only `*Service` classes and the Logger, and `process` is one `return this.<service>.<method>(...)` with no branch, loop, EntityManager or second call (`handler-is-thin`); no `*.use-case.ts`, no forwarder service, no `EventBus` or `@nestjs/event-emitter` (`handler-overrides-process`, `message-carries-params-only`, `message-typed-result`, `execute-params-shape`, `no-use-case`, `no-event-bus`) |
 | **Module layering** | Another owner is imported through its public `index.ts` (`@modules/domain/plan`, `@features/plan`), never through a path into it, and a same-owner import is relative and never through the own index (`import-owner-entry`); an owner has one `index.ts` (a nested one is refused) that holds only named `export { }` lines, with no `export *`, and a bounded number of names (`no-folder-reexport`); self-aliases and relative escapes are refused (`no-self-module-alias`, `no-relative-capability-escape`). Owners come from the HFS slots, aliases from the program's `compilerOptions.paths`. |

package/data-access.mjs

@@ -69,7 +69,7 @@ export const namedEntityManagerOnly = {
         schema: [],
         messages: {
             property:
-                "`{{type}}` is injected as a class property. Property injection hides the dependency from the constructor and from the composition spec. Receive the named-injector `EntityManager` as a constructor parameter.",
+                "`{{type}}` is injected as a class property. Property injection hides the dependency from the constructor and the app module. Receive the named-injector `EntityManager` as a constructor parameter.",
             infra:
                 "`{{type}}` is injected here. A `DataSource` or `QueryRunner` is built and held only by the platform database capability, the migrate app and the test world in `src/tests/world`; specs take `world.db.<connection>`; everything else injects the shared `EntityManager` through its named injector and calls it directly.",
             getRepository:

package/index.mjs

@@ -52,9 +52,11 @@ import { recommended as transportRecommended, rules as transportRules } from "./
 import { recommended as typeSafetyRecommended, rules as typeSafetyRules } from "./type-safety.mjs"
 import { recommended as unitSpecRecommended, rules as unitSpecRules } from "./unit-spec.mjs"
 import { recommended as userCopyRecommended, rules as userCopyRules } from "./user-copy.mjs"
+import { recommended as projectGraphRecommended, rules as projectGraphRules } from "./project-graph.mjs"
 
 /** Each law's contribution, kept separate so a duplicate name is detectable rather than silent. */
 const CONTRIBUTIONS = [
+    { law: "project-graph", rules: projectGraphRules, recommended: projectGraphRecommended },
     { law: "async-discipline", rules: asyncDisciplineRules, recommended: asyncDisciplineRecommended },
     { law: "authorization", rules: authorizationRules, recommended: authorizationRecommended },
     { law: "builders", rules: buildersRules, recommended: buildersRecommended },

package/lib/unit-spec.mjs

@@ -2,13 +2,13 @@
  * What is a unit spec, decided by the slot manifest and the file's role suffix, never by a path pattern.
  *
  * A unit spec is a `*.spec.ts` outside the folders that own the other test kinds (`src/tests/{e2e,integration,contract,world}`)
- * and outside `apps/migrate` (the migrate app's own specs). Only a `<name>.service.spec.ts` beside `<name>.service.ts` is a
+ * only. Only a `<name>.service.spec.ts` beside `<name>.service.ts` is a
  * legitimate unit spec (R47); the quality rules of R48 judge exactly those.
  */
 import { basename } from "node:path"
 
-/** The slots whose `*.spec.ts` files are not unit specs: the other test kinds and the migrate app. */
-const OTHER_KIND_SLOTS = new Set(["be.tests.e2e", "be.tests.integration", "be.tests.contract", "be.tests.world", "be.tests.world.kit", "be.app.migrate"])
+/** The slots whose `*.spec.ts` files are not unit specs: the other test kinds and world infrastructure. */
+const OTHER_KIND_SLOTS = new Set(["be.tests.e2e", "be.tests.integration", "be.tests.contract", "be.tests.world", "be.tests.world.kit"])
 
 /** The file name of a linted path. */
 export const baseOf = (filename) => basename(String(filename || "").replace(/\\/g, "/"))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/eslint-canon-be",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "The StarCi back-end lint canon: every rule its laws publish, gathered as one flat-config plugin.",
   "type": "module",
   "license": "UNLICENSED",

package/project-graph.mjs

@@ -0,0 +1,23 @@
+/**
+ * The rules that read the project graph: the findings of the architecture machine that sit on a TypeScript file.
+ *
+ * One graph per lint run: `scripts/lib/project-graph.mjs` (a byte copy in this package's runtime/) builds the machine's module
+ * graph and slot manifest once for the repository, caches it, and each rule below reports the findings of its own codes on
+ * the file ESLint is visiting, on the line the machine names. There is no second graph and no second judge: the list of
+ * rules and their codes is `LINT_ENFORCERS` of the machine (scripts/checks/architecture/surface.mjs); `hfs check` keeps the
+ * findings that have no TypeScript file to sit on. A graph that cannot be built stops the run with the machine's message.
+ */
+import { LINT_ENFORCERS } from "./runtime/scripts/checks/architecture/surface.mjs"
+import { projectRule } from "./runtime/scripts/lib/project-rule.mjs"
+import { hfsOf } from "./lib/hfs.mjs"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const RUNTIME = join(dirname(fileURLToPath(import.meta.url)), "runtime")
+const mine = LINT_ENFORCERS.filter((enforcer) => enforcer.plugins.includes("be"))
+
+/** The rules this law contributes to the plugin: one per graph enforcer of this profile. */
+export const rules = Object.fromEntries(mine.map((e) => [e.id, projectRule({ enforcer: e, runtimeRoot: RUNTIME, hfsOf })]))
+
+/** Every one at error. */
+export const recommended = Object.fromEntries(mine.map((e) => [`starci-be/${e.id}`, "error"]))

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

@@ -0,0 +1,309 @@
+schema: starci/knowledge-source@1
+id: fe.folder
+title: Folder
+purpose: |
+  Given a piece of frontend code, which directory and which file name does it get? Apply the HFS frontend tree
+  (knowledge/hfs/README.md section 6, slots fe.*).
+appliesTo:
+  - frontend
+family: fe
+provenance:
+  reviewedAt: 2026-09-29
+  sources:
+    - knowledge/hfs/README.md
+    - knowledge/hfs/slots.yaml
+    - https://nextjs.org/docs/app/getting-started/project-structure
+    - https://next-intl.dev/docs/routing
+    - packages/grammar/src/**
+  limitations: |
+    Folder rules place code by responsibility. They do not prove rendered behavior or accessibility. Inspect the
+    selected repository's actual source, manifests, aliases and lint and test configuration. Verify installed Grammar
+    exports at @starci/grammar/common.
+rules:
+  - id: FE-FOLDER-1
+    title: Responsibility directories
+    kind: mandatory
+    hfsRules: [R01, R02, R59, R64]
+    requirement: |
+      Every frontend repository is an apps/<app>/ monorepo even with one app, named by its role (for example web), and
+      all product source lives under apps/<app>/src. A repository-root src/ does not exist. Each Next source root
+      (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
+      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
+      modules or a feature public entry only; every other rule still applies to it, except that the export names the
+      framework mandates there (frameworkPinnedRootExports) keep their framework spelling. HFS uses proxy.ts for locale
+      routing; a middleware.* file is refused on Next 16 and later by the Next conventions check and the slot
+      fe.source-root-pinned, even though the machine list names it as a file Next loads. Any other file at the source
+      root, including a helper folder beside a pinned file, has no owner and is refused.
+    frameworkPinnedRootFiles:
+      # Machine list read by scripts/checks/architecture/framework-pinned.mjs (FE_SOURCE_LAYOUT_INVALID accepts exactly
+      # these basenames directly in a Next source root; FE_TIER_DIRECTION keeps them thin). Exact names,
+      # case-sensitive, no globs. It lists what the framework loads from the source root. Which of them a repository may
+      # keep is decided by the slot fe.source-root-pinned and FE_NEXT_CONVENTIONS, not by this list.
+      # Machine list read by scripts/checks/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).
+      - middleware.ts
+      - middleware.js
+      - middleware.mjs
+      - proxy.ts
+      - proxy.js
+      - proxy.mjs
+      - instrumentation.ts
+      - instrumentation.js
+      - instrumentation.mjs
+      - instrumentation-client.ts
+      - instrumentation-client.js
+      - instrumentation-client.mjs
+      - next-env.d.ts
+    frameworkPinnedRootExports:
+      # Export names the framework mandates in a pinned root file, keyed by file stem (read by
+      # scripts/checks/architecture/framework-pinned.mjs). FE_SOURCE_NAME_SHAPE accepts exactly these names in exactly
+      # these files when they sit directly in a Next source root; everywhere else the name-shape rule is unchanged.
+      middleware: [config, middleware, default]
+      proxy: [config, proxy, default]
+      instrumentation: [register, onRequestError]
+      instrumentation-client: [onRouterTransitionStart]
+    rationale: |
+      One fixed source root per app keeps every repository the same shape while preventing app helpers, component-local
+      hooks and feature-local transport buckets from becoming undeclared owners.
+    cases:
+      - id: case-1
+        when: "A routed authentication scenario"
+        write: "apps/<app>/src/features/pages/AuthenticationPage/index.tsx"
+      - id: case-2
+        when: "A reusable API client, reader or session capability"
+        write: >
+          apps/<app>/src/modules/api/ or apps/<app>/src/modules/session/ with one explicit public index.ts entry
+      - id: case-3
+        when: "A reusable product visual without scenario ownership"
+        write: "apps/<app>/src/components/{blocks,composites,branches,leaves}/<Name>/index.tsx"
+      - id: case-4
+        when: "A React hook"
+        write: "apps/<app>/src/hooks/<domain>/useAutoScroll.ts; built-in React hook calls may remain in visuals"
+      - id: case-5
+        kind: exception
+        when: "Next.js only loads the file from the source root (proxy, instrumentation, instrumentation-client, next-env.d.ts)"
+        write: >
+          apps/<app>/src/proxy.ts beside apps/<app>/src/app/ as a thin adapter; locale routing logic lives in
+          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 (apps/<app>/src/i18n/request.ts, apps/<app>/src/config.ts), and a repository-root src/"
+        write: >
+          Move it to its owner, for example apps/<app>/src/modules/i18n/request.ts, and point framework configuration
+          (apps/<app>/next.config.ts) at the new path
+      - id: case-7
+        when: "The per-slot data-status recipe"
+        write: >
+          apps/<app>/src/components/composites/SlotView/index.tsx, apps/<app>/src/modules/slot/index.ts (Slot, toSlot,
+          SlotLabels) and apps/<app>/src/hooks/slot/useSlotLabels.ts, one copy each (examples/shape-slot)
+    verification:
+      automated:
+        - HFS_SLOT_UNDECLARED
+        - HFS_SLOT_REQUIRED_MISSING
+        - FE_SOURCE_LAYOUT_INVALID
+        - FE_NEXT_CONVENTIONS
+        - FE_TIER_DIRECTION
+        - FE_CUSTOM_HOOK_LOCATION
+        - HFS_APPS_REQUIRED
+        - HFS_ROOT_SRC_FORBIDDEN_FE
+      manual:
+        - Confirm the unit's responsibility and public entry, rather than assigning it by consumer count.
+    relatedExamples:
+      - connected-block
+
+  - id: FE-FOLDER-2
+    title: Discoverable files for one unit
+    kind: mandatory
+    hfsRules: [R02, R55, R65]
+    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
+      (a shape that is a domain status is typed with that status, never a second name for it). Only that index.tsx and the
+      unit's specs import component.tsx. Pure blocks, composites, branches and leaves use index.tsx only and never gain an
+      empty twin. classNames.ts is present only when the unit owns class strings. Budgets: component.tsx 300 lines,
+      connected index.tsx 200 lines, at most 6 data hooks and 6 useState per connected unit.
+    rationale: |
+      Stable basenames make class, tests and the connected and presentational split discoverable without forwarding
+      twins, and budgets keep a unit reviewable.
+    cases:
+      - id: case-1
+        when: "Connected block with product-world lifecycle"
+        write: "blocks/CatalogBlock/{index.tsx,component.tsx}; every nonempty index render reaches the sibling"
+      - id: case-2
+        when: "Feature page, layout or overlay"
+        write: >
+          features/pages/OperatePage/{index.tsx,component.tsx,classNames.ts}, features/layouts/WorkspaceLayout/…,
+          features/overlays/SendHandoffOverlay/… (examples/shape-slot)
+      - id: case-3
+        when: "Single visual unit"
+        write: "leaves/ButtonStateSample/{classNames.ts,index.tsx}; no component.tsx twin without a separate world owner"
+      - id: case-4
+        when: "Custom hook or reusable module"
+        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
+        - FE_SIZE_AND_STATE_BUDGET
+        - HFS_SIZE_GROWTH
+        - starci-fe/base-import-pair
+      manual:
+        - Confirm each file owns a real responsibility; do not add a component.tsx twin by habit.
+    relatedExamples:
+      - connected-block
+
+  - 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]
+    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.
+      A route whose complete responsibility is redirect or notFound mounts none. A route file holds no inline component, no
+      drawing decision and no hook, and a redirect from an old URL lives in next.config redirects(), never in a page. Every app has
+      app/global-error.tsx, app/[locale]/layout.tsx, app/[locale]/error.tsx and app/[locale]/not-found.tsx, and a loading.tsx
+      for each route group that reads data. Each page exports generateMetadata. force-dynamic on a client page is forbidden.
+    rationale: |
+      Keeping default exports in the App Router layer prevents components from becoming route-coupled, and mandatory
+      boundaries turn a render failure into a recoverable screen instead of a blank page.
+    cases:
+      - id: case-1
+        when: "A route"
+        write: >
+          app/[locale]/authentication/page.tsx: const AuthenticationRoute = async () => <AuthenticationPage />, then export
+          default AuthenticationRoute
+      - id: case-2
+        kind: exception
+        when: "Redirect or notFound adapter"
+        write: "Resolve framework inputs and redirect or terminate without a visual owner."
+      - id: case-3
+        when: "Global app files"
+        write: >
+          app/globals.css, app/global-error.tsx, app/[locale]/error.tsx, app/[locale]/not-found.tsx, app/sitemap.ts,
+          app/robots.ts, app/health/{live,ready}/route.ts
+    verification:
+      automated:
+        - FE_ERROR_BOUNDARY_MISSING
+        - FE_ROUTE_FILES_THIN
+        - FE_CLIENT_BOUNDARY
+        - FE_OWNER_REACHABLE
+        - FE_TIER_DIRECTION
+      manual:
+        - Confirm visual routes have one page owner and redirect-only routes have no visual tree.
+    relatedExamples: []
+
+  - id: FE-FOLDER-4
+    title: Hooks are hooks; readers and transport live in modules
+    kind: mandatory
+    hfsRules: [R56, R50, R49]
+    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
+      file is a finding. Server-side readers (fetch and map, no React) live in modules/api/<domain>/read-*.ts and are
+      wrapped in React cache() when several blocks call them in one request. Generic client plumbing, the Outcome type,
+      the contract copy and generated wire types live in modules/api; environment reading lives in modules/config; every
+      href builder lives in modules/routes; locale routing lives in modules/i18n; colour values live in modules/brand.
+      A helper name defined twice across hook files is a finding.
+    rationale: |
+      A rule that says what a hooks folder is also says where everything else goes, so nobody copies a helper sixteen
+      times or fills hooks/ with server fetch functions.
+    cases:
+      - id: case-1
+        when: "Authentication request lifecycle"
+        write: "apps/<app>/src/hooks/authentication/useAuthentication.ts"
+      - id: case-2
+        when: "A helper shared by the hooks of one domain"
+        write: "apps/<app>/src/hooks/sales/sales.shared.ts, for example useSalesAccessToken's token reader"
+      - id: case-3
+        when: "A server read used by several blocks"
+        write: "apps/<app>/src/modules/api/sales/read-sales-summary.ts, exported through modules/api/index.ts"
+      - id: case-4
+        when: "The API client"
+        write: "apps/<app>/src/modules/api/client.ts and apps/<app>/src/modules/api/outcome.ts"
+      - id: case-5
+        when: "Intrinsic custom helper"
+        write: "apps/<app>/src/hooks/ui/useAutoScroll.ts; direct useRef and useState calls may remain in their visual owner"
+    verification:
+      automated:
+        - FE_HOOKS_ARE_HOOKS
+        - FE_CUSTOM_HOOK_LOCATION
+        - HFS_DUPLICATE_CODE
+        - FE_TIER_DIRECTION
+      manual:
+        - Confirm each lifecycle has one feature owner and transport mechanics have one module owner.
+    relatedExamples:
+      - connected-block
+
+  - id: FE-FOLDER-5
+    title: Package unit
+    kind: mandatory
+    hfsRules: [R63]
+    requirement: |
+      A shared package is packages/<pkg>/ with package.json (explicit exports), src/index.ts, tsconfig.json and colocated
+      specs, built to dist. Grammar components live under packages/grammar/src/core/<tier>/<Name>/ with collocated class
+      strings and specs; family entries and built-output proof stay at the package roots. See packages.yaml for the shared
+      UI package shape.
+    rationale: |
+      Package layout separates primitives from app composition and keeps public entry verification against dist.
+    cases:
+      - id: case-1
+        when: "A Grammar component"
+        write: "packages/grammar/src/core/<primitive|composite|branch|composition>/<Name>/index.tsx"
+      - id: case-2
+        when: "A Grammar component's class strings and spec"
+        write: "sibling classNames.ts and index.spec.tsx"
+      - id: case-3
+        when: "Built-output proof"
+        write: "common/index.test.mjs, core/index.test.mjs, package-boundary.test.mjs (node:test against dist/)"
+    verification:
+      automated:
+        - FE_PACKAGE_SHAPE
+      manual:
+        - Verify public app imports use @starci/grammar/common and installed exports, never the package root.
+    relatedExamples: []
+
+  - id: FE-FOLDER-6
+    title: Keep units cohesive
+    kind: mandatory
+    hfsRules: [R49, R21]
+    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.
+      Collocated subordinate renders and pure helpers are valid when they remain private to the owner; a separately stable
+      responsibility receives its own named owner.
+    rationale: |
+      Cohesion prevents helper sprawl and duplicated configuration while avoiding one-component-per-folder ceremony that
+      has no dependency boundary.
+    cases:
+      - id: case-1
+        when: "A small subordinate render is private to one owner"
+        write: "Keep it local with an unexported contract; extract it when it gains a stable public responsibility."
+      - id: case-2
+        when: "Class strings in component.tsx"
+        write: "Never; they go to classNames.ts (lint class-names-in-colocated-file, no-inline-class-name)"
+      - id: case-3
+        when: "A helpers/ or utils/ folder"
+        write: "Do not use it to hide mixed feature, transport or visual responsibilities."
+      - id: case-4
+        when: "A deployment constant"
+        write: >
+          Never. process.env.NEXT_PUBLIC_* is read only in apps/<app>/src/modules/config and reached through that module,
+          with no localhost fallback; a missing value in production throws when the module loads.
+    verification:
+      automated:
+        - FE_ENV_OWNER
+        - class-names-in-colocated-file
+        - no-inline-class-name
+        - no-helper-folder-in-components
+      manual:
+        - Confirm extraction is justified by ownership or lifecycle rather than file length or count.
+    relatedExamples: []