@starci/hfs 1.0.1 → 2.0.1

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: []

package/runtime/knowledge/sonar-gate.yaml

@@ -0,0 +1,85 @@
+schema: starci/sonar-gate@1
+id: sonar-gate
+title: The Sonar quality gate every product is held to
+purpose: |
+  The one place the Sonar thresholds live. A product repository never restates them: its
+  .starcistacks/application-stacks.yaml `services.sonar.qualityGate` names the gate below, and
+  scripts/checks/sonar-local.mjs (1) makes the local SonarQube's gate of that name carry exactly these
+  conditions and selects it for the project, and (2) judges an op's slice - the lines it changed - against
+  the same numbers. Code-writing ops cannot settle done while the slice is red
+  (scripts/kernel/sonar-settle.mjs). Changing a number here changes every repository on the next scan.
+  The gate has two parts: `newCode` (the recent work: duplication, blocker/critical issues, hotspots) and
+  `overall` (the whole code: no imported HFS, ESLint or stylelint finding, 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
+  # 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:
+  # Sonar holds NO coverage condition: unit coverage is the runner's job (jest per-file 100 on `*.service.ts`), never an lcov import.
+  # SonarQube's ignoreSmallChanges: fewer changed lines than this are not held to duplication.
+  ignoreBelowChangedLines: 20
+  duplication:
+    metric: new_duplicated_lines_density
+    maxPercent: 3
+  issues:
+    # An open issue of these severities on a changed line fails the slice; lesser ones are listed, never blocking.
+    blockingSeverities: [BLOCKER, CRITICAL]
+    metrics: {BLOCKER: new_blocker_violations, CRITICAL: new_critical_violations}
+    max: 0
+  hotspots:
+    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
+# 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
+# stricter than the engines alone and it is intended: a project that meets this gate has no open issue of any origin.
+overall:
+  issues:
+    metric: violations
+    max: 0
+    engines: [starci-hfs, eslint, stylelint]
+  # HFS_DUPLICATE_CODE (R21): duplicated lines density of the whole project, the Sonar enforcer of the machine's clone check.
+  # SonarJS runs its own token-based detection (sonar.cpd.* minimums are not read for TypeScript), so ruleParams.<profile>.duplicateBlock
+  # is enforced by the machine and imported as starci-hfs issues, and this density is the Sonar-side backstop.
+  duplication:
+    metric: duplicated_lines_density
+    maxPercent: 3
+  # HFS_SIZE_GROWTH (R20): the cognitive complexity of a function is the Sonar rule S3776 (typescript:S3776, Sonar way, default
+  # threshold); an open S3776 issue is an open issue of `overall.issues`, so the zero-issue condition is its gate.
+  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}
+  - {rule: R21, code: HFS_DUPLICATE_CODE, enforcer: duplicated-lines-density, condition: duplication}
+  - {rule: R21, code: HFS_DUPLICATE_SYMBOL, enforcer: duplicated-lines-density, condition: duplication}
+# Ops that write product code: each runs sonar-local on its own change and cannot settle done while the gate is red.
+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.
+  no coverage condition: the unit project fails below its per-file 100 threshold on `*.service.ts`, so Sonar never
+  imports an lcov report and never judges coverage.
+  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;
+  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`,
+  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.