@starci/hfs 2.0.2 → 4.0.0

package/runtime/knowledge/sonar-gate.yaml

@@ -32,13 +32,14 @@ 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 pipeline
-# (packages/hfs, contract change hfs-sonar-import) and the gate holds the open-issue count of the whole project at zero:
-#   starci-hfs   `hfs check --sonar reports/hfs.sonar.json` (repository, managed-file and architecture-machine findings;
-#                the rule id is the finding code) -> sonar.externalIssuesReportPaths
-#   eslint       `eslint -f json -o reports/eslint.json` (the BE and FE canon plugins alike) converted by `hfs report eslint` -> sonar.externalIssuesReportPaths
-#   stylelint    `stylelint --formatter json` converted by `hfs report stylelint` -> sonar.externalIssuesReportPaths
-# The three imports share ONE placement rule (a finding on a file Sonar does not index is filed on the first source file); Sonar's own
+# The whole code, not only the new code. Every finding of the HFS canon reaches Sonar through ONE entry, `hfs 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
+# 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)
+#   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
 # ESLint import (sonar.eslint.reportPaths) is not used because it drops such issues.
 # A SonarQube gate condition cannot filter issues by engine, so the condition is the project's open issues (`violations`,
 # overall code): the three engines above are the imports it counts, and every native Sonar issue counts with them. That is

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

@@ -245,10 +245,9 @@ BE_APP_BUSINESS_ROLE:
 BE_APP_COMPOSITION_ONLY:
   title: "Composition root has stray source"
   title_vi: "Gốc ghép nối có tệp lạc chỗ"
-  meaning_vi: "Mã trong ứng dụng gốc không phải tệp mà slot ứng dụng cho phép (main.ts, app.module.ts, <app>.options.ts)."
+  meaning_vi: "Mã trong ứng dụng gốc không phải tệp mà slot ứng dụng cho phép (main.ts, app.module.ts, <app>.options.ts; operations.ts ở ứng dụng API)."
   causes_vi:
     - "Thêm tệp không đúng tên vào thư mục ứng dụng gốc"
-    - "Composition spec của app tự khai AppModule, import AppModule từ tệp khác app.module, hoặc không gọi AppModule.register( — module thật không bao giờ được khởi chạy"
   nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra; không cần ai can thiệp thêm."
   owner: op-retry
   kind: check-finding
@@ -445,6 +444,7 @@ BE_RAW_INJECT:
     - "Token là chuỗi thay vì unique symbol"
     - "Tiêm lớp hạ tầng (CacheService, AppLogger) không qua injector"
     - "Dùng ModuleRef.get hoặc forwardRef để né vòng phụ thuộc"
+    - "constructor(private readonly timeoutMs: number) {} hoặc ReadonlyMap<string, X> không có Inject<Thing>() gắn token có tên"
   nextStep_vi: "Khai báo token `export const THING: unique symbol = Symbol(\"<owner>.<thing>\")` và `export const InjectThing = (): TypedParameterDecorator<Thing> => injector<Thing>(THING)` trong <owner>.decorators.ts rồi dùng @InjectThing() ở mọi nơi; vòng phụ thuộc là lỗi kiến trúc cần gỡ, không dùng forwardRef. Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra và mục của luật trong BE-CONVENTION; không thêm ngoại lệ, không tắt luật."
   owner: op-retry
   kind: check-finding
@@ -484,8 +484,9 @@ BE_SCHEMA_OWNER:
 BE_SOURCE_FORM:
   title: "Back-end source file breaks the naming or form canon"
   title_vi: "Tệp nguồn BE sai quy ước tên hoặc hình thức"
-  meaning_vi: "Tên tệp phải là kebab-case với hậu tố vai trò trong danh sách đóng của slots.yaml; chỉ export có tên (không export default); mọi export và thành viên công khai có JSDoc tiếng Anh; không emoji, và không có chữ tiếng Việt trong định danh, chuỗi ký tự, chú thích hay tên test ngoài catalog messages/ và slot fixture i18n."
+  meaning_vi: "Tên tệp phải là kebab-case với hậu tố vai trò trong danh sách đóng của slots.yaml; chỉ export có tên (không export default); mọi export và thành viên công khai có JSDoc tiếng Anh; không emoji, và không có chữ tiếng Việt trong định danh, chuỗi ký tự, chú thích hay tên test ngoài catalog messages/ và slot fixture i18n; mã production không khai báo lớp, hàm hay hằng export có từ Mock, Fake hoặc Stub trong tên (đồ giả nằm trong spec hoặc src/tests; driver ngoại tuyến là adapter điều khiển bằng options, đặt tên theo việc nó làm)."
   causes_vi:
+    - "class MockExpertAgentService trong mã production thay vì adapter điều khiển bằng options"
     - "Tệp dùng hậu tố bị cấm (use-case, repository, store, util, helper, types, constants)"
     - "Lớp export không kết thúc bằng hậu tố vai trò của tệp và cũng không kết thúc bằng tên port (interface trong *.port.ts hoặc *.contracts.ts) mà nó implements"
     - "Interface trong tệp *.input.ts, *.request.ts, *.response.ts, *.type.ts, *.args.ts hoặc *.rows.ts không kết thúc bằng Input, Request, Response, Type, Args hoặc Row"
@@ -516,6 +517,7 @@ BE_SPEC_QUALITY:
     - "Spec chỉ có toHaveBeenCalled*, không khẳng định kết quả hay trạng thái"
     - "`it.skip`, `describe.skip`, `xit`, `it.todo`, `.skipIf`/`.runIf` hoặc `(cond ? describe : describe.skip)` trong spec; hãy viết test thật hoặc xóa nó, còn việc bỏ qua khi thiếu sandbox nằm trong contract helper của world (`sandbox.describe(...)`)"
     - "e2e gọi CommandBus, QueryBus hay handler trực tiếp; dùng sleep thay cho waitFor; tự gọi Test.createTestingModule; import SDK của nhà cung cấp mô hình; không đọc lại dòng đã lưu qua EntityManager"
+    - "Spec đơn vị của service khẳng định `expect.any(String)`, `expect.any(Number)` hoặc `expect.any(Date)` cho giá trị service tự sinh; service nhận bộ sinh id và đồng hồ qua token, spec cấp `fakeIds()` và `new FakeClock(...)` từ @starci/jest-preset rồi khẳng định đúng giá trị"
     - "Spec đơn vị của service có providers khác với phụ thuộc constructor: thừa nhà cung cấp, thiếu nhà cung cấp, service không đứng đầu, token không suy ra được hoặc nhà cung cấp không phải lớp hay { provide, useValue }"
   nextStep_vi: "Chuyển luật kiến trúc sang lint hoặc bộ kiểm tra; khẳng định kết quả hoặc trạng thái; e2e vào bằng transport thật, chờ bằng waitFor và dựng thế giới ở src/tests/e2e/setup. Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra."
   owner: op-retry
@@ -539,7 +541,7 @@ BE_TEST_TOPOLOGY:
   meaning_vi: "Cấu hình test lệch chuẩn: `<detail>`."
   causes_vi:
     - "Vi phạm luật R47: một `jest.config.js` (preset `@starci/jest-preset`) với bốn project `unit`, `integration`, `e2e`, `contract`; thư mục và hậu tố spec luôn khớp nhau; `diagnostics: false` + `isolatedModules: true`; `test:integration`, `test:e2e`, `test:contract` = `typecheck:tests && jest --selectProjects <tên>`; `src/tests/world/` là nơi duy nhất dựng hạ tầng test và chỉ chứa `global-setup.ts`, `global-teardown.ts`, `use-test-world.ts`, `fakes/` và file gốc có hậu tố vai trò (kể cả `test-world.config.ts`)."
-    - "Vi phạm luật R47 về stack thật: mọi dịch vụ khai trong `.starcistacks/<env>` (Postgres, Redis, Keycloak, mail host, k3s...) chạy THẬT trong world qua toxiproxy, world đọc dịch vụ và phiên bản image từ stack lúc chạy; `fakes/<provider>/` chỉ giả SaaS bên ngoài mà đội không vận hành. Ngoại lệ duy nhất: dịch vụ stateless cần phần cứng đặc biệt hoặc model bên ngoài (GPU inference, embedding tự host) được giả khi `test-world.config.ts` khai trong `fakedBy` với `reason` không rỗng; dịch vụ có trạng thái (database, cache, identity, storage, mail, queue, search hoặc có volume bền) không bao giờ được giả, và mục `fakedBy` trỏ tới dịch vụ hoặc thư mục fake không tồn tại bị coi là cũ."
+    - "Vi phạm luật R47 về stack thật: mọi dịch vụ khai trong `.starcistacks/<env>` (Postgres, Redis, Keycloak, mail host, k3s...) chạy THẬT trong world qua toxiproxy, world đọc dịch vụ và phiên bản image từ stack lúc chạy; `fakes/<provider>/` chỉ giả SaaS bên ngoài mà đội không vận hành. Ngoại lệ duy nhất: dịch vụ stateless cần phần cứng đặc biệt hoặc model bên ngoài (GPU inference, embedding tự host) được giả khi mục `stacks` của dịch vụ đó trong `test-world.config.ts` khai `{ fakedBy, reason }` với `reason` không rỗng; dịch vụ có trạng thái (database, cache, identity, storage, mail, queue, search hoặc có volume bền) không bao giờ được giả, và mục `fakedBy` trỏ tới dịch vụ hoặc fake (mục `fakes` hay thư mục `fakes/`) không tồn tại bị coi là cũ. `test-world.config.ts` khai world theo đúng một dạng export có tên `export const { useTestWorld, useSandbox } = defineTestWorld({...})` (`stack`, `stacks` theo từng dịch vụ, `fakes`); export default không được đọc và bị báo lỗi."
   nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra (nợ hàng loạt có codemod của HFS); không cần ai can thiệp thêm."
   owner: op-retry
   kind: check-finding
@@ -905,11 +907,11 @@ FE_TRANSPORT_OWNER:
   kind: check-finding
 
 FE_WIRE_GENERATED:
-  title: "Wire types generated from the contract copy"
+  title: "Wire types generated from the be contract snapshots the fe side reads"
   title_vi: "Kiểu wire gõ tay"
-  meaning_vi: "`<file>` tự gõ kiểu wire/ép kiểu phản hồi. Dùng kiểu sinh từ `contract/`."
+  meaning_vi: "`<file>` tự gõ kiểu wire/ép kiểu phản hồi, hoặc kiểu sinh ra cũ hơn ảnh chụp hợp đồng. Dùng kiểu sinh từ `be/contracts/`."
   causes_vi:
-    - "Vi phạm luật R52: Kiểu wire sinh từ bản hợp đồng (`codegen`); tài liệu GraphQL trong `.graphql`; cấm `as GraphqlResult<T>`; enum wire không phải `string`."
+    - "Vi phạm luật R52: Kiểu wire sinh từ ảnh chụp hợp đồng của be (`be/contracts/`, chạy `npm run codegen` ở gốc app); tài liệu GraphQL trong `.graphql`; cấm `as GraphqlResult<T>`; enum wire không phải `string`."
   nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra và mục của luật trong tiêu chuẩn HFS; nợ cũ cần quyết định thiết kế nên op không thêm ngoại lệ, chỉ tách hoặc chuyển về đúng chủ."
   owner: op-retry
   kind: check-finding
@@ -981,21 +983,21 @@ HFS_CANON_PIN_DRIFT:
   kind: check-finding
 
 HFS_CI_MISSING_CANON:
-  title: "CI runs the pinned `@starci/hfs check`; pre-push runs typecheck and lint"
+  title: "CI runs the pinned `hfs lint`; pre-push runs typecheck and lint"
   title_vi: "CI thiếu bước canon"
   meaning_vi: "Workflow/husky thiếu bước `<step>`. Cấu trúc chỉ được kiểm khi agent chạy — CI phải tự kiểm."
   causes_vi:
-    - "Vi phạm luật R13: CI phải chạy `npx @starci/hfs check` (bản pin); pre-push phải có `typecheck` + `lint:check`."
+    - "Vi phạm luật R13: CI phải chạy `hfs lint` (`npm run lint` hoặc `npx @starci/hfs lint`, bản pin); pre-push phải có `typecheck` + `lint`."
   nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra (nợ hàng loạt có codemod của HFS); không cần ai can thiệp thêm."
   owner: op-retry
   kind: check-finding
 
 HFS_CONTRACT_SNAPSHOT_DRIFT:
-  title: "Contract snapshot equals the emit, the FE copy equals the BE"
+  title: "The be side commits its contract snapshot and it equals the emit"
   title_vi: "Bản hợp đồng lệch bản thật"
-  meaning_vi: "Hợp đồng `<file>` lệch bản thật (`<sha>` ≠ `<sha>`). Chạy `npm run contract:emit` (BE) / `contract:pull` (FE) rồi commit kết quả. Nếu emit không chạy được thì finding nêu nguyên văn lỗi của emit; không bao giờ bỏ qua âm thầm."
+  meaning_vi: "Hợp đồng `<file>` lệch bản thật (`<sha>` ≠ `<sha>`). Chạy `npm run contract:emit` ở gốc app rồi commit kết quả. Nếu emit không chạy được thì finding nêu nguyên văn lỗi của emit; không bao giờ bỏ qua âm thầm."
   causes_vi:
-    - "Vi phạm luật R23: BE: `contracts/<app>/schema.graphql` và `contracts/<app>/openapi.json` (sinh từ bảng thao tác có kiểu `apps/<app>/src/operations.ts`) phải bằng bản `hfs emit-contracts` phát ra ngay lúc kiểm tra (đồ thị module đọc từ mã nguồn, không cần env, DB hay mạng); chỉ chạy ở lượt kiểm tra đầy đủ, `--fast` bỏ qua và nói rõ trong phần coverage. FE: `modules/api/contract/*` bằng bản BE (so hash)."
+    - "Vi phạm luật R23: phía be: `be/contracts/<app>/schema.graphql` và `be/contracts/<app>/openapi.json` (sinh từ bảng thao tác có kiểu `apps/<app>/src/operations.ts`) phải bằng bản `hfs emit-contracts` phát ra ngay lúc kiểm tra (đồ thị module đọc từ mã nguồn, không cần env, DB hay mạng); chỉ chạy ở lượt kiểm tra đầy đủ, `--fast` bỏ qua và nói rõ trong phần coverage. Phía fe đọc thẳng `be/contracts/` (đường đọc chéo duy nhất khai trong hfs.json `sides.fe.reads`), không giữ bản sao."
   nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra; không cần ai can thiệp thêm."
   owner: op-retry
   kind: check-finding
@@ -1141,27 +1143,6 @@ HFS_HOOKS_PATH_REDIRECTED:
   owner: op-retry
   kind: check-finding
 
-HFS_INIT_EXISTS:
-  title: "hfs.json already exists"
-  title_vi: "hfs.json đã có sẵn"
-  meaning_vi: "Lệnh hfs init không ghi đè bản khai báo đã có vì bản đó là quyết định của kho."
-  causes_vi:
-    - "Chạy hfs init trong kho đã có hfs.json"
-  nextStep_vi: "Sửa hfs.json trực tiếp, hoặc dùng hfs init --stdout để xem bản dò tự động rồi so sánh."
-  owner: op-retry
-  kind: verb-refusal
-
-HFS_INIT_UNDETECTED:
-  title: "Repository profile or apps not detected"
-  title_vi: "Không dò được loại kho hoặc ứng dụng"
-  meaning_vi: "Lệnh hfs init không xác định chắc chắn kho là backend hay frontend, hoặc không thấy ứng dụng nào dưới apps/ để khai báo, nên không đoán mò."
-  causes_vi:
-    - "Không có next hay @nestjs/core trong phụ thuộc, hoặc có cả hai"
-    - "Kho chưa có thư mục apps/<tên>/ (Nest cần thêm src/, Next cần next.config)"
-  nextStep_vi: "Tạo bố cục apps/<tên>/ theo chuẩn hoặc viết hfs.json bằng tay theo modules/schemas/hfs-repo.schema.yaml."
-  owner: op-retry
-  kind: verb-refusal
-
 HFS_LINT_SUPPRESSION_FILE:
   title: "A repository keeps no lint-suppression file, script or option"
   title_vi: "Kho có tệp hoặc script ghi nhận bỏ qua lỗi lint"
@@ -1238,6 +1219,16 @@ HFS_PACKAGE_MANAGER_MIXED:
   owner: other-op:backend.scaffold
   kind: check-finding
 
+HFS_PEER_INTEGRATION_MISSING:
+  title: "An app declares the runtime peer its driver integration needs"
+  title_vi: "Thiếu gói peer mà tích hợp driver cần khi chạy"
+  meaning_vi: "`package.json` ở gốc app phụ thuộc vào các gói của một cặp trong `knowledge/hfs/peer-integrations.yaml` (ví dụ `@nestjs/apollo` trên `@nestjs/platform-express` 11, tức Express 5) nhưng không khai báo gói `<requires>` trong dependencies, nên api không khởi động được."
+  causes_vi:
+    - "Vi phạm luật R111: npm không tự cài gói peer này, type-check và unit spec không nạp nó, nên lỗi chỉ lộ ra khi api khởi động (hai backend cũ thiếu `@as-integrations/express5` và api GraphQL không chạy được trên Express 5)."
+  nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra: thêm gói `<requires>` vào dependencies của `package.json` ở gốc app; không thêm ngoại lệ."
+  owner: op-retry
+  kind: check-finding
+
 HFS_PLAINTEXT_SECRET:
   title: "Secrets exist only as `.starcistacks/<env>/secrets/<slug>.enc`"
   title_vi: "Bí mật dạng rõ trong kho"
@@ -1283,7 +1274,7 @@ HFS_README_DESCRIPTION_INVALID:
 HFS_README_DEVELOPMENT_INCOMPLETE:
   title: "README Development section incomplete"
   title_vi: "Mục Development trong README chưa đủ lệnh"
-  meaning_vi: "Mục Development chưa nêu đủ các lệnh cài đặt, typecheck, lint:check, build và test (các script do hfs sync quản lý; test chạy bằng npm test)."
+  meaning_vi: "Mục Development chưa nêu đủ các lệnh cài đặt, typecheck, lint, build và test (các script do hfs sync quản lý; test chạy bằng npm test)."
   causes_vi:
     - "Quên một hoặc vài lệnh"
     - "Viết bằng lệnh của trình quản lý khác"
@@ -1413,7 +1404,7 @@ HFS_ROOT_MARKDOWN_FORBIDDEN:
   kind: check-finding
 
 HFS_ROOT_SRC_FORBIDDEN_FE:
-  title: "Root src folder in frontend repo"
+  title: "Root src folder in the front end (fe/)"
   title_vi: "Repo giao diện có thư mục src ở gốc"
   meaning_vi: "Repo giao diện có thư mục src ngay ở gốc, trong khi mã nguồn chỉ được đặt trong apps/<tên app>/src."
   causes_vi:
@@ -1433,18 +1424,6 @@ HFS_RULE_OFF_WITHOUT_REPLACEMENT:
   owner: op-retry
   kind: check-finding
 
-HFS_SIZE_GROWTH:
-  title: "Source file over the size budget grew"
-  title_vi: "Tệp mã nguồn vượt hạn mức dòng vẫn tiếp tục dài thêm"
-  meaning_vi: "Một tệp mã nguồn đã dài hơn hạn mức mềm của ruleParams.fileLines nhưng lại dài thêm so với phiên bản gốc của nhánh, hoặc một tệp mới tạo đã vượt hạn mức ngay từ đầu. Tệp quá dài khó đọc, khó sửa và là nơi lỗi dễ ẩn; quy tắc này cho phép tệp cũ đang quá dài được giữ nguyên hoặc thu nhỏ dần, nhưng không cho phép nó phình thêm."
-  causes_vi:
-    - "Op thêm mã mới vào một tệp vốn đã quá hạn mức thay vì tách phần mới sang tệp khác"
-    - "Một tệp đang dưới hạn mức được thêm mã cho đến khi vượt hạn mức"
-    - "Một tệp mới tạo dài hơn hạn mức, hoặc một tệp bị di chuyển sang đường dẫn mới nên bị coi là tệp mới"
-  nextStep_vi: "Op vừa tạo ra bản này sẽ được chạy lại để tách phần mã mới (hoặc bớt phần cũ) sang tệp riêng đúng ô của nó, sao cho tệp không dài hơn phiên bản gốc và tệp mới nằm trong hạn mức."
-  owner: op-retry
-  kind: check-finding
-
 HFS_SIZE_SOFT_BACKLOG:
   title: "Source file above the soft size"
   title_vi: "Tệp mã vượt cỡ mềm (chỉ báo cáo)"
@@ -1478,12 +1457,12 @@ HFS_SLOT_NOT_ENABLED:
   kind: check-finding
 
 HFS_SLOT_REQUIRED_MISSING:
-  title: "A slot is missing a required file (feature `index.ts`, app composition spec, FE `global-error.tsx`)"
+  title: "A slot is missing a required file (feature `index.ts`, app `main.ts`, FE `global-error.tsx`)"
   title_vi: "Ô thiếu tệp bắt buộc"
   meaning_vi: "Một ô bắt buộc (hoặc một thực thể của ô, như một ứng dụng hay một tính năng) đòi có tệp hoặc thư mục này nhưng nó không nằm trong những gì Git theo dõi."
   causes_vi:
-    - "Vi phạm luật R02: slot bắt buộc thiếu tệp `requires` (vd feature thiếu `index.ts`, app thiếu composition spec, FE thiếu `global-error.tsx`)."
-    - "Ứng dụng thiếu main.ts, app.module.ts hoặc spec ghép ứng dụng"
+    - "Vi phạm luật R02: slot bắt buộc thiếu tệp `requires` (vd feature thiếu `index.ts`, app thiếu `main.ts`, FE thiếu `global-error.tsx`)."
+    - "Ứng dụng thiếu main.ts hoặc app.module.ts"
     - "Kho thiếu tệp gốc bắt buộc như README.md, hfs.json, .starciwork, .starcistacks"
   nextStep_vi: "Tạo tệp hoặc thư mục theo mẫu của ô rồi commit; tệp chưa git add vẫn tính là thiếu. Op vừa tạo ra bản này sẽ được chạy lại để sửa theo lời nhắn của bộ kiểm tra; không cần ai can thiệp thêm."
   owner: op-retry
@@ -1525,7 +1504,7 @@ HFS_SRC_LAYOUT_INVALID:
   kind: check-finding
 
 HFS_STACKS_IN_FE:
-  title: "Stack declarations in frontend repo"
+  title: "Stack declarations in the front end (fe/)"
   title_vi: "Khai báo stack nằm trong repo giao diện"
   meaning_vi: "Repo giao diện đang chứa thư mục .starcistacks, trong khi khai báo stack chỉ được đặt ở repo backend."
   causes_vi:
@@ -1622,7 +1601,7 @@ HFS_UNUSED_FILE:
   kind: check-finding
 
 HFS_WORK_IN_FE:
-  title: "Work tree inside frontend repo"
+  title: "Work tree inside the front end (fe/)"
   title_vi: "Hồ sơ Work nằm trong repo giao diện"
   meaning_vi: "Repo giao diện chứa thư mục .starciwork, trong khi hồ sơ Work chỉ được lưu ở repo backend."
   causes_vi:

package/runtime/scripts/checks/architecture/backend.mjs

@@ -227,7 +227,7 @@ function externalTransportReexport(ts, sourceFile, selected) {
   for (const statement of sourceFile.statements) {
     if (!ts.isExportDeclaration(statement)) continue;
     const clause = statement.exportClause;
-    const specifier = ts.isStringLiteralLike(statement.moduleSpecifier) ? statement.moduleSpecifier.text : null;
+    const specifier = statement.moduleSpecifier && ts.isStringLiteralLike(statement.moduleSpecifier) ? statement.moduleSpecifier.text : null;
     if (specifier && (specifier === '@nestjs/common' || TRANSPORT_PACKAGES.test(specifier))) {
       if (!clause) {
         if (specifier !== '@nestjs/common' || selected === null || [...selected].some(name => NEST_COMMON_TRANSPORT.has(name))) {

package/runtime/scripts/checks/architecture/config.mjs

@@ -61,7 +61,12 @@ function existingRegularFile(root, relative) {
   }
 }
 
-function workspaceDirectories(root) {
+/**
+ * The npm workspaces below `root`. The one package.json of an app is at `packageRoot` (the app root; `root` is its side folder):
+ * its workspace patterns under `<side>/` are this side's, read relative to the side folder, and every other pattern is the other
+ * side's.
+ */
+function workspaceDirectories(root, { packageRoot: appPackageRoot = root, side = null } = {}) {
   const directories = new Set();
   const queue = [root];
   const visited = new Set();
@@ -89,11 +94,14 @@ function workspaceDirectories(root) {
     const packageRoot = queue.shift();
     if (visited.has(packageRoot)) continue;
     visited.add(packageRoot);
-    const pkg = readJson(path.join(packageRoot, 'package.json'));
+    const sideRoot = side !== null && packageRoot === root;
+    const pkg = readJson(path.join(sideRoot ? appPackageRoot : packageRoot, 'package.json'));
     const patterns = Array.isArray(pkg?.workspaces) ? pkg.workspaces : pkg?.workspaces?.packages;
     for (const pattern of Array.isArray(patterns) ? patterns : []) {
       if (typeof pattern !== 'string' || !pattern.trim()) throw Error('package.json workspace entries must be non-empty paths.');
-      const normalized = slash(pattern.trim()).replace(/^\.\//, '');
+      const written = slash(pattern.trim()).replace(/^\.\//, '');
+      if (sideRoot && !written.startsWith(`${side}/`)) continue;
+      const normalized = sideRoot ? written.slice(side.length + 1) : written;
       const segments = normalized.split('/');
       if (path.isAbsolute(normalized) || segments.some(segment => segment === '..' || (segment.includes('*') && segment !== '*'))) {
         throw Error(`Unsupported local workspace pattern: ${normalized}.`);
@@ -121,7 +129,10 @@ function workspaceDirectories(root) {
     for (const section of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
       for (const [name, value] of Object.entries(pkg?.[section] ?? {})) {
         if (typeof value !== 'string' || !value.startsWith('file:')) continue;
-        const absolute = path.resolve(packageRoot, value.slice('file:'.length));
+        const absolute = path.resolve(sideRoot ? appPackageRoot : packageRoot, value.slice('file:'.length));
+        // The app's one package.json also lists the other side's file dependencies (inside the app, outside this side): not this
+        // side's. A path that leaves the app is judged like any other: a package of the same repository, or refused.
+        if (sideRoot && !isInside(root, absolute) && isInside(appPackageRoot, absolute)) continue;
         const label = `${section}.${name} file dependency`;
         if (isInside(root, absolute)) { admit(absolute, label, true); continue; }
         // A sibling package of the same repository: this project consumes it, so the path is real and
@@ -248,15 +259,19 @@ const GRAMMAR_PACKAGE = '@starci/grammar';
  * source, every app and every workspace package that depends on the Grammar package is a consumer. null when no app has
  * a globals.css to judge (the contract is then reported unavailable, never passed).
  */
-function derivedGrammar(root, apps, workspaces) {
+function derivedGrammar(root, packageRoot, workspaces, apps = []) {
   const styleSources = apps.map(app => `apps/${app.name}/src/app/globals.css`).filter(relative => existingRegularFile(root, relative));
   if (!styleSources.length) return null;
-  const consumerManifests = apps.map(app => `apps/${app.name}/package.json`).filter(relative => existingRegularFile(root, relative));
+  // The apps have no package.json of their own: the app root's one manifest declares their dependencies, and it is a consumer
+  // when it declares the Grammar package; so is every workspace package that does.
+  const declaresGrammar = (pkg) => Boolean(pkg && [pkg.dependencies, pkg.peerDependencies, pkg.devDependencies].some(section => section && Object.hasOwn(section, GRAMMAR_PACKAGE)));
+  const appManifest = slash(path.relative(root, path.join(packageRoot, 'package.json')));
+  const consumerManifests = declaresGrammar(readJson(path.join(packageRoot, 'package.json'))) ? [appManifest] : [];
   for (const workspace of workspaces) {
     if (!workspace.startsWith('packages/')) continue;
     const manifest = `${workspace}/package.json`;
     const pkg = readJson(path.join(root, ...manifest.split('/')));
-    if (pkg && [pkg.dependencies, pkg.peerDependencies, pkg.devDependencies].some(section => section && Object.hasOwn(section, GRAMMAR_PACKAGE))) consumerManifests.push(manifest);
+    if (declaresGrammar(pkg)) consumerManifests.push(manifest);
   }
   if (!consumerManifests.length) return null;
   return { package: GRAMMAR_PACKAGE, entry: `${GRAMMAR_PACKAGE}/common`, styleEntry: `${GRAMMAR_PACKAGE}/common.css`, styleSources, consumerManifests, peers: ['react', '@heroui/react'] };
@@ -272,10 +287,14 @@ export function loadArchitectureConfig(repositoryRoot, { hfs } = {}) {
   if (!fs.lstatSync(root).isDirectory()) throw Error('Repository root must be a directory.');
   const opened = hfs ?? openHfs({ repoRoot: root });
   const { profile, apps } = opened.repo;
-  const workspaces = workspaceDirectories(root);
-  const inferred = inferredLayout(root, [...new Set([...workspaces, ...apps.map(app => `apps/${app.name}`)])].sort());
+  // A side of an app (the side folder is the root the machine judges) keeps its dependencies in the app root's one package.json.
+  const side = opened.repo.side ?? null;
+  const packageRoot = side === null ? root : path.dirname(root);
+  const workspaces = workspaceDirectories(root, { packageRoot, side });
+  const appDirs = apps.map(app => `apps/${app.name}`);
+  const inferred = inferredLayout(root, [...new Set([...workspaces, ...appDirs])].sort());
   const kinds = [profile === 'be' ? 'backend' : 'frontend'];
-  const projects = discoveredProjects(root, workspaces);
+  const projects = discoveredProjects(root, [...new Set([...workspaces, ...appDirs])].sort());
   if (!projects.length) throw Error('The repository has no tsconfig.json to derive a TypeScript project from.');
   const backend = {
     modules: ['src/modules'],
@@ -290,11 +309,12 @@ export function loadArchitectureConfig(repositoryRoot, { hfs } = {}) {
     hooks: inferred.hooks,
     modules: inferred.modules,
     transport: inferred.transport,
-    grammar: profile === 'fe' ? derivedGrammar(root, apps, workspaces) : null,
+    grammar: profile === 'fe' ? derivedGrammar(root, packageRoot, workspaces, apps) : null,
   };
   if (profile === 'fe') assertFrontendRolesDisjoint(root, frontend);
   return {
     root,
+    packageRoot,
     repository: enclosingRepository(root),
     kinds,
     projects,

package/runtime/scripts/checks/architecture/contracts.mjs

@@ -276,7 +276,7 @@ function contractTypeStatusFromType(ts, checker, type, seen = new Set(), depth =
   }
   for (const anonymous of ['Record', 'Partial', 'Pick', 'Omit', 'Required']) if (builtinSymbol(ts, named, anonymous)) return 'inline';
   if (type.aliasSymbol) return 'named';
-  if (type.symbol?.getDeclarations?.().some(declaration => ts.isEnumDeclaration(declaration))) return 'named';
+  if ((type.symbol?.getDeclarations?.() ?? []).some(declaration => ts.isEnumDeclaration(declaration))) return 'named';
   if (type.flags & ts.TypeFlags.TypeParameter) return 'named';
   if (type.flags & ts.TypeFlags.Boolean) return 'scalar';
   if (type.flags & (ts.TypeFlags.Union | ts.TypeFlags.Intersection)) return 'inline';
@@ -590,7 +590,7 @@ function checkMessageReadonly(config, context, checker, declaration, localFiles,
     }
     const type = classInstanceType(ts, checker, selected);
     for (const base of type && checker.getBaseTypes ? checker.getBaseTypes(type) : []) {
-      const declarations = base.symbol?.getDeclarations?.().filter(item => ts.isClassDeclaration(item)) ?? [];
+      const declarations = (base.symbol?.getDeclarations?.() ?? []).filter(item => ts.isClassDeclaration(item)) ?? [];
       if (declarations.length !== 1) {
         reasons.push(`${relativePath(config.root, sourceFile.fileName)} inherits message fields from a class outside the checked production program`);
       } else if (localFiles.has(canonical(declarations[0].getSourceFile().fileName))) visitClass(declarations[0]);
@@ -654,7 +654,7 @@ function checkInjectedClass(config, context, checker, declaration, classKind, ta
   if (classKind) {
     const type = classInstanceType(ts, checker, declaration);
     for (const base of type && checker.getBaseTypes ? checker.getBaseTypes(type) : []) {
-      const declarations = base.symbol?.getDeclarations?.().filter(item => ts.isClassDeclaration(item)) ?? [];
+      const declarations = (base.symbol?.getDeclarations?.() ?? []).filter(item => ts.isClassDeclaration(item)) ?? [];
       if (declarations.length !== 1) {
         reasons.push(`${relativePath(config.root, sourceFile.fileName)} inherits an injected constructor from a class outside the checked production program`);
       } else if (localFiles.has(canonical(declarations[0].getSourceFile().fileName))) {
@@ -709,7 +709,7 @@ export function checkBackendContracts(config, context) {
       publicReasons.push(`${owner.entry} uses export =, so named capability API discovery is unavailable`);
     }
     for (const symbol of exportedSymbols(ts, checker, entry)) {
-      const declarations = symbol.getDeclarations?.().filter(declaration => localFiles.has(canonical(declaration.getSourceFile().fileName))) ?? [];
+      const declarations = (symbol.getDeclarations?.() ?? []).filter(declaration => localFiles.has(canonical(declaration.getSourceFile().fileName))) ?? [];
       if (!declarations.length) continue;
       const representative = declarations[0];
       if (isFrameworkHelper(representative.getSourceFile(), representative, framework)) continue;

package/runtime/scripts/checks/architecture/fe-slot-allows.mjs

@@ -1,14 +1,17 @@
 import { treeOf } from './required-files.mjs';
 import { allowsFile } from '../../lib/hfs-allows.mjs';
+import { isFeTestPath } from '../../lib/hfs-rules/fe-no-tests.mjs';
 
 /**
  * R94 `fe-slot-allows` (FE_SLOT_FILE_ROLE). A front-end slot that owns a whole directory (`fe.route`, `fe.feature`,
  * `fe.components`, `fe.hooks`, `fe.modules.api`) also says what its instances hold (`allows` in knowledge/hfs/slots.yaml).
  * Every tracked file of such a slot is matched against the `requires` and `allows` entries of its slot; a file no entry names is a
- * finding - `page.tsx` in a hooks domain, a `[lang]` segment under `app/`, a `.test.tsx` beside a component, a stray file at
- * a feature root. A file that sits where the slot expects a folder (`hooks/useX.ts`, so the "domain" is a file name) is one too.
+ * finding - `page.tsx` in a hooks domain, a `[lang]` segment under `app/`, a stray file beside a component or at a feature
+ * root. A file that sits where the slot expects a folder (`hooks/useX.ts`, so the "domain" is a file name) is one too.
  * Files no slot owns are HFS_PATH_NO_SLOT's (`hfs check`), so together every front-end file is placed by exactly one slot and
- * named by it.
+ * named by it. A test path (a `.spec.tsx` or `.test.tsx` beside a component, a test directory or test tooling) is FE_NO_TESTS's
+ * (R97, contract-change fe-no-tests): that rule is the one finding of such a file, so this check leaves it alone, as
+ * HFS_PATH_NO_SLOT does (scripts/lib/hfs-path-findings.mjs).
  */
 export const FE_SLOT_ALLOWS_RULE_IDS = ['FE_SLOT_FILE_ROLE'];
 
@@ -21,6 +24,7 @@ export function checkFeSlotAllows({ config, graph }) {
   let files = 0;
   const report = (file, message, extra = {}) => violations.push({ ruleId: RULE, path: file, line: 1, column: 1, message, ...extra });
   for (const file of [...tree.files].sort()) {
+    if (isFeTestPath(file)) continue;   // FE_NO_TESTS's, the one finding of that file
     const classified = resolver.classifyPath(file);
     if (classified.status !== 'owned') continue;
     const slot = resolver.slot(classified.slot);

package/runtime/scripts/checks/architecture/framework-pinned.mjs

@@ -1,14 +1,11 @@
 // framework-pinned.mjs - the Next.js files that only load from a source root (the directory holding
-// app/), and the export names the framework mandates in them. Authored once in
-// knowledge/patterns/fe/folder.yaml FE-FOLDER-1 (frameworkPinnedRootFiles, frameworkPinnedRootExports),
-// never hard-coded here (supervisor rulings, nivo wf-nivo-fe-debt-mug06w7h inc-2e42a24b74e4 and
-// inc-846867b9a34e). Read by the architecture check (FE_SOURCE_LAYOUT_INVALID) and the Next name-shape
-// check (FE_SOURCE_NAME_SHAPE).
+// app/). Authored once in knowledge/patterns/fe/folder.yaml FE-FOLDER-1 (frameworkPinnedRootFiles), never
+// hard-coded here (supervisor ruling, nivo wf-nivo-fe-debt-mug06w7h inc-2e42a24b74e4). Read by the architecture
+// check (FE_SOURCE_LAYOUT_INVALID).
 //
-// An unreadable or malformed list is a broken install, not "no pinned files": both readers throw
+// An unreadable or malformed list is a broken install, not "no pinned files": the reader throws
 // ARCH_KNOWLEDGE_UNAVAILABLE so the caller reports an error instead of judging with a different contract.
 import fs from 'node:fs';
-import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseYaml } from '../../../engine/yaml.mjs';
 
@@ -21,11 +18,6 @@ function unavailable(file, detail) {
   return Error(`ARCH_KNOWLEDGE_UNAVAILABLE: ${file} ${detail}`);
 }
 
-/** The file stem Next.js keys a pinned file by: `middleware.ts` -> `middleware`, `next-env.d.ts` -> `next-env`. */
-export function pinnedStem(fileName) {
-  return path.basename(fileName).replace(/(?:\.d)?\.[cm]?[jt]sx?$/i, '');
-}
-
 function load(file) {
   if (cache.has(file)) return cache.get(file);
   let rule;
@@ -38,21 +30,7 @@ function load(file) {
   if (!Array.isArray(list) || !list.length || list.some(name => typeof name !== 'string' || !EXACT_NAME.test(name))) {
     throw unavailable(file, 'FE-FOLDER-1 frameworkPinnedRootFiles must be a nonempty list of exact file names.');
   }
-  const files = new Set(list);
-  const stems = new Set(list.map(pinnedStem));
-  const declared = rule.frameworkPinnedRootExports;
-  if (!declared || typeof declared !== 'object' || Array.isArray(declared)) {
-    throw unavailable(file, 'FE-FOLDER-1 frameworkPinnedRootExports must map a pinned file stem to its framework-mandated export names.');
-  }
-  const exports = new Map();
-  for (const [stem, names] of Object.entries(declared)) {
-    if (!stems.has(stem)) throw unavailable(file, `FE-FOLDER-1 frameworkPinnedRootExports names ${stem}, which no frameworkPinnedRootFiles entry pins.`);
-    if (!Array.isArray(names) || !names.length || names.some(name => typeof name !== 'string' || !/^[A-Za-z_$][\w$]*$/.test(name))) {
-      throw unavailable(file, `FE-FOLDER-1 frameworkPinnedRootExports.${stem} must be a nonempty list of export identifiers.`);
-    }
-    exports.set(stem, new Set(names));
-  }
-  const loaded = { files, exports };
+  const loaded = { files: new Set(list) };
   if (file === FRAMEWORK_PINNED_KNOWLEDGE) cache.set(file, loaded);
   return loaded;
 }
@@ -61,23 +39,3 @@ function load(file) {
 export function frameworkPinnedRootFiles(file = FRAMEWORK_PINNED_KNOWLEDGE) {
   return load(file).files;
 }
-
-/** Map of pinned file stem to the export names the framework mandates there. */
-export function frameworkPinnedRootExports(file = FRAMEWORK_PINNED_KNOWLEDGE) {
-  return load(file).exports;
-}
-
-/**
- * The framework-mandated export names for an absolute source file when it is a pinned file sitting
- * directly in a Next source root (its directory holds an app/ directory), else null.
- */
-export function frameworkMandatedExports(absoluteFile, file = FRAMEWORK_PINNED_KNOWLEDGE) {
-  const { files, exports } = load(file);
-  if (!files.has(path.basename(absoluteFile))) return null;
-  try {
-    if (!fs.statSync(path.join(path.dirname(absoluteFile), 'app')).isDirectory()) return null;
-  } catch {
-    return null;
-  }
-  return exports.get(pinnedStem(absoluteFile)) ?? new Set();
-}

package/runtime/scripts/checks/architecture/frontend.mjs

@@ -108,13 +108,15 @@ function checkGrammar(config, context) {
   // Node resolution per consumer: in an npm-workspaces monorepo a consumer whose range differs from the
   // hoisted copy gets its own apps/<app>/node_modules/<package> (nivo-fe: apps/app on 0.5.0 beside a hoisted
   // 0.4.11). Every consumer is judged against the copy it actually resolves, never the hoisted one alone.
+  // An app installs once, at its root (config.packageRoot): a side folder has no node_modules of its own.
+  const installRoot = config.packageRoot ?? config.root;
   const installedFrom = (from) => {
-    for (let dir = from; isInside(config.root, dir); dir = path.dirname(dir)) {
+    for (let dir = from; isInside(installRoot, dir); dir = path.dirname(dir)) {
       const candidate = path.join(dir, 'node_modules', ...grammar.package.split('/'));
       if (fs.existsSync(path.join(candidate, 'package.json'))) return candidate;
-      if (dir === config.root || path.dirname(dir) === dir) break;
+      if (dir === installRoot || path.dirname(dir) === dir) break;
     }
-    return path.join(config.root, 'node_modules', ...grammar.package.split('/'));
+    return path.join(installRoot, 'node_modules', ...grammar.package.split('/'));
   };
   const consumers = grammar.consumerManifests.map(relative => {
     const root = path.dirname(path.join(config.root, ...relative.split('/')));
@@ -123,7 +125,7 @@ function checkGrammar(config, context) {
       manifest: readJson(path.join(config.root, ...relative.split('/'))) ?? {} };
   });
   const installs = [...new Map(consumers.map(consumer => [consumer.packageRoot, consumer])).values()];
-  const packageRoot = installs[0]?.packageRoot ?? local?.root ?? path.join(config.root, 'node_modules', ...grammar.package.split('/'));
+  const packageRoot = installs[0]?.packageRoot ?? local?.root ?? path.join(installRoot, 'node_modules', ...grammar.package.split('/'));
   const manifestFile = path.join(packageRoot, 'package.json');
   const manifest = readJson(manifestFile);
   const ownerOf = (fileName) => consumers.filter(consumer => isInside(consumer.root, fileName))

package/runtime/scripts/checks/architecture/hfs-graph.mjs

@@ -5,7 +5,7 @@ import { relativePath } from './typescript.mjs';
  * The file and owner graph the HFS architecture checks share. Every production source file the TypeScript context
  * loaded becomes a node classified by the slot manifest (config.hfs is the resolver of scripts/lib/hfs-slots.mjs);
  * every import, re-export and type-only import between two of them becomes an edge. Nothing here judges: the checks
- * in tiers.mjs, reachability.mjs, dead-exports.mjs, required-files.mjs, size-growth.mjs and clones.mjs read it.
+ * in tiers.mjs, reachability.mjs, dead-exports.mjs, required-files.mjs and clones.mjs read it.
  *
  *   graph.profile            'be' | 'fe'
  *   graph.resolver           the slot resolver (config.hfs)