@starci/hfs 4.16.5 → 4.17.2

package/runtime/knowledge/hfs/rules.yaml

@@ -75,6 +75,7 @@ rules:
       - {kind: machine, id: required-files, at: scripts/hfs/architecture/required-files.mjs}
       - {kind: machine, id: repository-tree-required, at: scripts/hfs/architecture/hfs.mjs}
       - {kind: runtime, id: runtime-required, at: scripts/hfs/runtime-check.mjs}
+    docs: [contexts/code/be/folder.md]
   - id: R03
     code: "HFS_UNTRACKED_ROOT_ENTRY"
     editions: [lite, full]
@@ -155,6 +156,7 @@ rules:
     failureCodes: ["HFS_AGENT_DATA_TRACKED"]
     enforcers:
       - {kind: work-validate, id: agent-data-tracked, at: scripts/work/validate/check-example-work.mjs}
+    docs: [contexts/hfs/README.md#rule-notes]
   - id: R09
     code: "HFS_IDENTITY_CUSTODY"
     law: "An identity points its secret at `secrets/identity-<slug>.enc`; UAT chooses by role."
@@ -164,6 +166,7 @@ rules:
     enforcers:
       - {kind: work-validate, id: sealed-custody-location, at: scripts/work/validate/check-work-artifacts.mjs}
       - {kind: work-validate, id: identity-custody-role, at: scripts/work/validate/check-example-work.mjs}
+    docs: [contexts/hfs/README.md#rule-notes]
   - id: R10
     code: "HFS_STACKS_SHAPE"
     editions: [lite, full]
@@ -336,6 +339,7 @@ rules:
       - {kind: eslint-be, id: no-inline-suppression}
       - {kind: eslint-fe, id: no-inline-lint-config}
       - {kind: stylelint, id: no-inline-lint-config}
+    docs: [contexts/code/shared/format.md]
   - id: R19
     code: "HFS_FORMAT"
     editions: ["lite", "full"]
@@ -365,6 +369,7 @@ rules:
       - {kind: eslint-fe, id: file-size-growth}
       - {kind: sonar, id: cognitive-complexity, at: knowledge/sonar-gate.yaml}
       - {kind: runtime, id: runtime-size, at: scripts/hfs/runtime-rules/size.mjs}
+    docs: [contexts/code/be/function.md]
   - id: R21
     code: "HFS_DUPLICATE_CODE"
     law: "No duplicated blocks or twice-defined helpers."
@@ -378,6 +383,7 @@ rules:
       - {kind: eslint-fe, id: duplicate-symbol}
       - {kind: eslint-fe, id: cross-app-duplicate}
       - {kind: sonar, id: duplicated-lines-density, at: knowledge/sonar-gate.yaml}
+    docs: [contexts/code/be/function.md]
   - id: R22
     code: "HFS_TS_STRICT"
     editions: ["lite", "full"]
@@ -474,10 +480,10 @@ rules:
     witness:
       - {path: packages/eslint/be/legacy-owner-graph.a16.spec.mjs, editions: [lite, full]}
     templateNa: "Tier and package direction are constraints on cross-owner import graphs; no dedicated cross-owner graph scaffold is generated."
-    law: "The tier direction matrix; a shared package never imports an app. Front-end page and layout owners may import overlay entries; every other cross-owner feature-to-feature edge is forbidden, including layout-to-page and overlay-to-overlay. Components never import overlays. The one platform-to-domain edge is the lite entity registry (be.platform.database.entities) importing a capability's `<c>Entities` alone from its `index.ts`."
+    law: "The tier direction matrix; a shared package never imports an app. Front-end page and layout owners may import overlay entries; every other cross-owner feature-to-feature edge is forbidden, including layout-to-page and overlay-to-overlay. Components never import overlays. The one platform-to-domain edge is the lite entity registry (be.platform.database.entities) importing a capability's `<c>Entities` alone from its `index.ts`. A component library's tiers (`tiers.grammar`: leaf, branch, composite, frame) import nothing above themselves, and its `data-tier` stamp is its folder."
     kinds: [lint, design]
     gates: [settle, land, ci]
-    failureCodes: ["BE_TIER_DIRECTION", "FE_TIER_DIRECTION", "ARCH_PACKAGE_IMPORTS_APP"]
+    failureCodes: ["BE_TIER_DIRECTION", "FE_TIER_DIRECTION", "FE_GRAMMAR_TIER_DIRECTION", "FE_GRAMMAR_TIER_STAMP", "ARCH_PACKAGE_IMPORTS_APP"]
     enforcers:
       - {kind: eslint-be, id: tier-direction}
       - {kind: eslint-fe, id: tier-direction}
@@ -1266,7 +1272,8 @@ rules:
       - {kind: stylelint, id: globals-shape}
       - {kind: stylelint, id: globals-import-order}
       - {kind: stylelint, id: no-token-redefinition}
-      - {kind: stylelint, id: brand-layer-shape}
+      - {kind: stylelint, id: no-grammar-private-token}
+      - {kind: stylelint, id: theme-layer-shape}
       - {kind: stylelint, id: status-contrast}
       - {kind: stylelint, id: no-css-module}
       - {kind: stylelint, id: no-class-selector}
@@ -1275,9 +1282,7 @@ rules:
       - {kind: eslint-fe, id: no-raw-brand-value}
       - {kind: eslint-grammar-core, id: no-fractional-step}
       - {kind: eslint-fe, id: no-arbitrary-value}
-      - {kind: eslint-grammar-core, id: no-hand-rolled-heading}
       - {kind: eslint-grammar-core, id: no-unresolved-token-class}
-      - {kind: eslint-grammar-core, id: no-heading-tag-outside-heading-component}
       - {kind: eslint-grammar-core, id: status-text-uses-soft-foreground}
     proves:
       - {path: packages/stylelint/source-resolves.spec.mjs, editions: [lite, full], codes: [FE_STYLE_SOURCE_UNRESOLVED]}
@@ -1859,7 +1864,7 @@ rules:
     editions: ["lite","full"]
     docs: ["docs/frontend-source-authoring.md#r91-source-form"]
     proves: [{"path":"packages/eslint/fe/r91-source-form.spec.mjs","editions":["lite","full"]}]
-    exemplifiedBy: [{"path":"packages/hfs/templates/fe/skeleton-lite/apps/web/src/components/composites/SiteShell/index.tsx","edition":"lite"},{"path":"packages/hfs/templates/fe/skeleton/apps/app/src/features/pages/AppHomePage/index.tsx","edition":"full"},{"path":"packages/eslint/fe/r91-source-form.spec.mjs","editions":["lite","full"]}]
+    exemplifiedBy: [{"path":"packages/hfs/templates/fe/skeleton-lite/apps/web/src/components/frames/SiteShell/index.tsx","edition":"lite"},{"path":"packages/hfs/templates/fe/skeleton/apps/app/src/features/pages/AppHomePage/index.tsx","edition":"full"},{"path":"packages/eslint/fe/r91-source-form.spec.mjs","editions":["lite","full"]}]
     witness: [{"path":"packages/eslint/fe/r91-source-form.spec.mjs","edition":"lite","codes":["FE_SOURCE_FORM","FE_SOURCE_LAYOUT_INVALID"]},{"path":"packages/eslint/fe/r91-source-form.spec.mjs","edition":"full","codes":["FE_SOURCE_FORM","FE_SOURCE_LAYOUT_INVALID"]}]
     gates: ["pre-commit","settle","land","ci"]
   - id: R92
@@ -1875,6 +1880,7 @@ rules:
       - {kind: eslint-fe, id: no-public-classname-prop}
       - {kind: eslint-fe, id: no-public-frame-css-props}
       - {kind: eslint-fe, id: no-css-door-type-laundering}
+      - {kind: eslint-fe, id: tier-children}
       - {kind: eslint-fe, id: base-props-atom}
       - {kind: eslint-fe, id: base-import-pair}
       - {kind: eslint-fe, id: no-data-status-shape}
@@ -1915,10 +1921,8 @@ rules:
     enforcers:
       - {kind: eslint-grammar-core, id: no-vendor-icon-outside-icon-leaf}
       - {kind: eslint-grammar-core, id: heroicons-is-the-glyph-vendor}
-      - {kind: eslint-grammar-core, id: no-off-scale-glyph-size}
       - {kind: eslint-grammar-core, id: no-icon-size-class}
       - {kind: eslint-grammar-core, id: destructive-menu-entry-needs-danger-tone}
-      - {kind: eslint-grammar-core, id: no-decorative-icon-in-metric-cell}
       - {kind: eslint-grammar-core, id: vendor-primitive-has-named-owner}
       - {kind: eslint-fe, id: grammar-entry}
       - {kind: machine, id: grammar, at: scripts/hfs/architecture/frontend-grammar.mjs}
@@ -3809,6 +3813,7 @@ rules:
     failureCodes: ["RIGHTS_ROLE_DENIED", "RIGHTS_GIT_PUSH", "RIGHTS_GIT_TAG", "RIGHTS_GIT_COMMIT", "RIGHTS_GIT_SYNC", "RIGHTS_NPM_PUBLISH", "RIGHTS_NPM_CI_UNLOCKED", "RIGHTS_SUITE_RUN", "RIGHTS_RELEASE_CUT", "RIGHTS_RAW_TOOL"]
     enforcers:
       - {kind: runtime, id: role-rights, at: scripts/hfs/runtime-rules/rights-policy.mjs}
+    docs: [contexts/hfs/README.md#rule-notes]
   - id: R224
     code: "RIGHTS_PROTECTED_ZONE"
     law: "The protected zone declared once in modules/kernel/protected-zone.yaml is edited only by the owner path; a supervisor self-upgrade files an owner proposal, and an op never writes the .claude runtime checkout."
@@ -3818,6 +3823,7 @@ rules:
     failureCodes: ["RIGHTS_PROTECTED_ZONE", "RIGHTS_OP_RUNTIME_WRITE"]
     enforcers:
       - {kind: runtime, id: protected-zone, at: scripts/hfs/runtime-rules/rights-policy.mjs}
+    docs: [contexts/hfs/README.md#rule-notes]
   - id: R225
     code: "RT_HOOK_SHAPE"
     law: "The app hook templates keep the gate model: pre-commit is L0 only (no typecheck or test run); pre-push invokes the bundled scripts/guards/release-push-gate.mjs policy for fast-forward main, a clean outgoing secret scan and annotated v* tags, then the harness's `starci deps check` (every committed @starci pin installable from npm, no local package copy ahead of npm). It runs no build, test, typecheck or lint."
@@ -3827,6 +3833,7 @@ rules:
     failureCodes: ["RT_HOOK_SHAPE", "RIGHTS_PUSH_NOT_RELEASE"]
     enforcers:
       - {kind: runtime, id: hook-shape, at: scripts/hfs/runtime-rules/hook-shape.mjs}
+    docs: [contexts/hfs/README.md#rule-notes]
   - id: R227
     code: "RT_SYNTAX_INVALID"
     editions: [lite, full]
@@ -5468,7 +5475,6 @@ rules:
     gates: [pre-commit, settle, land, ci]
     failureCodes: ["FE_NESTED_VARIANT", "FE_LIST_PANEL_PADDING", "FE_GRAMMAR_LAYOUT_ONLY", "FE_DIVIDER_FULL_BLEED"]
     enforcers:
-      - {kind: eslint-fe, id: nested-control-variant}
       - {kind: eslint-fe, id: no-list-panel-padding}
       - {kind: eslint-fe, id: no-app-surface-paint}
       - {kind: eslint-fe, id: divider-full-bleed}
@@ -5479,15 +5485,15 @@ rules:
     templateNa: "Product composition is proved by the FE canon's Grammar import and surface fixtures; a template cannot choose product slots or lists."
     proves:
       - {path: packages/eslint/fe/divider-full-bleed.spec.mjs, editions: [lite, full], codes: [FE_DIVIDER_FULL_BLEED]}
-      - {path: packages/eslint/fe/surface-rules.spec.mjs, editions: [lite, full], codes: [FE_NESTED_VARIANT, FE_LIST_PANEL_PADDING, FE_GRAMMAR_LAYOUT_ONLY]}
+      - {path: packages/eslint/fe/surface-rules.spec.mjs, editions: [lite, full], codes: [FE_LIST_PANEL_PADDING, FE_GRAMMAR_LAYOUT_ONLY]}
       - {path: packages/eslint/fe/ui-rulings.spec.mjs, editions: [lite, full], codes: [FE_NESTED_VARIANT, FE_GRAMMAR_LAYOUT_ONLY]}
     exemplifiedBy:
       - {path: packages/eslint/fe/divider-full-bleed.spec.mjs, editions: [lite, full], codes: [FE_DIVIDER_FULL_BLEED]}
-      - {path: packages/eslint/fe/surface-rules.spec.mjs, editions: [lite, full], codes: [FE_NESTED_VARIANT, FE_LIST_PANEL_PADDING, FE_GRAMMAR_LAYOUT_ONLY]}
+      - {path: packages/eslint/fe/surface-rules.spec.mjs, editions: [lite, full], codes: [FE_LIST_PANEL_PADDING, FE_GRAMMAR_LAYOUT_ONLY]}
       - {path: packages/eslint/fe/ui-rulings.spec.mjs, editions: [lite, full], codes: [FE_NESTED_VARIANT, FE_GRAMMAR_LAYOUT_ONLY]}
     witness:
       - {path: packages/eslint/fe/divider-full-bleed.spec.mjs, editions: [lite, full], codes: [FE_DIVIDER_FULL_BLEED]}
-      - {path: packages/eslint/fe/surface-rules.spec.mjs, editions: [lite, full], codes: [FE_NESTED_VARIANT, FE_LIST_PANEL_PADDING, FE_GRAMMAR_LAYOUT_ONLY]}
+      - {path: packages/eslint/fe/surface-rules.spec.mjs, editions: [lite, full], codes: [FE_LIST_PANEL_PADDING, FE_GRAMMAR_LAYOUT_ONLY]}
       - {path: packages/eslint/fe/ui-rulings.spec.mjs, editions: [lite, full], codes: [FE_NESTED_VARIANT, FE_GRAMMAR_LAYOUT_ONLY]}
     cases:
       - id: case-1
@@ -5501,10 +5507,9 @@ rules:
     law: "An app Button or IconButton declares an intent and never a variant; Grammar resolves the variant from intent and placement (CTA-6). A destructive confirm lives in a confirmation dialog, a render holds at most one commit, and a collection item holds none."
     kinds: [codemod, lint, design]
     gates: [pre-commit, settle, land, ci]
-    failureCodes: ["FE_BUTTON_INTENT", "FE_BUTTON_INTENT_REQUIRED", "FE_BUTTON_NO_VARIANT", "FE_DESTRUCTIVE_CONFIRM_IN_DIALOG", "FE_SINGLE_COMMIT_PER_RENDER", "FE_NO_COMMIT_IN_COLLECTION_ITEM"]
+    failureCodes: ["FE_BUTTON_INTENT", "FE_BUTTON_INTENT_REQUIRED", "FE_DESTRUCTIVE_CONFIRM_IN_DIALOG", "FE_SINGLE_COMMIT_PER_RENDER", "FE_NO_COMMIT_IN_COLLECTION_ITEM"]
     enforcers:
       - {kind: eslint-fe, id: button-intent-required}
-      - {kind: eslint-fe, id: button-no-variant}
       - {kind: eslint-fe, id: destructive-confirm-in-dialog}
       - {kind: eslint-fe, id: single-commit-per-render}
       - {kind: eslint-fe, id: no-commit-in-collection-item}
@@ -5513,11 +5518,11 @@ rules:
       - knowledge/ui/composition/cta.yaml
       - docs/code-pattern-enforcement.md#r319-button-intent
     proves:
-      - {path: packages/eslint/fe/button-intent.spec.mjs, editions: [lite, full], codes: [FE_BUTTON_INTENT, FE_BUTTON_INTENT_REQUIRED, FE_BUTTON_NO_VARIANT, FE_DESTRUCTIVE_CONFIRM_IN_DIALOG, FE_SINGLE_COMMIT_PER_RENDER, FE_NO_COMMIT_IN_COLLECTION_ITEM]}
+      - {path: packages/eslint/fe/button-intent.spec.mjs, editions: [lite, full], codes: [FE_BUTTON_INTENT, FE_BUTTON_INTENT_REQUIRED, FE_DESTRUCTIVE_CONFIRM_IN_DIALOG, FE_SINGLE_COMMIT_PER_RENDER, FE_NO_COMMIT_IN_COLLECTION_ITEM]}
     exemplifiedBy:
-      - {path: packages/eslint/fe/button-intent.spec.mjs, editions: [lite, full], codes: [FE_BUTTON_INTENT, FE_BUTTON_INTENT_REQUIRED, FE_BUTTON_NO_VARIANT, FE_DESTRUCTIVE_CONFIRM_IN_DIALOG, FE_SINGLE_COMMIT_PER_RENDER, FE_NO_COMMIT_IN_COLLECTION_ITEM]}
+      - {path: packages/eslint/fe/button-intent.spec.mjs, editions: [lite, full], codes: [FE_BUTTON_INTENT, FE_BUTTON_INTENT_REQUIRED, FE_DESTRUCTIVE_CONFIRM_IN_DIALOG, FE_SINGLE_COMMIT_PER_RENDER, FE_NO_COMMIT_IN_COLLECTION_ITEM]}
     witness:
-      - {path: packages/eslint/fe/button-intent.spec.mjs, editions: [lite, full], codes: [FE_BUTTON_INTENT, FE_BUTTON_INTENT_REQUIRED, FE_BUTTON_NO_VARIANT, FE_DESTRUCTIVE_CONFIRM_IN_DIALOG, FE_SINGLE_COMMIT_PER_RENDER, FE_NO_COMMIT_IN_COLLECTION_ITEM]}
+      - {path: packages/eslint/fe/button-intent.spec.mjs, editions: [lite, full], codes: [FE_BUTTON_INTENT, FE_BUTTON_INTENT_REQUIRED, FE_DESTRUCTIVE_CONFIRM_IN_DIALOG, FE_SINGLE_COMMIT_PER_RENDER, FE_NO_COMMIT_IN_COLLECTION_ITEM]}
     templateNa: "The intent of an action comes from the product decision in the .starciwork specification; a template cannot choose it."
     cases:
       - id: case-1
@@ -5576,7 +5581,7 @@ rules:
         ruling: "The label of a status chip starts with an uppercase letter (owner ruling chip-label-uppercase); StatusDot capitalises a text label it renders, and the lint refuses a lowercase literal label at its source."
   - id: R323
     code: "FE_PAGE_HEADER_HAND_ROLLED"
-    law: "A page is headed by Grammar's PageHeader; a Breadcrumbs trail followed by a SectionHeader in one parent is a page head composed by hand, with no band, no top inset and no separator."
+    law: "A page is headed by the header of Grammar's Page; PageHeader and Breadcrumbs are Page's parts and are not exported, so importing either from the Grammar composes a page head by hand, with no band, no top inset and no separator."
     kinds: [lint]
     gates: [pre-commit, settle, land, ci]
     failureCodes: ["FE_PAGE_HEADER_HAND_ROLLED"]
@@ -5596,10 +5601,10 @@ rules:
         date: "2026-10-28"
         source: owner
         quote: "Publish Grammar 0.15.3 with PageHeader now, then move all 18 pages to it before deploying. (translated from Vietnamese)"
-        ruling: "A page is headed by Grammar's PageHeader (owner ruling page-header-band): a surface band whose content shares the page content's edges and which ends in its own full-width separator, page tabs standing on it; the lint refuses a page head composed by hand from Breadcrumbs and SectionHeader."
+        ruling: "A page is headed by Grammar's Page header (owner ruling page-header-band): a surface band whose content shares the page content's edges and which ends in its own full-width separator, page tabs standing on it; the lint refuses a PageHeader or Breadcrumbs imported by hand, since both are Page's own parts."
   - id: R324
     code: "FE_PAGE_TABS_OUTSIDE_HEADER"
-    law: "Page tabs are the header's tabs; a Tabs that is the first element of a Page body or the next element after a PageHeader is a page tab bar drawn outside the band."
+    law: "Page tabs are the header's tabs; a Tabs that is the first element of a Page body is a page tab bar drawn outside the band."
     kinds: [lint]
     gates: [pre-commit, settle, land, ci]
     failureCodes: ["FE_PAGE_TABS_OUTSIDE_HEADER"]
@@ -5622,7 +5627,7 @@ rules:
         ruling: "A route page is one Grammar Page (owner ruling page-frame); page tabs are its header's tabs, and the lint refuses a Tabs at the top of the Page body or right after a PageHeader."
   - id: R325
     code: "FE_ROUTE_PAGE_OUTSIDE_PAGE"
-    law: "A page owner draws one Grammar Page with nothing beside it; a sibling of the Page, or a bare PageHeader or PageContainer in the page owner, re-decides the inset and rhythm Page owns."
+    law: "A page owner draws one Grammar Page with nothing beside it; a sibling of the Page re-decides the inset and rhythm Page owns, and PageHeader and PageContainer are Page's parts, not exports to import from the Grammar."
     kinds: [lint]
     gates: [pre-commit, settle, land, ci]
     failureCodes: ["FE_ROUTE_PAGE_OUTSIDE_PAGE"]
@@ -5958,7 +5963,7 @@ rules:
         ruling: "Mascot takes AssetSlotProps (assetSlot, assetSha256, assetPrompt) and emits them as data-asset-* on its root; the lint requires assetSlot on every Mascot."
   - id: R340
     code: "FE_RAISED_SURFACE_IN_SURFACE"
-    law: "A Grammar surface that accepts a depth prop (SurfaceListCard) does not pass depth=\"top\" when a SurfaceCard, SurfaceListCard or SurfaceAccordionCard of the same file encloses it: a nested surface is subordinate (outlined, BOUNDARY-5), never raised again (BOUNDARY-6, DNA-COMMON-NO-RAISED-SURFACE-IN-SURFACE); the Grammar resolves the depth from the surface context. A depth computed at run time is not judged."
+    law: "A surface never stands inside another surface (owner decision, dialogs and drawers included): a SurfaceCard that a SurfaceCard, a Pane surface, or a Dialog, Drawer, AlertDialog or Popover of the same file encloses is refused. The Grammar has one depth, raised."
     kinds: [lint]
     gates: [pre-commit, settle, land, ci]
     failureCodes: ["FE_RAISED_SURFACE_IN_SURFACE"]
@@ -5977,8 +5982,8 @@ rules:
       - id: case-1
         date: "2026-10-31"
         source: owner
-        quote: "A list inside another surface is outlined (BOUNDARY-5, DNA-COMMON-NO-RAISED-SURFACE-IN-SURFACE); SurfaceListCard takes its depth from the surface context (grammar 0.16.2)."
-        ruling: "SurfaceListCard resolves its depth from the surface context like SurfaceCard and SurfaceAccordionCard; an app that forces depth=\"top\" on a surface nested in another surface raises a surface inside a surface, so the lint refuses it."
+        quote: "A list inside another surface is outlined (BOUNDARY-5, DNA-COMMON-NO-RAISED-SURFACE-IN-SURFACE); the list SurfaceCard takes its depth from the surface context (grammar 0.16.2)."
+        ruling: "A list SurfaceCard resolves its depth from the surface context like every SurfaceCard kind; an app that forces depth=\"top\" on a surface nested in another surface raises a surface inside a surface, so the lint refuses it."
   - id: R341
     code: "FE_FREESTYLE_REASON_MISSING"
     law: "A Grammar Freestyle region, the one sanctioned place where an app writes its own plain elements and CSS because no Grammar component fits, names its reason: a non-empty string literal saying why. The rules that judge hand-written elements, classes, styles and generated art leave the raw elements of a Freestyle subtree alone; a Grammar component inside it is judged as before. An element with a spread attribute is not judged."
@@ -6028,6 +6033,7 @@ rules:
   - id: R343
     code: "HFS_CHECK_CACHE_FORGED"
     editions: ["lite", "full"]
+    docs: [contexts/hfs/README.md#rule-notes]
     law: "An app's committed check cache (.starcistacks/cache/) is trusted in CI only as it stands at the trusted base; a record whose key matches the tree and whose findings differ from the inherited or computed result is HFS_CHECK_CACHE_FORGED (a hard blocker at any count), a touched key without a current record is HFS_CHECK_CACHE_STALE and a missing cache is HFS_CHECK_CACHE_MISSING (both report-only warnings)."
     kinds: [codemod]
     gates: [ci]
@@ -6140,7 +6146,7 @@ rules:
         ruling: "One padding system for everything placed in a PaneGrid: the Pane publishes the inset and the PaneSection applies it, so no band adds its own."
   - id: R348
     code: "FE_PANE_GRID_FRAME"
-    law: "A Grammar PaneGrid is the one child of `Page chrome=\"panes\"` or stands inside a Pane; a PaneGrid drawn in a FillViewport, a SurfaceCard, SurfaceListCard or SurfaceAccordionCard, a Page of another chrome, or wrapped inside `Page chrome=\"panes\"` re-decides the frame and the bottom edge that Page owns. A grid whose frame lives in another file is judged where the frame is, and a Freestyle subtree is not judged."
+    law: "A Grammar PaneGrid is the one child of `Page chrome=\"panes\"` or stands inside a Pane; a PaneGrid drawn in a SurfaceCard of any kind, a Page of another chrome, or wrapped inside `Page chrome=\"panes\"` re-decides the frame and the bottom edge that Page owns. A grid whose frame lives in another file is judged where the frame is, and a Freestyle subtree is not judged."
     kinds: [lint]
     gates: [pre-commit, settle, land, ci]
     failureCodes: ["FE_PANE_GRID_FRAME"]
@@ -6210,7 +6216,7 @@ rules:
         ruling: "One spacing scale with no 16; every container holds its content 12 in, and an app names relations through role props, never spacing utilities."
   - id: R351
     code: "FE_TABLE_IN_CARD"
-    law: "A DataTable is not placed inside a SurfaceCard, on the page or in a pane: plain rows with a few facts are a SurfaceListCard with the label outside and the note in its footer, and a table that belongs to a card is an owner decision named in this rule. The rule reads the JSX of the file: a DataTable enclosed by a SurfaceCard element, or rendered by a component of the same file that a SurfaceCard encloses."
+    law: "A DataTable is not placed inside a SurfaceCard, on the page or in a pane: plain rows with a few facts are a SurfaceCard kind=list with the label outside and the note in its footer, and a table that belongs to a card is an owner decision named in this rule. The rule reads the JSX of the file: a DataTable enclosed by a SurfaceCard element, or rendered by a component of the same file that a SurfaceCard encloses."
     kinds: [lint]
     gates: [pre-commit, settle, land, ci]
     failureCodes: ["FE_TABLE_IN_CARD"]
@@ -6230,10 +6236,10 @@ rules:
         date: "2026-11-01"
         source: owner
         quote: "quá phức tạp mới nhét bảng vào card"
-        ruling: "Plain rows are a SurfaceListCard with a bottom note in its footer; a DataTable is not put in a SurfaceCard."
+        ruling: "Plain rows are a SurfaceCard kind=\"list\" with a bottom note in its footer; a DataTable is not put in a SurfaceCard."
   - id: R352
     code: "FE_COMMAND_FILLS_HEADER"
-    law: "A page or pane command hugs its label and sits at the end of its header row: a Grammar Button with width=\"fill\" in the actions of a PageHeader or the labelEnd of a SurfaceCard or SurfaceListCard is refused; width=\"fill\" is for a form submit, an auth panel and a phone action bar, which a file cannot show and the rule does not judge."
+    law: "A page or pane command hugs its label and sits at the end of its header row: a Grammar Button with width=\"fill\" in the actions of a Page header or the labelEnd of a SurfaceCard is refused; width=\"fill\" is for a form submit, an auth panel and a phone action bar, which a file cannot show and the rule does not judge."
     kinds: [lint]
     gates: [pre-commit, settle, land, ci]
     failureCodes: ["FE_COMMAND_FILLS_HEADER"]
@@ -6279,7 +6285,7 @@ rules:
         ruling: "A filter over a collection is a FilterButtonGroup of sm toggle buttons; the TagGroup has no selection."
   - id: R354
     code: "FE_HEADING_ABOVE_CARD"
-    law: "A card has a label by design, so a hand heading above it is wrong: a SectionHeader directly followed, in the same parent, by one SurfaceCard, SurfaceListCard or SurfaceAccordionCard, and a card whose ariaLabel is the header title, are refused; the title moves to the label, the count to fact, the action to labelEnd and the note to footer. Several cards under one header stay legal."
+    law: "A card has a label by design, so a heading over it is wrong: a Section (not kind=\"list\") whose only child is one SurfaceCard (of any kind), and a card whose ariaLabel is the Section title, are refused; the title moves to the label, the count to fact, the action to labelEnd and the note to footer. Several cards under one Section stay legal."
     kinds: [lint]
     gates: [pre-commit, settle, land, ci]
     failureCodes: ["FE_HEADING_ABOVE_CARD"]
@@ -6299,4 +6305,223 @@ rules:
         date: "2026-11-01"
         source: owner
         quote: "bản thân card đã có label, vốn là mục đích thiết kế"
-        ruling: "A card carries its own title, count, action and note; a SectionHeader above a single card is refused."
+        ruling: "A card carries its own title, count, action and note; a Section around a single card is refused."
+  - id: R355
+    code: "FE_SURFACE_CARD_KIND"
+    law: "A SurfaceCard is one component whose kind the compiler checks, and what a kind draws is not drawn by hand around it: a card of the body kind holds no raw ul, ol, li or dl, no Divider, and no Heading standing as a second title, and a Section whose only child is one SurfaceCard frames one subject twice."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["FE_SURFACE_CARD_KIND"]
+    enforcers:
+      - {kind: eslint-grammar-core, id: surface-card-kind}
+    editions: [lite, full]
+    proves:
+      - packages/eslint-grammar-core/src/surface-card.spec.ts
+    exemplifiedBy:
+      - {path: packages/eslint-grammar-core/src/surface-card.spec.ts, editions: [lite, full], codes: [FE_SURFACE_CARD_KIND]}
+    witness:
+      - {path: packages/eslint-grammar-core/src/surface-card.spec.ts, editions: [lite, full], codes: [FE_SURFACE_CARD_KIND]}
+  - id: R356
+    code: "FE_SURFACE_NESTING"
+    law: "Across files, a card is not drawn inside a card, a Pane surface or an overlay, a DataTable is not drawn inside a card, a PaneGrid stands only in Page chrome=\"panes\" or a Pane, a Section or Heading holds more than one card, and a labelled card is not repeated in the peer-card layout Grid kind=\"cards\": the render graph replaces every component by what it draws and every children by what its caller handed it."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["FE_SURFACE_NESTING"]
+    enforcers:
+      - {kind: machine, id: surface-nesting, at: scripts/hfs/architecture/surface-nesting.mjs}
+    editions: [lite, full]
+    docs: [contexts/ui/components/card.md]
+    templateNa: "A template draws no card, table or grid."
+    proves:
+      - {path: packages/hfs/src/surface-nesting.spec.mts, editions: [lite, full], codes: [FE_SURFACE_NESTING]}
+    exemplifiedBy:
+      - {path: packages/hfs/src/surface-nesting.spec.mts, editions: [lite, full], codes: [FE_SURFACE_NESTING]}
+    witness:
+      - {path: packages/hfs/src/surface-nesting.spec.mts, editions: [lite, full], codes: [FE_SURFACE_NESTING]}
+    cases:
+      - id: case-1
+        date: "2026-11-01"
+        source: owner
+        quote: "Surface in surface is banned totally, dialogs and drawers included."
+        ruling: "The one-file card laws (R340, R348, R351, R354, R366) are closed across files by the render graph; the machine reports the inner element and the chain that led to it."
+  - id: R357
+    code: "FE_TEXT_BLOCK"
+    law: "Text holds a run of words: a block component or block element inside it is refused."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["FE_TEXT_BLOCK"]
+    enforcers:
+      - {kind: eslint-grammar-core, id: text-inline-only}
+    editions: [lite, full]
+    docs: [contexts/ui/components/text.md]
+    templateNa: "A template writes no Text with a block inside."
+    proves:
+      - {path: packages/eslint-grammar-core/src/text-rules.spec.ts, editions: [lite, full], codes: [FE_TEXT_BLOCK]}
+    exemplifiedBy:
+      - {path: packages/eslint-grammar-core/src/text-rules.spec.ts, editions: [lite, full], codes: [FE_TEXT_BLOCK]}
+    witness:
+      - {path: packages/eslint-grammar-core/src/text-rules.spec.ts, editions: [lite, full], codes: [FE_TEXT_BLOCK]}
+    cases:
+      - id: case-1
+        date: "2026-11-01"
+        source: owner
+        quote: "A card carries its own label; text is inline."
+        ruling: "Text is inline only, so a layout cannot hide inside a paragraph."
+  - id: R358
+    code: "FE_TEXT_HEADING"
+    law: "A strong Text that is the first child of a group and is followed only by blocks is a hand heading: the group takes a Section title, a card label or Heading."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["FE_TEXT_HEADING"]
+    enforcers:
+      - {kind: eslint-grammar-core, id: no-text-heading}
+    editions: [lite, full]
+    docs: [contexts/ui/components/text.md]
+    templateNa: "A template writes no heading by hand."
+    proves:
+      - {path: packages/eslint-grammar-core/src/text-rules.spec.ts, editions: [lite, full], codes: [FE_TEXT_HEADING]}
+    exemplifiedBy:
+      - {path: packages/eslint-grammar-core/src/text-rules.spec.ts, editions: [lite, full], codes: [FE_TEXT_HEADING]}
+    witness:
+      - {path: packages/eslint-grammar-core/src/text-rules.spec.ts, editions: [lite, full], codes: [FE_TEXT_HEADING]}
+    cases:
+      - id: case-1
+        date: "2026-11-01"
+        source: owner
+        quote: "No free heading in apps."
+        ruling: "A heading is a Section title, a card label or Heading, never a strong Text."
+  - id: R359
+    code: "FE_ONE_HIGHLIGHT"
+    law: "A render states one highlighted thing: a second isHighlight on a Grammar element in one component render is refused."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["FE_ONE_HIGHLIGHT"]
+    enforcers:
+      - {kind: eslint-grammar-core, id: one-highlight-per-render}
+    editions: [lite, full]
+    docs: [contexts/ui/components/card.md]
+    templateNa: "A template highlights nothing."
+    proves:
+      - {path: packages/eslint-grammar-core/src/text-rules.spec.ts, editions: [lite, full], codes: [FE_ONE_HIGHLIGHT]}
+    exemplifiedBy:
+      - {path: packages/eslint-grammar-core/src/text-rules.spec.ts, editions: [lite, full], codes: [FE_ONE_HIGHLIGHT]}
+    witness:
+      - {path: packages/eslint-grammar-core/src/text-rules.spec.ts, editions: [lite, full], codes: [FE_ONE_HIGHLIGHT]}
+    cases:
+      - id: case-1
+        date: "2026-11-01"
+        source: owner
+        quote: "One accent fill per render."
+        ruling: "When two things are highlighted neither is."
+  - id: R361
+    code: "FE_RENDER_PROP_ACROSS_SERVER"
+    law: "A function is not handed from a server file to a client component: React serialises props across that line and a function is not serialisable; pass data, or move the callback into the client branch that owns the interaction."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["FE_RENDER_PROP_ACROSS_SERVER"]
+    enforcers:
+      - {kind: machine, id: render-prop-across-server, at: scripts/hfs/architecture/render-prop-across-server.mjs}
+    editions: [lite, full]
+    docs: [contexts/code/fe/function.md]
+    templateNa: "A template hands no function across the server line."
+    proves:
+      - {path: packages/hfs/src/surface-nesting.spec.mts, editions: [lite, full], codes: [FE_RENDER_PROP_ACROSS_SERVER]}
+    exemplifiedBy:
+      - {path: packages/hfs/src/surface-nesting.spec.mts, editions: [lite, full], codes: [FE_RENDER_PROP_ACROSS_SERVER]}
+    witness:
+      - {path: packages/hfs/src/surface-nesting.spec.mts, editions: [lite, full], codes: [FE_RENDER_PROP_ACROSS_SERVER]}
+    cases:
+      - id: case-1
+        date: "2026-11-01"
+        source: owner
+        quote: "a block takes data"
+        ruling: "A render callback is for a client branch; a block takes data and renders it itself."
+  - id: R362
+    code: "FE_GRAMMAR_TIER_STATE"
+    law: "In the Grammar package a leaf and a composite hold no useState, useReducer or effect, and a component's own props and its ReactNode slots stay inside its tier's budget (leaf 8, branch 12, composite 12, frame 10 props; 3 slots). Both run as counting rules: their findings are the tier refactor list."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["FE_GRAMMAR_TIER_STATE", "FE_GRAMMAR_PROP_BUDGET"]
+    enforcers:
+      - {kind: runtime, id: tier-state, at: packages/grammar/scripts/lint/eslint-plugin.mts}
+      - {kind: runtime, id: prop-budget, at: packages/grammar/scripts/lint/eslint-plugin.mts}
+    editions: [lite, full]
+    docs: [contexts/grammars/README.md#grammar-lint]
+    templateNa: "A template ships no Grammar source."
+    proves:
+      - {path: packages/grammar/scripts/lint/eslint-plugin.mts, editions: [lite, full], codes: [FE_GRAMMAR_TIER_STATE, FE_GRAMMAR_PROP_BUDGET]}
+    exemplifiedBy:
+      - {path: packages/grammar/scripts/lint/eslint-plugin.mts, editions: [lite, full], codes: [FE_GRAMMAR_TIER_STATE, FE_GRAMMAR_PROP_BUDGET]}
+    witness:
+      - {path: packages/grammar/scripts/lint/eslint-plugin.mts, editions: [lite, full], codes: [FE_GRAMMAR_TIER_STATE, FE_GRAMMAR_PROP_BUDGET]}
+    cases:
+      - id: case-1
+        date: "2026-11-02"
+        source: owner
+        quote: "The tier binding of the Grammar is a ladder; a leaf draws and a branch behaves."
+        ruling: "State sits in branches; budgets keep a role from growing into two."
+  - id: R363
+    code: "FE_GRAMMAR_LITERAL"
+    law: "A Grammar component holds no hardcoded colour, length, utility class or numeric style value (`no-literal-look`); its stylesheets read named roles and ramps."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["FE_GRAMMAR_LITERAL"]
+    enforcers:
+      - {kind: runtime, id: no-literal-look, at: packages/grammar/scripts/lint/eslint-plugin.mts}
+    editions: [lite, full]
+    docs: [contexts/grammars/README.md#grammar-lint]
+    templateNa: "A template ships no Grammar source."
+    proves:
+      - {path: packages/grammar/scripts/lint/eslint-plugin.mts, editions: [lite, full], codes: [FE_GRAMMAR_LITERAL]}
+    exemplifiedBy:
+      - {path: packages/grammar/scripts/lint/eslint-plugin.mts, editions: [lite, full], codes: [FE_GRAMMAR_LITERAL]}
+    witness:
+      - {path: packages/grammar/scripts/lint/eslint-plugin.mts, editions: [lite, full], codes: [FE_GRAMMAR_LITERAL]}
+    cases:
+      - id: case-1
+        date: "2026-11-02"
+        source: owner
+        quote: "A component names a role and the stylesheet gives it a value."
+        ruling: "Literals live in the ramps."
+  - id: R366
+    code: "FE_LABEL_IN_GRID"
+    law: "A SurfaceCard with a label repeated in a Grid kind=cards is a tile drawn with the wrong anatomy: a peer you recognise and open names itself inside (SurfaceCard kind=tile), and peers compared by a fact are one kind=list card."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["FE_LABEL_IN_GRID"]
+    enforcers:
+      - {kind: eslint-grammar-core, id: no-label-in-grid}
+    editions: [lite, full]
+    proves:
+      - packages/eslint-grammar-core/src/surface-card.spec.ts
+    exemplifiedBy:
+      - {path: packages/eslint-grammar-core/src/surface-card.spec.ts, editions: [lite, full], codes: [FE_LABEL_IN_GRID]}
+    witness:
+      - {path: packages/eslint-grammar-core/src/surface-card.spec.ts, editions: [lite, full], codes: [FE_LABEL_IN_GRID]}
+  - id: R367
+    code: "FE_SWR_DEFAULT_ARRAY"
+    law: "A loading state is drawn from the page's own reads: a hook folds a read to [] only while it also returns that read's isLoading, a slot takes its loading and error from the reads it draws and never from another slot, a background refresh (isValidating) never drives a loading flag or a status, a placeholder is not the ready data with its lists emptied, and an app draws no skeleton by hand (`no-hand-skeleton`): the Grammar components draw their loading structure from `isLoading`."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["FE_SWR_DEFAULT_ARRAY", "FE_FOREIGN_SLOT_STATUS", "FE_VALIDATING_AS_LOADING", "FE_PLACEHOLDER_OBJECT", "FE_HAND_SKELETON"]
+    enforcers:
+      - {kind: eslint-fe, id: no-swr-default-array}
+      - {kind: eslint-fe, id: no-foreign-slot-status}
+      - {kind: eslint-fe, id: no-validating-as-loading}
+      - {kind: eslint-fe, id: no-placeholder-object}
+      - {kind: eslint-fe, id: no-hand-skeleton}
+    editions: [lite, full]
+    docs: [contexts/ui/loading.md]
+    templateNa: "A template draws no loading state of its own."
+    proves:
+      - {path: packages/eslint-canon-fe/src/skeleton-states.spec.ts, editions: [lite, full], codes: [FE_SWR_DEFAULT_ARRAY, FE_FOREIGN_SLOT_STATUS, FE_VALIDATING_AS_LOADING, FE_PLACEHOLDER_OBJECT, FE_HAND_SKELETON]}
+    exemplifiedBy:
+      - {path: packages/eslint-canon-fe/src/skeleton-states.spec.ts, editions: [lite, full], codes: [FE_SWR_DEFAULT_ARRAY, FE_FOREIGN_SLOT_STATUS, FE_VALIDATING_AS_LOADING, FE_PLACEHOLDER_OBJECT, FE_HAND_SKELETON]}
+    witness:
+      - {path: packages/eslint-canon-fe/src/skeleton-states.spec.ts, editions: [lite, full], codes: [FE_SWR_DEFAULT_ARRAY, FE_FOREIGN_SLOT_STATUS, FE_VALIDATING_AS_LOADING, FE_PLACEHOLDER_OBJECT, FE_HAND_SKELETON]}
+    cases:
+      - id: case-1
+        date: "2026-11-01"
+        source: owner
+        quote: "The skeleton is the ready structure with its data missing; it is drawn from isLoading alone and from the reads the region shows."
+        ruling: "Several reads feed one frame: loading is any read loading with no data; a key change reloads only the region keyed by it; a refresh keeps the content."

package/runtime/knowledge/hfs/slots.yaml

@@ -203,13 +203,20 @@ tiers:
     feature:      {mayImport: [feature, components, hooks, foundation, modules, package], mayImportKinds: {feature: {from: [pages, layouts], to: [overlays]}}} # pages and layouts compose overlays and blocks; data goes through hooks/swr
     # A component never reaches data: config, routes, i18n and types are foundation; every other module and the api
     # transport are reached through a hook (owner decision 2026-09-29).
-    components:   {mayImport: [components, hooks, foundation, package], lowerLayerOnly: true} # blocks, composites, branches, leaves
+    components:   {mayImport: [components, hooks, foundation, package], lowerLayerOnly: true} # blocks, frames, composites, branches, leaves
     # Across domains a hook is imported only through the other domain's public index (hooks/<domain>/index.ts), never deep.
     hooks:        {mayImport: [hooks, foundation, modules, transport, package], mayImportSlots: {transport: {from: [fe.hooks.swr]}}} # only hooks/swr imports an operation
     foundation:   {mayImport: [foundation, package], acyclic: true}               # modules/{config,i18n,routes,types}
     modules:      {mayImport: [foundation, modules, transport, package], acyclic: true}
     transport:    {mayImport: [foundation, modules, package]}                     # modules/api: the one fetch
     package:      {mayImport: [package]}
+  # A component library (packages/grammar): src/core/<tier>/<Name>/ and the data-tier stamp equal the tier folder. A tier imports nothing
+  # above itself (FE_GRAMMAR_TIER_DIRECTION); a shared untiered module under src/core is followed, so one hop of indirection hides nothing.
+  grammar:
+    leaf:         {mayImport: [leaf]}                                             # one element or one vendor part
+    branch:       {mayImport: [leaf, branch]}                                     # a leaf plus its own interaction state
+    composite:    {mayImport: [leaf, branch, composite]}                          # a fixed arrangement of lower tiers
+    frame:        {mayImport: [leaf, branch, composite, frame]}                   # owns a region; the one tier that takes children
 crossOwner: every import across owners targets the owner's public entry (index.ts or index.tsx); never export *.
 crossApp: apps never import each other; shared code is a packages/<pkg> slot.
 
@@ -2270,12 +2277,12 @@ slots:
   - id: fe.components
     since: 3.1.0
     profiles: [fe]
-    path: "apps/<app>/src/components/{blocks,composites,branches,leaves}/<name>/"
+    path: "apps/<app>/src/components/{blocks,frames,composites,branches,leaves}/<name>/"
     presence: optional
     tracked: tracked
     tier: components
     owner: true
-    layers: [blocks, composites, branches, leaves]   # a layer imports only the layers after it
+    layers: [blocks, frames, composites, branches, leaves]   # a layer imports only the layers after it
     requires: [index.tsx]
     allows: [index.tsx, component.tsx, classNames.ts]
     roles: {entry: index.tsx, drawing: component.tsx, styles: classNames.ts}   # the connected entry, the pure drawing half and the styling declarations of a component owner
@@ -2618,12 +2625,12 @@ slots:
     tracked: tracked
     tier: package
     owner: true
-    kinds: [composites, branches, leaves]   # the layer folders under src/ (a package owns no blocks)
+    kinds: [frames, composites, branches, leaves]   # the layer folders under src/ (a package owns no blocks)
     roles: {entry: index.tsx, drawing: component.tsx, styles: classNames.ts}
     requires: [package.json, src/index.ts, tsconfig.json]
     tests: none
     budget: {component.tsx: 300, index.tsx: 200, dataHooks: 6, useState: 6}
-    why: built to dist with explicit named exports; only composites, branches and leaves; no unused export; no colour literal
+    why: built to dist with explicit named exports; only frames, composites, branches and leaves; no unused export; no colour literal
     rules: [FE_PACKAGE_SHAPE, HFS_UNUSED_EXPORT, FE_STYLE_TOKEN_ONLY]
   - id: fe.package.api
     since: 3.1.0

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

@@ -364,7 +364,7 @@ rules:
     cases:
       - id: case-1
         when: "A Grammar component (runtime package)"
-        write: "packages/grammar/src/core/<primitive|composite|branch|composition>/<Name>/index.tsx"
+        write: "packages/grammar/src/core/<leaf|branch|composite|frame>/<Name>/index.tsx"
       - id: case-2
         when: "A Grammar component's class strings and spec (runtime package)"
         write: "sibling classNames.ts and index.spec.tsx"