@starci/eslint-canon-be 3.4.43 → 3.4.44

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,8 @@
1
1
  # Changelog
2
2
 
3
+ ## 3.4.44 - 2026-10-26
4
+ - Fixed: R80 delegated claims map arguments over runtime parameters and reject spreads, effects hidden in `const` preparation, protected or replaced helpers, and runner or manager unions containing lookalikes. Private helpers (including `#private`) and independently judged public delivery helpers retain the transaction proof; public overrides preserve the claim's manager binding and prelude restrictions, including widened parameters and arrow properties. Every declared runner and manager origin must match its owner.
5
+
3
6
  ## 3.4.43 - 2026-10-26
4
7
  - Changed: `inbox-dedupe-required` (R80 `BE_INBOX_DEDUPE_MISSING`) accepts a delivery whose one write transaction hands its work to a typed helper: the sole `.transaction(...)` runs on typeorm's `EntityManager` or on a port the `platform/database` owner declares, its arrow callback returns `this.<method>(..., tx, ...)` of the same class (resolved by the checker), and that async helper claims first with the never-reassigned manager parameter and returns on `false`. The database port also runs the inline claim callback. A helper that never claims, claims after other work or under a condition, claims with another manager, a lookalike runner, a callback that hands work to another object or detaches it, and an ignored claim answer stay refused; every form refused before stays refused.
5
8
 
package/feature-thin.mjs CHANGED
@@ -154,11 +154,11 @@ export const featureThin = {
154
154
  return injectedNamesOf(classNode).has(member) ? member : null
155
155
  }
156
156
 
157
- /** True for a call `f(...)` where `f` is imported from a `*.mapper.ts` (the pure mapping functions). */
157
+ /** True for an imported pure `*.mapper.ts` function, resolved through any facade re-exports to its declaration. */
158
158
  const isMapperCall = (callee) => {
159
- if (callee.type !== "Identifier") return false
160
- const found = importOf(context, callee)
161
- return found !== null && /(?:^|\/)[^/]+\.mapper(?:\.[cm]?[jt]s)?$/.test(found.source.replace(/\\/g, "/"))
159
+ if (callee.type !== "Identifier" || importOf(context, callee) === null) return false
160
+ const declarations = aliasTarget(context, callee)?.getDeclarations() ?? []
161
+ return declarations.length > 0 && declarations.every((declaration) => roleOf(declaration.getSourceFile().fileName) === "mapper")
162
162
  }
163
163
 
164
164
  /** True for a call `f(...)` where `f` is imported and its declaration lives outside the feature tier (a function of the modules). */
package/idempotency.mjs CHANGED
@@ -24,23 +24,26 @@
24
24
  * `EntityManager` or as a port the `platform/database` owner declares; the callback's one parameter is typed `EntityManager`.
25
25
  * Either the actual selected inline async callback claims with that manager in its first statement, then returns on false,
26
26
  * or an arrow callback hands its whole work to one `this.<method>(..., tx, ...)` of the same class, resolved by the checker:
27
- * that async helper receives the manager in a never-reassigned `EntityManager` parameter, prepares only `const` arguments,
28
- * and its first await is the claim with that parameter at its top level, followed by the return on false:
27
+ * that async helper is private or a public delivery method judged in its own right, receives the manager in a never-reassigned
28
+ * `EntityManager` runtime parameter, and prepares only `const` arguments without this/manager access, writes, construction,
29
+ * awaits or calls other than free functions. Its first await is the claim with that parameter at its top level, followed by
30
+ * the return on false:
29
31
  * return this.manager.transaction((tx) => this.recordInTransaction(delivery, tx))
30
32
  * async recordInTransaction(delivery: Delivery, manager: EntityManager) {
31
33
  * const key = keyOf(delivery)
32
34
  * if (!(await this.inbox.claim(source, key, manager))) return this.readRepeat(delivery, manager)
33
35
  * return this.write(delivery, manager)
34
36
  * }
35
- * No outer work runs after a duplicate. A lookalike runner (a `transaction` method on a type no package or database owner
36
- * declares), a callback that hands work to another object and a helper reached through a further call are refused.
37
- * Synchronous effects before a claim, getters and helpers called past the first one stay review questions.
37
+ * No outer work runs after a duplicate. Every runner and manager type origin must match its declared owner; unions with
38
+ * lookalikes, spread handoffs, protected or replaced helpers, and callbacks handing work to another object are refused.
39
+ * Effects hidden inside free functions or getters and helpers called past the first one stay review questions.
38
40
  */
41
+ import ts from "typescript"
39
42
  import { hfsOf } from "./lib/hfs.mjs"
40
- import { walk } from "./lib/ast.mjs"
43
+ import { keyName, walk } from "./lib/ast.mjs"
41
44
  import { baseName, isOwnedType, ownerNameOf } from "./lib/ports.mjs"
42
45
  import { resolveVariable } from "./lib/transactions.mjs"
43
- import { isPackageType, typeOrigins, typed } from "./lib/types.mjs"
46
+ import { typeOrigins, typed } from "./lib/types.mjs"
44
47
  import { mutationIdempotent } from "./lib/client-idempotency.mjs"
45
48
 
46
49
  /** The `Inbox` port of `platform/inbox`. */
@@ -102,10 +105,20 @@ const hasPriorEffect = (expression, call) => {
102
105
  /** A transaction port the `platform/database` owner declares: a receiver typed by that owner, never by its name. */
103
106
  const isDatabasePort = (context, node) => {
104
107
  const hfs = hfsOf(context)
105
- return typeOrigins(context, node).some((origin) =>
108
+ const origins = typeOrigins(context, node)
109
+ return origins.length > 0 && origins.every((origin) =>
106
110
  origin.module === null && hfs.tierOf(origin.file) === "platform" && ownerNameOf(hfs, origin.file) === "database")
107
111
  }
108
112
 
113
+ /** Every declared alternative must be TypeORM's manager: one genuine union member cannot vouch for a lookalike. */
114
+ const isEntityManager = (context, node) => {
115
+ const origins = typeOrigins(context, node)
116
+ return origins.length > 0 && origins.every((origin) => origin.name === "EntityManager" && origin.module === "typeorm")
117
+ }
118
+
119
+ /** TypeScript erases a `this` parameter, so only these parameters receive call arguments at runtime. */
120
+ const runtimeParams = (method) => method.value.params.filter((param) => !(param.type === "Identifier" && param.name === "this"))
121
+
109
122
  /** The callback a sole, returned or awaited `.transaction(...)` runs on an EntityManager or the database port, and its manager parameter. */
110
123
  const soleTransactionCallback = (context, body) => {
111
124
  if (body.body.length !== 1) return null
@@ -117,7 +130,7 @@ const soleTransactionCallback = (context, body) => {
117
130
  if (call?.type !== "CallExpression" || callee.type !== "MemberExpression" || callee.computed
118
131
  || callee.property.type !== "Identifier" || callee.property.name !== "transaction" || hasPriorEffect(call, call)) return null
119
132
  let callback = null
120
- if (isPackageType(context, callee.object, "EntityManager", "typeorm")) {
133
+ if (isEntityManager(context, callee.object)) {
121
134
  // TypeORM runs arg0 when it is a function, otherwise arg1. Never accept a later, ignored callback.
122
135
  const isolation = call.arguments[0]
123
136
  callback = call.arguments.length === 1 ? isolation
@@ -127,7 +140,7 @@ const soleTransactionCallback = (context, body) => {
127
140
  } else if (isDatabasePort(context, callee.object) && call.arguments.length === 1) callback = call.arguments[0]
128
141
  if (!callback || !["ArrowFunctionExpression", "FunctionExpression"].includes(callback.type) || callback.params.length !== 1) return null
129
142
  const manager = callback.params[0]
130
- if (manager.type !== "Identifier" || !isPackageType(context, manager, "EntityManager", "typeorm")) return null
143
+ if (manager.type !== "Identifier" || !isEntityManager(context, manager)) return null
131
144
  return { callback, manager }
132
145
  }
133
146
 
@@ -173,7 +186,48 @@ const handedCall = (callback) => {
173
186
  const call = expression?.type === "AwaitExpression" ? expression.argument : expression
174
187
  const callee = call?.callee
175
188
  return call?.type === "CallExpression" && callee.type === "MemberExpression" && !callee.computed
176
- && callee.object.type === "ThisExpression" && callee.property.type === "Identifier" ? call : null
189
+ && callee.object.type === "ThisExpression" && ["Identifier", "PrivateIdentifier"].includes(callee.property.type) ? call : null
190
+ }
191
+
192
+ /** Argument preparation cannot start instance or transactional work before the inbox claim. */
193
+ const preparesArguments = (context, statement, manager) => {
194
+ if (statement.type !== "VariableDeclaration" || statement.kind !== "const") return false
195
+ let safe = true
196
+ walk(statement, (node) => {
197
+ if (node.type === "ThisExpression" || (node.type === "Identifier" && isParameter(context, node, manager))
198
+ || ["AwaitExpression", "NewExpression", "AssignmentExpression", "UpdateExpression"].includes(node.type)
199
+ || (node.type === "CallExpression" && node.callee.type !== "Identifier")) safe = false
200
+ }, { intoFunctions: false })
201
+ return safe
202
+ }
203
+
204
+ /** An assignment anywhere in the class can replace the method that the checker resolved for the handoff. */
205
+ const replacesHelper = (classBody, helper) => {
206
+ let replaced = false
207
+ walk(classBody, (node) => {
208
+ if (node.type !== "AssignmentExpression") return
209
+ const target = node.left
210
+ if (target.type === "MemberExpression" && target.object.type === "ThisExpression"
211
+ && (!target.computed || target.property.type === "Literal")
212
+ && (target.property.type === "PrivateIdentifier") === (helper.key.type === "PrivateIdentifier")
213
+ && keyName(target.property) === keyName(helper.key)) replaced = true
214
+ })
215
+ return replaced
216
+ }
217
+
218
+ /** The helper body must claim first with its unchanged runtime manager, after only argument preparation. */
219
+ const helperClaim = (context, helper, param) => {
220
+ if (!helper.value?.async || helper.value.body?.type !== "BlockStatement"
221
+ || param?.type !== "Identifier" || !isEntityManager(context, param)) return null
222
+ const body = helper.value.body
223
+ const found = claimStatement(body)
224
+ if (!found) return null
225
+ const before = body.body.slice(0, body.body.indexOf(found.statement))
226
+ if (before.some((statement) => !preparesArguments(context, statement, param))) return null
227
+ const claim = found.awaited.argument
228
+ if (claim?.type !== "CallExpression" || !isParameter(context, claim.arguments[2], param, { unwritten: true })
229
+ || hasPriorEffect(found.statement, claim)) return null
230
+ return found.awaited
177
231
  }
178
232
 
179
233
  /**
@@ -183,7 +237,7 @@ const handedCall = (callback) => {
183
237
  */
184
238
  const delegatedClaim = (context, delivery, { callback, manager }) => {
185
239
  const call = handedCall(callback)
186
- if (!call || hasPriorEffect(call, call)) return null
240
+ if (!call || call.arguments.some((argument) => argument.type === "SpreadElement") || hasPriorEffect(call, call)) return null
187
241
  const position = call.arguments.findIndex((argument) => argument.type === "Identifier" && argument.name === manager.name)
188
242
  if (position < 0 || !isParameter(context, call.arguments[position], manager)) return null
189
243
  const { checker, toTs } = typed(context)
@@ -191,17 +245,11 @@ const delegatedClaim = (context, delivery, { callback, manager }) => {
191
245
  const helper = declarations.length === 1
192
246
  ? delivery.parent.body.find((member) => member.type === "MethodDefinition" && toTs(member) === declarations[0]) : undefined
193
247
  if (!helper || helper === delivery || helper.kind !== "method" || helper.static || !helper.value.async || !helper.value.body) return null
194
- const param = helper.value.params[position]
195
- if (param?.type !== "Identifier" || !isPackageType(context, param, "EntityManager", "typeorm")) return null
196
- const body = helper.value.body
197
- const found = claimStatement(body)
198
- if (!found) return null
199
- const before = body.body.slice(0, body.body.indexOf(found.statement))
200
- if (before.some((statement) => statement.type !== "VariableDeclaration" || statement.kind !== "const")) return null
201
- const claim = found.awaited.argument
202
- if (claim?.type !== "CallExpression" || !isParameter(context, claim.arguments[2], param, { unwritten: true })
203
- || hasPriorEffect(found.statement, claim)) return null
204
- return found.awaited
248
+ const params = runtimeParams(helper)
249
+ // A public delivery contract carries its claim and manager obligations into every override.
250
+ if (helper.accessibility === "protected" || (helper.accessibility !== "private" && helper.key.type !== "PrivateIdentifier"
251
+ && (!params[0] || !isDeliveryParam(context, params[0]))) || replacesHelper(delivery.parent, helper)) return null
252
+ return helperClaim(context, helper, params[position])
205
253
  }
206
254
 
207
255
  /** The first awaited claim of a delivery that runs as one transaction: inline in its callback, or in the typed helper that callback delegates to. */
@@ -210,14 +258,61 @@ const transactionClaim = (context, delivery) => {
210
258
  if (!transaction) return null
211
259
  return inlineClaim(context, transaction) ?? delegatedClaim(context, delivery, transaction)
212
260
  }
261
+
262
+ /** A delivery's type, including a union alternative, exposes the sender's `eventId`. */
263
+ const hasEventId = (checker, type) =>
264
+ (type.isUnion() ? type.types : [type]).some((part) => checker.getPropertyOfType(part, "eventId") !== undefined)
265
+
213
266
  /** Whether a parameter's type has an `eventId` property: the shape of a delivery. */
214
267
  const isDeliveryParam = (context, param) => {
215
268
  const target = param.type === "TSParameterProperty" ? param.parameter : param.type === "AssignmentPattern" ? param.left : param
216
269
  const { checker, toTs } = typed(context)
217
270
  const tsNode = toTs(target)
218
271
  if (!tsNode) return false
219
- const type = checker.getTypeAtLocation(tsNode)
220
- return (type.isUnion() ? type.types : [type]).some((part) => checker.getPropertyOfType(part, "eventId") !== undefined)
272
+ return hasEventId(checker, checker.getTypeAtLocation(tsNode))
273
+ }
274
+
275
+ /** The runtime parameter the declared signature's first awaited claim uses, including declarations in another source file. */
276
+ const claimedManagerPosition = (checker, signature) => {
277
+ let awaited = null
278
+ const visit = (node) => {
279
+ if (ts.isAwaitExpression(node) && (!awaited || node.end < awaited.end)) awaited = node
280
+ ts.forEachChild(node, (child) => { if (!ts.isFunctionLike(child)) visit(child) })
281
+ }
282
+ const body = signature.getDeclaration()?.body
283
+ if (body) visit(body)
284
+ const claim = awaited?.expression
285
+ if (!claim || !ts.isCallExpression(claim) || !ts.isPropertyAccessExpression(claim.expression)
286
+ || claim.expression.name.text !== "claim" || !claim.arguments[2]) return -1
287
+ const manager = checker.getSymbolAtLocation(claim.arguments[2])
288
+ return manager ? signature.parameters.indexOf(manager) : -1
289
+ }
290
+
291
+ /** An override preserves inherited delivery and transaction-manager obligations even when it widens its own parameter. */
292
+ const inheritedDelivery = (context, method) => {
293
+ const name = keyName(method.key)
294
+ const result = { delivery: false, managers: new Set() }
295
+ if (name === null) return result
296
+ const { checker, toTs } = typed(context)
297
+ const location = toTs(method)
298
+ const seen = new Set()
299
+ const visit = (type) => {
300
+ if (seen.has(type)) return
301
+ seen.add(type)
302
+ const member = checker.getPropertyOfType(type, name)
303
+ const signatures = member ? checker.getTypeOfSymbolAtLocation(member, location).getCallSignatures() : []
304
+ for (const signature of signatures) {
305
+ const param = signature.parameters[0]
306
+ if (!param || !hasEventId(checker, checker.getTypeOfSymbolAtLocation(param, location))) continue
307
+ result.delivery = true
308
+ const manager = claimedManagerPosition(checker, signature)
309
+ if (manager >= 0) result.managers.add(manager)
310
+ }
311
+ for (const base of checker.getBaseTypes(type) ?? []) visit(base)
312
+ }
313
+ const owner = checker.getTypeAtLocation(toTs(method.parent.parent))
314
+ for (const base of checker.getBaseTypes(owner) ?? []) visit(base)
315
+ return result
221
316
  }
222
317
 
223
318
  /** A service method that takes a delivery claims the event through the shared inbox before it acts. */
@@ -238,23 +333,37 @@ export const inboxDedupeRequired = {
238
333
  if (!baseName(filename).endsWith(".service.ts") || !slot || slot.startsWith("be.tests.")) return {}
239
334
  // The event bus publishes events (their shape carries an `eventId`) and its runtime claims the inbox before a consumer runs: no delivery method here.
240
335
  if (slot.startsWith("be.platform") && ownerNameOf(hfs, filename) === "event-bus") return {}
336
+ const judgeClaim = (node, inherited) => {
337
+ const body = node.value?.body
338
+ let awaited = body?.type === "BlockStatement" ? transactionClaim(context, node) ?? firstAwait(body) : null
339
+ if (inherited.managers.size > 0) {
340
+ const params = node.value?.params ? runtimeParams(node) : []
341
+ if (![...inherited.managers].every((position) => helperClaim(context, node, params[position]) === awaited)) awaited = null
342
+ }
343
+ const call = awaited?.argument
344
+ const claims = call?.type === "CallExpression"
345
+ && call.callee.type === "MemberExpression"
346
+ && !call.callee.computed
347
+ && call.callee.property.type === "Identifier"
348
+ && call.callee.property.name === "claim"
349
+ && call.arguments.length >= 2
350
+ && isInboxType(context, call.callee.object)
351
+ if (!claims) context.report({ node: node.key, messageId: "noClaim" })
352
+ else if (!returnsOnFalse(awaited)) context.report({ node: node.key, messageId: "noEarlyReturn" })
353
+ }
241
354
  return {
242
355
  MethodDefinition(node) {
243
356
  if (node.kind !== "method" || node.static || node.key.type === "PrivateIdentifier" || !node.value.body) return
244
357
  if (node.accessibility === "private" || node.accessibility === "protected") return
245
- const first = node.value.params[0]
246
- if (!first || !isDeliveryParam(context, first)) return
247
- const awaited = transactionClaim(context, node) ?? firstAwait(node.value.body)
248
- const call = awaited?.argument
249
- const claims = call?.type === "CallExpression"
250
- && call.callee.type === "MemberExpression"
251
- && !call.callee.computed
252
- && call.callee.property.type === "Identifier"
253
- && call.callee.property.name === "claim"
254
- && call.arguments.length >= 2
255
- && isInboxType(context, call.callee.object)
256
- if (!claims) context.report({ node: node.key, messageId: "noClaim" })
257
- else if (!returnsOnFalse(awaited)) context.report({ node: node.key, messageId: "noEarlyReturn" })
358
+ const first = runtimeParams(node)[0]
359
+ const inherited = inheritedDelivery(context, node)
360
+ if (!(first && isDeliveryParam(context, first)) && !inherited.delivery) return
361
+ judgeClaim(node, inherited)
362
+ },
363
+ PropertyDefinition(node) {
364
+ if (node.static || node.key.type === "PrivateIdentifier" || node.accessibility === "private" || node.accessibility === "protected") return
365
+ const inherited = inheritedDelivery(context, node)
366
+ if (inherited.delivery) judgeClaim(node, inherited)
258
367
  },
259
368
  }
260
369
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@starci/eslint-canon-be",
3
- "version": "3.4.43",
3
+ "version": "3.4.44",
4
4
  "description": "The StarCi back-end lint canon: every rule its laws publish, gathered as one flat-config plugin.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -0,0 +1,102 @@
1
+ schema: starci/knowledge-source@1
2
+ id: grammars
3
+ title: Grammar families
4
+ purpose: |
5
+ Catalog of authored UI Grammar families. Inventory only — not a default-family rule.
6
+ The selected design specification names the applicable installed family. The app binds that choice
7
+ explicitly in sides.fe.grammar; the catalog resolves its lint package and component contract.
8
+ A missing or ambiguous family never silently resolves to a family. DNA snapshots describe the
9
+ observed implementation; they do not install packages or prove current rendered behavior.
10
+ appliesTo:
11
+ - grammar
12
+ provenance:
13
+ limitations: |
14
+ Component names, tokens and gap tables describe the reference family at observation time.
15
+ Verify actual package identity/version, exported types, CSS and renderer source in the selected
16
+ repository before using snapshot APIs or gaps. Record current source references in the selected
17
+ .starciwork node; an old source census is not current UAT evidence. The current public consumer
18
+ entry observed for FE work is @starci/grammar/common — confirm installed exports before import.
19
+ The `common` entry is a DNA snapshot of that semantic entry and nothing more: it declares no palette,
20
+ no family boundary and no composition playbook, because the entry itself ships none of them.
21
+ guidance:
22
+ - id: catalog-not-default
23
+ requirement: |
24
+ Do not treat this catalog as selecting a default Grammar family. Family choice belongs to the
25
+ current design specification and its explicit sides.fe.grammar declaration.
26
+ rationale: |
27
+ Silent fallback to StarCi would invent product direction and override an absent/ambiguous design.
28
+ - id: verify-before-use
29
+ requirement: |
30
+ Before applying snapshot APIs or recorded gaps, inspect the selected repository's package
31
+ identity/version, exported types, CSS and renderer source.
32
+ rationale: |
33
+ Snapshots are historical; installed exports may differ. Inventing missing APIs is forbidden.
34
+ - id: ui-owns-universal
35
+ requirement: |
36
+ Common semantics, renderer anatomy, state and accessibility remain owned by knowledge/ui.
37
+ A family owns its scoped visual realization and promoted idioms; the product owns its facts,
38
+ content, routes and approved composition.
39
+ Apply FE-RULE-OWNERSHIP in knowledge/patterns/fe/index.yaml when placing requirements and checks.
40
+ rationale: |
41
+ Keeps universal UI law separate from family-scoped DNA and product composition.
42
+ topics:
43
+ - id: common
44
+ path: common/DNA.yaml
45
+ title: Common Grammar — DNA
46
+ summary: |
47
+ Generated DNA snapshot of the `@starci/grammar/common` public entry: custom properties,
48
+ the 110 renderers of its registry, their classes, stamped rule ids and recorded gaps. The DNA owns the observed package
49
+ version and source inventory. Common supplies anatomy, not colour. The snapshot is drift-checked.
50
+ - id: starci
51
+ path: starci/index.yaml
52
+ title: StarCi Core Grammar
53
+ summary: |
54
+ Historical snapshot of the StarCi Core family — DNA, idioms, playbook (including composing the
55
+ 0.5.0 forms, overlays and navigation chrome) and family boundaries.
56
+ - id: offset-pop
57
+ path: offset-pop/index.yaml
58
+ title: Offset Pop Grammar
59
+ summary: |
60
+ Snapshot of the product-neutral Offset Pop family — cream canvas, ink outline plus hard offset
61
+ shadow, one pink decision accent with a text-safe accent for text — with DNA, idioms, a
62
+ mobile-first playbook for playful learning or consumer apps, and family boundaries including two
63
+ decisions flagged for the family owner.
64
+ families:
65
+ - id: common
66
+ title: common
67
+ componentContract:
68
+ package: '@starci/grammar'
69
+ entry: '@starci/grammar/common'
70
+ styleEntry: '@starci/grammar/common.css'
71
+ peers: [react, '@heroui/react', '@xyflow/react']
72
+ packageSnapshot: common/DNA.yaml
73
+ scope: |
74
+ DNA snapshot only. This catalog carries no Common-side family boundary, idiom set or composition
75
+ playbook: `@starci/grammar/common` is the semantic/props entry every visual family is defined over
76
+ (`defineGrammarFamily`), not a family that ships a palette, so `authority`, `reusableStyle`,
77
+ `productComposition` and `index` have nothing to name here. Universal semantics, renderer anatomy,
78
+ state and accessibility remain owned by knowledge/ui.
79
+ - id: starci
80
+ title: starci
81
+ contractRef: common
82
+ lint:
83
+ package: '@starci/eslint-grammar-starci'
84
+ factory: starciGrammarConfig
85
+ prefix: starci-grammar
86
+ authority: starci/family.yaml
87
+ packageSnapshot: starci/DNA.yaml
88
+ reusableStyle: starci/idioms.yaml
89
+ productComposition: starci/playbook.yaml
90
+ index: starci/index.yaml
91
+ - id: offset-pop
92
+ title: offset-pop
93
+ contractRef: common
94
+ lint:
95
+ package: '@starci/eslint-grammar-offset-pop'
96
+ factory: offsetPopGrammarConfig
97
+ prefix: starci-grammar
98
+ authority: offset-pop/family.yaml
99
+ packageSnapshot: offset-pop/DNA.yaml
100
+ reusableStyle: offset-pop/idioms.yaml
101
+ productComposition: offset-pop/playbook.yaml
102
+ index: offset-pop/index.yaml
@@ -21,30 +21,44 @@ pins:
21
21
  install: registry
22
22
  side: fe
23
23
  source: packages/heroicons/package.json
24
- why: 'StarCi custom Heroicons-compatible cuts; eslint-canon-fe (icon.mjs) admits @starci/heroicons/24/outline and /16/solid as icon sources, so an app that uses them gets this exact version.'
24
+ why: 'StarCi custom Heroicons-compatible cuts; eslint-grammar-starci (icon.mjs) admits @starci/heroicons/24/outline and /16/solid as icon sources, so an app that uses them gets this exact version.'
25
25
  '@starci/grammar':
26
- version: 0.12.1
26
+ version: 0.12.3
27
27
  group: starci
28
28
  install: registry
29
29
  side: fe
30
30
  source: packages/grammar/package.json
31
31
  why: 'the grammar front ends read: the brand layer sets `--font-sans` and `--font-mono` and the grammar reads them; it carries the Input tel kind, the copyable and read-only Input, the IconButton disclosure props and count badge, ChatBubble, FillViewport, Textarea mentions and Enter-to-send, the leading PrimaryRailLayout rail, the plate-less Image, ListRow, the soft Alert, Progress steps, the floating primary IconButton, FlowGraph, the STATE-8 loading views and the bordered selectable TagGroup chips. The runtime source version wins for a @starci package.'
32
32
  '@starci/eslint-canon-be':
33
- version: 3.4.43
33
+ version: 3.4.44
34
34
  group: starci
35
35
  install: registry
36
36
  side: be
37
37
  source: packages/eslint/be/package.json
38
38
  why: 'the back-end ESLint canon: `loadHfs(import.meta.url)` of be/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the be side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; `starciBeConfig({ hfs: loadHfs(import.meta.url) })` is the typed factory and the BE-CONVENTION laws are its rules.'
39
39
  '@starci/eslint-canon-fe':
40
- version: 8.4.42
40
+ version: 9.0.0
41
41
  group: starci
42
42
  install: registry
43
43
  side: fe
44
44
  source: packages/eslint/fe/package.json
45
45
  why: 'the front-end ESLint canon: `loadHfs(import.meta.url)` of fe/eslint.config.mjs finds the app-root hfs.json (kind app) and gives every linted file the view of the fe side, and the project graph is built per side; its bundled runtime copies (slots, canon-pins, failure codes, the architecture machine) put .starcistacks and .sops.yaml at the app root; the front end has no tests (FE_NO_TESTS R97 in hfs) and no-vietnamese-in-source (R91) applies.'
46
+ '@starci/eslint-grammar-starci':
47
+ version: 0.12.3
48
+ group: starci
49
+ install: registry
50
+ side: fe
51
+ source: packages/eslint/grammar-starci/package.json
52
+ why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
53
+ '@starci/eslint-grammar-offset-pop':
54
+ version: 0.12.3
55
+ group: starci
56
+ install: registry
57
+ side: fe
58
+ source: packages/eslint/grammar-offset-pop/package.json
59
+ why: 'the Offset Pop Grammar component API lint, versioned with @starci/grammar; its shared component contract comes from the StarCi family lint without copying rules.'
46
60
  '@starci/stylelint-canon':
47
- version: 2.0.11
61
+ version: 2.0.12
48
62
  group: starci
49
63
  install: registry
50
64
  side: fe
@@ -77,14 +91,14 @@ pins:
77
91
  source: packages/test-world/package.json
78
92
  why: 'the shared e2e library of every back end (R47, R48), a devDependency of every back end: the warm stack behind toxiproxy, the network-edge fakes, the Nest boot, the typed useTestWorld handle, useSandbox for contract specs and the outage lock. Kafka is real own infra (the one digest-pinned apache/kafka KRaft image, a broker listener and proxy per slot, slot-prefixed topics, consumer groups and client ids) and Postgres is schema-per-context (a schema and a login role per context in a shared database). Each worker has its own data slot (<ns>_w<k>) with its own databases, Keycloak realm, leased Redis DB, bucket/collection/topic prefixes, fakes host, toxiproxy proxies and outage lock; a run provisions min(jest workers, workers cap, default 2) slots, and state file protocol 2 pairs exactly with @starci/jest-preset (TEST_WORLD_PAIR_MISMATCH otherwise). A modules world boots real peer apps beside its modules, world.apps.<name>.during(fn) is the outage of a peer app, w.keycloak.clientSecret(client) answers the run-generated secret of a confidential realm client, world.keycloak.events/sessions read the realm user events and live sessions, world.infra.postgresql.connection(name) takes one database connection down while the others serve, and world.resolve and scope.resolve take any Nest token. Every path a declaration names (`stack`, seeds, the realm, Dockerfiles) resolves from the app root (the directory of hfs.json); the globalSetup registers the path aliases as TypeScript resolves them. Its CLI main is exported at ./cli for starci app stack.'
79
93
  '@starci/cli':
80
- version: 1.7.34
94
+ version: 1.7.35
81
95
  group: starci
82
96
  install: registry
83
97
  side: both
84
98
  source: packages/cli/package.json
85
99
  why: 'the only StarCi command package; product repositories install it for starci app, while @starci/hfs remains its pinned transitive implementation.'
86
100
  '@starci/hfs':
87
- version: 4.7.34
101
+ version: 4.7.35
88
102
  group: starci
89
103
  install: registry
90
104
  side: both
@@ -380,7 +394,7 @@ pins:
380
394
  version: 2.2.0
381
395
  group: ui
382
396
  side: fe
383
- why: 'the base of the one application icon set (fe-stack icons, with @starci/heroicons for the glyphs it lacks); eslint-canon-fe (icon.mjs) admits @heroicons/react/24/outline and /16/solid.'
397
+ why: 'the base of the one application icon set (fe-stack icons, with @starci/heroicons for the glyphs it lacks); eslint-grammar-starci (icon.mjs) admits @heroicons/react/24/outline and /16/solid.'
384
398
  '@dicebear/core':
385
399
  version: 10.4.0
386
400
  group: ui
@@ -237,6 +237,13 @@ concerns:
237
237
  pattern: FE-LINT
238
238
  forbids: []
239
239
  why: the canon lint and format configuration.
240
+ - id: grammar-lint
241
+ tier: opt
242
+ packages: ['@starci/eslint-grammar-starci', '@starci/eslint-grammar-offset-pop']
243
+ home: [fe.source-root-pinned]
244
+ pattern: FE-RULE-OWNERSHIP
245
+ forbids: []
246
+ why: The selected Grammar family's lint package runs beside the universal front-end canon; the family catalog declares the package and factory.
240
247
  - id: auth-supabase
241
248
  tier: opt
242
249
  packages: ['@supabase/supabase-js', '@supabase/ssr']
@@ -8,7 +8,7 @@
8
8
  # An enforcer is a check that exists or one still owed. `status: planned` marks one owed: the architecture machine, the
9
9
  # hfs CLI, stylelint and Sonar lanes fill them, and the entry's `status` is removed the day the check ships (the check
10
10
  # refuses a planned enforcer that already exists). An existing eslint enforcer is a rule id of the plugin
11
- # `@starci/eslint-canon-be` or `@starci/eslint-canon-fe`; an existing machine, hfs or work-validate enforcer names the file
11
+ # the backend, universal frontend or selected Grammar family lint package; an existing machine, hfs or work-validate enforcer names the file
12
12
  # (`at`) that emits one of the rule's codes. scripts/checks/check-hfs-rules.mjs holds all of this to the packages, the
13
13
  # scripts and modules/kernel/failure-codes.yaml.
14
14
  #
@@ -19,8 +19,8 @@
19
19
  schema: starci/hfs-rules@3
20
20
  version: 3.1.0
21
21
  gates:
22
- pre-commit: the managed .husky/pre-commit at the app root - starci app hygiene (staged .starciwork and .starcistacks paths, secrets guard, a new back-end logic file staged without its unit spec), typecheck, ESLint per side and stylelint on the staged files, prettier --check, the unit specs the staged files touch
23
- pre-push: typecheck, lint (starci app lint), format:check and the unit specs affected since origin/main; runs every pre-commit rule again
22
+ pre-commit: the managed L0 hook runs app hygiene, managed-file drift, ESLint per side and stylelint on staged source, and prettier on staged files; typecheck and targeted specs belong to the op gate under R225
23
+ pre-push: the managed app hook validates an annotated release tag and the recorded L4 evidence for HEAD, permitting the release refs and backup namespace under R225; it starts no source check, build or test
24
24
  settle: the op gate `starci gate run` over the op's changed files (merge guard, starci app lint --changed, codegen, tsc, the slice's specs; only findings new against the workflow's previous checkpoint block), re-read at starci kernel settle, which refuses a red done; a green settle commits the op's checkpoint on wf-<workflowId>
25
25
  land: the workflow's finish, the only time main is touched - gate.mjs over the whole workflow branch against its merge-base with main, the merge guard, review.verify of the exact head that lands, the branch rebased onto main, then main fast-forwarded and pushed
26
26
  ci: GitHub Actions runs the same pinned starci app lint, format:check, typecheck, unit with the per-file coverage threshold, build:be and build:fe, then the Sonar scan and gate
@@ -28,7 +28,8 @@ gates:
28
28
  runtime: "`starci runtime check` (npm run check) of the StarCi runtime repository itself: scripts/checks/check-runtime.mjs runs node --check, scripts/hfs/runtime-check.mjs with knowledge/hfs/runtime-slots.yaml, and the retained self-checks"
29
29
  enforcerKinds:
30
30
  eslint-be: a rule of the plugin @starci/eslint-canon-be (id without the plugin prefix)
31
- eslint-fe: a rule of the plugin @starci/eslint-canon-fe (id without the plugin prefix)
31
+ eslint-fe: a universal rule of @starci/eslint-canon-fe (id without the plugin prefix)
32
+ eslint-grammar-starci: a selected Grammar family rule sharing the common component API, resolved through the family canon binding (id without the plugin prefix; FE-RULE-OWNERSHIP)
32
33
  stylelint: a rule of the @starci/stylelint-canon package
33
34
  machine: a check of the architecture machine (scripts/hfs/architecture), which reads the import graph
34
35
  hfs: a check of the hfs CLI that reads the repository tree, configuration, contracts or catalogs
@@ -1141,7 +1142,7 @@ rules:
1141
1142
 
1142
1143
  - id: R56
1143
1144
  code: "FE_HOOKS_ARE_HOOKS"
1144
- law: "`hooks/` hold hooks only: `hooks/swr` (one SWR wrapper per modules/api operation), `hooks/rhf` (forms), `hooks/zustand/<store>`, `hooks/socketio`, `hooks/effects`, `hooks/reuseables` and `hooks/<domain>` with one shared file per domain; a product hook is defined only there and imported through its index. A function in `hooks/` is a hook when it calls a hook: a React, SWR or Redux hook, a `use*` of the app's own `hooks/` folders (a `hooks/swr` wrapper, a sibling domain hook; resolved by TypeScript symbol resolution), or a listed library hook (next-intl, next/navigation, react-hook-form, zustand); a file that exports a non-hook still fails (owner ruling 2026-10-16 \"Theo y tro\")."
1145
+ law: "`hooks/` hold hooks only: `hooks/swr` (one SWR wrapper per modules/api operation), `hooks/rhf` (forms), `hooks/zustand/<store>`, `hooks/socketio`, `hooks/effects`, `hooks/reuseables` and `hooks/<domain>` with one shared file per domain; a product hook is defined only there and imported through its index. A function in `hooks/` is a hook when it calls a hook: a React, SWR or Redux hook, a `use*` of the app's own `hooks/` folders (a `hooks/swr` wrapper, a sibling domain hook; resolved by TypeScript symbol resolution), or a listed library hook (next-intl, next/navigation, next-themes useTheme, react-hook-form, zustand); a file that exports a non-hook still fails (owner ruling 2026-10-16 \"Theo y tro\")."
1145
1146
  kinds: [lint, codemod]
1146
1147
  gates: [settle, land, ci]
1147
1148
  failureCodes: ["FE_HOOKS_ARE_HOOKS", "FE_CUSTOM_HOOK_LOCATION", "FE_BLOCK_PRODUCT_HOOK_DEFINITION", "FE_COMPONENT_DEEP_HOOK_IMPORT"]
@@ -1209,7 +1210,7 @@ rules:
1209
1210
  code: "FE_I18N_PLACEMENT"
1210
1211
  editions: [lite, full]
1211
1212
  docs: [docs/architecture.md#r59]
1212
- law: "`next-intl` with `[locale]`; the next-intl stack is written once per front end: `fe/packages/<family>-i18n` (`createAppI18n`) called by each app's `modules/i18n/index.ts`, or the only app's `modules/i18n/`."
1213
+ law: "`next-intl` with `[locale]`; multiple apps share one `fe/packages/<family>-i18n` stack through `createAppI18n`. A single app keeps routing and request configuration in `modules/i18n` and `createNavigation` in the `modules/routes` public entry. The proxy imports routing or a routing-only shared proxy export without evaluating navigation runtime."
1213
1214
  kinds: [check, codemod, lint]
1214
1215
  gates: [settle, land, ci]
1215
1216
  failureCodes: ["FE_I18N_PLACEMENT", "FE_I18N_NAVIGATION", "FE_I18N_FORMATTER"]
@@ -1252,9 +1253,10 @@ rules:
1252
1253
  - {path: packages/hfs/src/hfs-i18n-catalog-coverage.spec.mjs, editions: [lite, full]}
1253
1254
  - id: R61
1254
1255
  code: "FE_STYLE_TOKEN_ONLY"
1255
- law: "Token-only CSS; colour only in `brand.css`; every `@source` resolves (sub-check `FE_STYLE_SOURCE_UNRESOLVED`). Status colours follow HeroUI soft pairs: every status tone has `--<tone>-soft` and `--<tone>-soft-foreground` in light and dark, the soft foreground reaches 3:1 on its tint and on `--background`, body text 4.5:1, a solid tone is never text below 4.5:1, and text and icons take the soft foreground, never the solid tone."
1256
+ law: "Application CSS uses the selected Grammar tokens for layout and the declared brand owner for brand values; every source declaration resolves. Status foregrounds reach 3:1 against their tinted surface and page background in each theme, body text reaches 4.5:1, and an insufficiently contrasting solid tone is never text. The selected Grammar owns the concrete token pairs, typography, scale and visual values."
1257
+ docs: [knowledge/patterns/fe/index.yaml#FE-RULE-OWNERSHIP, packages/stylelint/README.md, packages/eslint/fe/docs/brand-values.md, docs/source-process.md#the-test-ladder, knowledge/hfs/rules.yaml#R225]
1256
1258
  kinds: [lint, design]
1257
- gates: [pre-commit, pre-push, settle, land, ci]
1259
+ gates: [pre-commit, settle, land, ci]
1258
1260
  failureCodes: ["FE_STYLE_TOKEN_ONLY", "FE_STYLE_SOURCE_UNRESOLVED"]
1259
1261
  enforcers:
1260
1262
  - {kind: stylelint, id: token-only}
@@ -1271,33 +1273,59 @@ rules:
1271
1273
  - {kind: stylelint, id: breakpoint-scale}
1272
1274
  - {kind: stylelint, id: source-resolves}
1273
1275
  - {kind: eslint-fe, id: no-raw-brand-value}
1274
- - {kind: eslint-fe, id: no-fractional-step}
1276
+ - {kind: eslint-grammar-starci, id: no-fractional-step}
1275
1277
  - {kind: eslint-fe, id: no-arbitrary-value}
1276
- - {kind: eslint-fe, id: no-hand-rolled-heading}
1277
- - {kind: eslint-fe, id: no-unresolved-token-class}
1278
- - {kind: eslint-fe, id: no-heading-tag-outside-heading-component}
1279
- - {kind: eslint-fe, id: status-text-uses-soft-foreground}
1278
+ - {kind: eslint-grammar-starci, id: no-hand-rolled-heading}
1279
+ - {kind: eslint-grammar-starci, id: no-unresolved-token-class}
1280
+ - {kind: eslint-grammar-starci, id: no-heading-tag-outside-heading-component}
1281
+ - {kind: eslint-grammar-starci, id: status-text-uses-soft-foreground}
1282
+ proves:
1283
+ - {path: packages/stylelint/source-resolves.spec.mjs, editions: [lite, full], codes: [FE_STYLE_SOURCE_UNRESOLVED]}
1284
+ - {path: packages/eslint/fe/brand-values.spec.mjs, editions: [lite, full], codes: [FE_STYLE_TOKEN_ONLY]}
1285
+ - {path: packages/eslint/fe/tokens.spec.mjs, editions: [lite, full], codes: [FE_STYLE_TOKEN_ONLY]}
1286
+ - {path: packages/eslint/grammar-starci/status-colors.spec.mjs, editions: [lite, full], codes: [FE_STYLE_TOKEN_ONLY]}
1287
+ - {path: packages/eslint/grammar-starci/typography.spec.mjs, editions: [lite, full], codes: [FE_STYLE_TOKEN_ONLY]}
1288
+ - {path: packages/eslint/grammar-starci/tokens.spec.mjs, editions: [lite, full], codes: [FE_STYLE_TOKEN_ONLY]}
1289
+ exemplifiedBy:
1290
+ - {path: packages/hfs/templates/fe/skeleton-lite/apps/web/src/app/globals.css, edition: lite}
1291
+ - {path: packages/hfs/templates/fe/skeleton/apps/app/src/app/globals.css, edition: full}
1292
+ - {path: packages/stylelint/source-resolves.spec.mjs, editions: [lite, full], codes: [FE_STYLE_SOURCE_UNRESOLVED]}
1293
+ - {path: packages/eslint/fe/brand-values.spec.mjs, editions: [lite, full], codes: [FE_STYLE_TOKEN_ONLY]}
1294
+ - {path: packages/eslint/fe/tokens.spec.mjs, editions: [lite, full], codes: [FE_STYLE_TOKEN_ONLY]}
1295
+ - {path: packages/eslint/grammar-starci/status-colors.spec.mjs, editions: [lite, full], codes: [FE_STYLE_TOKEN_ONLY]}
1296
+ - {path: packages/eslint/grammar-starci/typography.spec.mjs, editions: [lite, full], codes: [FE_STYLE_TOKEN_ONLY]}
1297
+ - {path: packages/eslint/grammar-starci/tokens.spec.mjs, editions: [lite, full], codes: [FE_STYLE_TOKEN_ONLY]}
1298
+ witness:
1299
+ - {path: packages/stylelint/source-resolves.spec.mjs, editions: [lite, full], codes: [FE_STYLE_SOURCE_UNRESOLVED]}
1300
+ - {path: packages/eslint/fe/brand-values.spec.mjs, editions: [lite, full], codes: [FE_STYLE_TOKEN_ONLY]}
1301
+ - {path: packages/eslint/fe/tokens.spec.mjs, editions: [lite, full], codes: [FE_STYLE_TOKEN_ONLY]}
1302
+ - {path: packages/eslint/grammar-starci/status-colors.spec.mjs, editions: [lite, full], codes: [FE_STYLE_TOKEN_ONLY]}
1303
+ - {path: packages/eslint/grammar-starci/typography.spec.mjs, editions: [lite, full], codes: [FE_STYLE_TOKEN_ONLY]}
1304
+ - {path: packages/eslint/grammar-starci/tokens.spec.mjs, editions: [lite, full], codes: [FE_STYLE_TOKEN_ONLY]}
1280
1305
  - id: R62
1281
1306
  code: "FE_NATIVE_FORM_CONTROL"
1282
1307
  editions: [lite, full]
1283
- docs: [docs/architecture.md#r62]
1308
+ docs: [docs/architecture.md#r62, knowledge/patterns/fe/index.yaml#FE-RULE-OWNERSHIP]
1284
1309
  proves:
1310
+ - {path: packages/eslint/grammar-starci/r62-structural-elements-coverage.spec.mjs, editions: [lite, full], codes: [FE_NATIVE_FORM_CONTROL]}
1285
1311
  - {path: packages/eslint/fe/r62-native-controls-coverage.spec.mjs, editions: [lite, full]}
1286
1312
  exemplifiedBy:
1313
+ - {path: packages/eslint/grammar-starci/r62-structural-elements-coverage.spec.mjs, editions: [lite, full], codes: [FE_NATIVE_FORM_CONTROL]}
1287
1314
  - {path: packages/hfs/templates/fe/skeleton-lite/apps/web/src/features/pages/AppHomePage/component.tsx, edition: lite}
1288
1315
  - {path: packages/hfs/templates/fe/skeleton/apps/__app__/src/components/blocks/SignInForm/component.tsx, edition: full}
1289
1316
  - {path: packages/eslint/fe/r62-native-controls-coverage.spec.mjs, editions: [lite, full]}
1290
1317
  witness:
1318
+ - {path: packages/eslint/grammar-starci/r62-structural-elements-coverage.spec.mjs, editions: [lite, full], codes: [FE_NATIVE_FORM_CONTROL]}
1291
1319
  - {path: packages/eslint/fe/r62-native-controls-coverage.spec.mjs, edition: lite, codes: [FE_NATIVE_FORM_CONTROL, FE_NATIVE_IMAGE]}
1292
1320
  - {path: packages/eslint/fe/r62-native-controls-coverage.spec.mjs, edition: full, codes: [FE_NATIVE_FORM_CONTROL, FE_NATIVE_IMAGE]}
1293
- law: "No raw form controls, native images or raw structural tags in product tiers; the grammar renders them."
1321
+ law: "Product tiers compose the selected Grammar renderers for form controls, images and structural elements that the Grammar owns; they never reproduce those renderers with raw HTML."
1294
1322
  kinds: [lint, design]
1295
1323
  gates: ["pre-commit", "settle", "land", "ci"]
1296
1324
  failureCodes: ["FE_NATIVE_FORM_CONTROL", "FE_NATIVE_IMAGE"]
1297
1325
  enforcers:
1298
1326
  - {kind: eslint-fe, id: no-native-form-control}
1299
1327
  - {kind: eslint-fe, id: no-native-img}
1300
- - {kind: eslint-fe, id: no-raw-structural-element}
1328
+ - {kind: eslint-grammar-starci, id: no-raw-structural-element}
1301
1329
  - {kind: eslint-fe, id: image-has-size}
1302
1330
 
1303
1331
  - id: R63
@@ -1836,7 +1864,7 @@ rules:
1836
1864
  gates: ["pre-commit","settle","land","ci"]
1837
1865
  - id: R92
1838
1866
  code: "FE_COMPONENT_API"
1839
- law: "A component exposes the canon surface: typed named props and slots, an exact sibling XBase presentational twin for every connected block, status through the slot view, no className or CSS doors, no resting twin or placeholder prop, class names in the colocated file; a pure component reaches no hook, router, locale or API, but may render a list of blocks supplied through render props without importing blocks or owning their data."
1867
+ law: "A component exposes the canon surface: typed named props and slots, an exact sibling XBase presentational twin for every connected block, status through the selected Grammar state renderer, no className or CSS doors, no resting twin or placeholder prop, class names in the colocated file; a pure component reaches no hook, router, locale or API, but may render a list of blocks supplied through render props without importing blocks or owning their data."
1840
1868
  kinds: [lint, design]
1841
1869
  gates: [pre-commit, settle, land, ci]
1842
1870
  failureCodes: ["FE_COMPONENT_API", "FE_COMPONENT_WORLD_OWNERSHIP", "FE_WORLD_OWNER_RENDER_BOUNDARY", "FE_CONNECTED_BLOCK_RENDER_PAIR", "FE_PURE_REACHES_DATA", "FE_PURE_WORLD_HOOK", "FE_PURE_WORLD_IMPORT"]
@@ -1850,7 +1878,7 @@ rules:
1850
1878
  - {kind: eslint-fe, id: base-props-atom}
1851
1879
  - {kind: eslint-fe, id: base-import-pair}
1852
1880
  - {kind: eslint-fe, id: no-data-status-shape}
1853
- - {kind: eslint-fe, id: slot-status-through-slotview}
1881
+ - {kind: eslint-grammar-starci, id: slot-status-through-slotview}
1854
1882
  - {kind: eslint-fe, id: presentational-purity}
1855
1883
  - {kind: eslint-fe, id: connected-block-has-presentational-twin}
1856
1884
  - {kind: eslint-fe, id: no-resting-twin-component}
@@ -1861,62 +1889,54 @@ rules:
1861
1889
  - {kind: eslint-fe, id: cn-arguments-are-single-tokens}
1862
1890
  - {kind: eslint-fe, id: component-purity}
1863
1891
  editions: [lite, full]
1864
- docs: [docs/architecture.md#r92]
1892
+ docs: [docs/architecture.md#r92, knowledge/patterns/fe/index.yaml#FE-RULE-OWNERSHIP]
1865
1893
  proves:
1894
+ - {path: packages/eslint/grammar-starci/r92-slot-status-coverage.spec.mjs, editions: [lite, full], codes: [FE_COMPONENT_API]}
1866
1895
  - {path: packages/eslint/fe/r92-fetch-barrel.spec.mjs, editions: [lite, full]}
1867
1896
  - {path: packages/eslint/fe/r92-component-surface-coverage.spec.mjs, editions: [lite, full]}
1868
1897
  - {path: packages/eslint/fe/r56-r92-graph-coverage.spec.mjs, editions: [lite, full]}
1869
1898
  exemplifiedBy:
1899
+ - {path: packages/eslint/grammar-starci/r92-slot-status-coverage.spec.mjs, editions: [lite, full], codes: [FE_COMPONENT_API]}
1870
1900
  - {path: packages/hfs/templates/fe/skeleton/apps/__app__/src/components/blocks/SignInForm/component.tsx, editions: [lite, full]}
1871
1901
  - {path: packages/eslint/fe/r92-fetch-barrel.spec.mjs, editions: [lite, full]}
1872
1902
  - {path: packages/eslint/fe/r92-component-surface-coverage.spec.mjs, editions: [lite, full]}
1873
1903
  - {path: packages/eslint/fe/r56-r92-graph-coverage.spec.mjs, editions: [lite, full]}
1874
1904
  witness:
1905
+ - {path: packages/eslint/grammar-starci/r92-slot-status-coverage.spec.mjs, editions: [lite, full], codes: [FE_COMPONENT_API]}
1875
1906
  - {path: packages/eslint/fe/r92-fetch-barrel.spec.mjs, editions: [lite, full]}
1876
1907
  - {path: packages/eslint/fe/r92-component-surface-coverage.spec.mjs, editions: [lite, full]}
1877
1908
  - {path: packages/eslint/fe/r56-r92-graph-coverage.spec.mjs, editions: [lite, full]}
1878
1909
  - id: R93
1879
1910
  code: "FE_VENDOR_BOUNDARY"
1880
- law: "Vendor primitives and icons reach components only through their named owner: the one icon set of knowledge/hfs/fe-stack.yaml (the heroicons family) through the icon leaf at the glyph scale, every vendor primitive behind a named owner; the Grammar package is imported only through its selected code and style entry and keeps its declared contract. Apps compose Grammar surfaces with layout-only CSS; surface context supplies nested field variants and panel list alignment, without raw surface paint or stacked horizontal list-wrapper padding."
1911
+ law: "Vendor primitives and icons reach components only through their named owner: one declared icon set through its icon owner, one icon size per region chosen from the selected Grammar scale, and every vendor primitive behind a named owner. The Grammar package is imported through its selected public code and style entries and keeps its declared contract. The Grammar owns the visual values and component API that realize these requirements."
1881
1912
  kinds: [lint, codemod]
1882
1913
  gates: [pre-commit, settle, land, ci]
1883
- failureCodes: ["FE_VENDOR_BOUNDARY", "ARCH_GRAMMAR_CONTRACT_INVALID", "ARCH_GRAMMAR_EXPORT_BYPASS", "FE_NESTED_VARIANT", "FE_LIST_PANEL_PADDING"]
1884
- enforcers:
1885
- - {kind: eslint-fe, id: no-vendor-icon-outside-icon-leaf}
1886
- - {kind: eslint-fe, id: heroicons-is-the-glyph-vendor}
1887
- - {kind: eslint-fe, id: no-off-scale-glyph-size}
1888
- - {kind: eslint-fe, id: no-icon-size-class}
1889
- - {kind: eslint-fe, id: destructive-menu-entry-needs-danger-tone}
1890
- - {kind: eslint-fe, id: no-decorative-icon-in-metric-cell}
1891
- - {kind: eslint-fe, id: vendor-primitive-has-named-owner}
1914
+ failureCodes: ["FE_VENDOR_BOUNDARY", "ARCH_GRAMMAR_CONTRACT_INVALID", "ARCH_GRAMMAR_EXPORT_BYPASS"]
1915
+ enforcers:
1916
+ - {kind: eslint-grammar-starci, id: no-vendor-icon-outside-icon-leaf}
1917
+ - {kind: eslint-grammar-starci, id: heroicons-is-the-glyph-vendor}
1918
+ - {kind: eslint-grammar-starci, id: no-off-scale-glyph-size}
1919
+ - {kind: eslint-grammar-starci, id: no-icon-size-class}
1920
+ - {kind: eslint-grammar-starci, id: destructive-menu-entry-needs-danger-tone}
1921
+ - {kind: eslint-grammar-starci, id: no-decorative-icon-in-metric-cell}
1922
+ - {kind: eslint-grammar-starci, id: vendor-primitive-has-named-owner}
1892
1923
  - {kind: eslint-fe, id: grammar-entry}
1893
- - {kind: eslint-fe, id: nested-control-variant}
1894
- - {kind: eslint-fe, id: no-list-panel-padding}
1895
1924
  - {kind: machine, id: grammar, at: scripts/hfs/architecture/frontend-grammar.mjs}
1896
1925
  editions: [lite, full]
1897
- docs: ["docs/code-pattern-enforcement.md#r93-vendor-and-grammar-ownership"]
1926
+ docs: ["docs/code-pattern-enforcement.md#r93-vendor-and-grammar-ownership", knowledge/patterns/fe/index.yaml#FE-RULE-OWNERSHIP]
1898
1927
  templateNa: "Vendor boundary violations and installed Grammar package contracts are checked against consumer ownership; no managed template scaffolds a vendor install or a forbidden import."
1899
1928
  proves:
1900
- - packages/eslint/fe/r93-vendor-coverage.spec.mjs
1929
+ - packages/eslint/grammar-starci/r93-vendor-coverage.spec.mjs
1901
1930
  - packages/eslint/fe/r93-grammar-ownership.spec.mjs
1902
- - packages/eslint/fe/menu-entries.spec.mjs
1903
- - packages/eslint/fe/surface-rules.spec.mjs
1931
+ - packages/eslint/grammar-starci/menu-entries.spec.mjs
1904
1932
  exemplifiedBy:
1905
- - {path: packages/eslint/fe/r93-vendor-coverage.spec.mjs, editions: [lite, full]}
1933
+ - {path: packages/eslint/grammar-starci/r93-vendor-coverage.spec.mjs, editions: [lite, full]}
1906
1934
  - {path: packages/eslint/fe/r93-grammar-ownership.spec.mjs, editions: [lite, full]}
1907
- - {path: packages/eslint/fe/menu-entries.spec.mjs, editions: [lite, full]}
1908
- - {path: packages/eslint/fe/surface-rules.spec.mjs, editions: [lite, full]}
1935
+ - {path: packages/eslint/grammar-starci/menu-entries.spec.mjs, editions: [lite, full]}
1909
1936
  witness:
1910
- - {path: packages/eslint/fe/menu-entries.spec.mjs, editions: [lite, full], codes: [FE_VENDOR_BOUNDARY]}
1911
- - {path: packages/eslint/fe/r93-vendor-coverage.spec.mjs, editions: [lite, full], codes: [FE_VENDOR_BOUNDARY]}
1937
+ - {path: packages/eslint/grammar-starci/menu-entries.spec.mjs, editions: [lite, full], codes: [FE_VENDOR_BOUNDARY]}
1938
+ - {path: packages/eslint/grammar-starci/r93-vendor-coverage.spec.mjs, editions: [lite, full], codes: [FE_VENDOR_BOUNDARY]}
1912
1939
  - {path: packages/eslint/fe/r93-grammar-ownership.spec.mjs, editions: [lite, full], codes: [ARCH_GRAMMAR_CONTRACT_INVALID, ARCH_GRAMMAR_EXPORT_BYPASS]}
1913
- - {path: packages/eslint/fe/surface-rules.spec.mjs, editions: [lite, full], codes: [FE_NESTED_VARIANT, FE_LIST_PANEL_PADDING]}
1914
- cases:
1915
- - id: case-1
1916
- date: "2026-10-25"
1917
- source: owner
1918
- quote: "apps on Grammar write layout-only CSS; every visual element lives in @starci/grammar"
1919
- ruling: "ANATOMY-2 owns contextual field defaults, PADDING-0 owns panel list alignment, and COLLECTION-3 owns composite member avatars for conversation and group identity. Grammar supplies these capabilities; the FE canon rejects explicit primary fields inside surfaces, raw app surface paint and stacked horizontal list-wrapper padding."
1920
1940
  - id: R94
1921
1941
  code: "FE_SLOT_FILE_ROLE"
1922
1942
  law: "A front-end file is owned by a slot and named by it: a slot that owns a directory (route, feature, components, hooks, api module) holds only the files its `allows` list names, and holds them inside a folder of its own."
@@ -4978,27 +4998,27 @@ rules:
4978
4998
 
4979
4999
  - id: R286
4980
5000
  code: "FE_COPY_IN_CALL"
4981
- law: "Copy shown by validation and toast calls comes from the next-intl catalog, including Zod message arguments and toast titles or descriptions. Browser alert calls are forbidden. Inline SVG glyphs are forbidden outside a declared brand-mark leaf; ordinary icons use the one Heroicons family through the Icon leaf."
5001
+ law: "Validation and toast copy comes from the translation catalog, including validation messages, titles and descriptions. Browser alert calls are forbidden. Inline vector glyphs belong only to declared brand-mark owners; ordinary icons use the selected Grammar icon owner and its declared glyph family."
4982
5002
  kinds: [lint]
4983
5003
  gates: [pre-commit, settle, land, ci]
4984
5004
  failureCodes: ["FE_COPY_IN_CALL", "FE_NO_ALERT", "FE_ICON_INLINE_SVG"]
4985
5005
  enforcers:
4986
5006
  - {kind: eslint-fe, id: no-copy-in-call}
4987
5007
  - {kind: eslint-fe, id: no-alert}
4988
- - {kind: eslint-fe, id: no-inline-svg-outside-brand-mark-leaf}
5008
+ - {kind: eslint-grammar-starci, id: no-inline-svg-outside-brand-mark-leaf}
4989
5009
  editions: [lite, full]
4990
- docs: [docs/quality-bar.md#r286]
5010
+ docs: [docs/quality-bar.md#r286, knowledge/patterns/fe/index.yaml#FE-RULE-OWNERSHIP]
4991
5011
  exemplifiedBy:
4992
5012
  - {path: packages/eslint/fe/translation.spec.mjs, editions: [lite, full], codes: [FE_COPY_IN_CALL, FE_NO_ALERT]}
4993
- - {path: packages/eslint/fe/icon.spec.mjs, editions: [lite, full], codes: [FE_ICON_INLINE_SVG]}
5013
+ - {path: packages/eslint/grammar-starci/icon.spec.mjs, editions: [lite, full], codes: [FE_ICON_INLINE_SVG]}
4994
5014
  - {path: packages/hfs/templates/fe/skeleton/apps/__app__/src/components/leaves/Icon/index.tsx, editions: [lite, full]}
4995
5015
  - {path: packages/hfs/templates/fe/skeleton/apps/__app__/src/modules/toast, editions: [lite, full]}
4996
5016
  proves:
4997
5017
  - {path: packages/eslint/fe/translation.spec.mjs, editions: [lite, full], codes: [FE_COPY_IN_CALL, FE_NO_ALERT]}
4998
- - {path: packages/eslint/fe/icon.spec.mjs, editions: [lite, full], codes: [FE_ICON_INLINE_SVG]}
5018
+ - {path: packages/eslint/grammar-starci/icon.spec.mjs, editions: [lite, full], codes: [FE_ICON_INLINE_SVG]}
4999
5019
  witness:
5000
5020
  - {path: packages/eslint/fe/translation.spec.mjs, editions: [lite, full], codes: [FE_COPY_IN_CALL, FE_NO_ALERT]}
5001
- - {path: packages/eslint/fe/icon.spec.mjs, editions: [lite, full], codes: [FE_ICON_INLINE_SVG]}
5021
+ - {path: packages/eslint/grammar-starci/icon.spec.mjs, editions: [lite, full], codes: [FE_ICON_INLINE_SVG]}
5002
5022
 
5003
5023
  - id: R287
5004
5024
  code: "FE_CALLBACK_SHAPE"
@@ -5021,21 +5041,21 @@ rules:
5021
5041
 
5022
5042
  - id: R288
5023
5043
  code: "FE_STACK_UNLISTED"
5024
- law: "Every direct FE workspace dependency belongs to knowledge/hfs/fe-stack.yaml or is declared in hfs.json fe.extraPackages with its name and a nonempty reason. Installed runtime dependencies carried by a listed Grammar package are not app declarations and raise no FE_STACK_UNLISTED; direct forbidden dependencies still raise FE_STACK_FORBIDDEN. Every product Next app declares the catalog's core runtime packages; codegen, lint, TypeScript and Tailwind tools may be installed once at the app root. The marketing landing app is exempt (lite and full) from core presence. GraphQL documents, including gql templates, match the back-end contracts, and SWR keys carry fetcher identities without an opt-in declaration."
5044
+ law: "Every direct FE workspace dependency belongs to knowledge/hfs/fe-stack.yaml or is declared in hfs.json fe.extraPackages with its name and a nonempty reason. Installed runtime dependencies carried by a listed Grammar package are not app declarations and raise no FE_STACK_UNLISTED; direct forbidden dependencies still raise FE_STACK_FORBIDDEN. Every product Next app declares the catalog's core runtime packages; codegen, lint, TypeScript and Tailwind tools may be installed once at the app root. The marketing landing app is exempt (lite and full) from core presence. A front end that selects sides.fe.grammar and declares @starci/eslint-canon-fe 9 or later also declares that family's lint package from knowledge/grammars/index.yaml, which carries its Grammar component rules (FE_STACK_FAMILY_LINT_MISSING). GraphQL documents, including gql templates, match the back-end contracts, and SWR keys carry fetcher identities without an opt-in declaration."
5025
5045
  kinds: [check]
5026
5046
  gates: [settle, land, ci]
5027
- failureCodes: ["FE_STACK_UNLISTED", "FE_STACK_CORE_MISSING"]
5047
+ failureCodes: ["FE_STACK_UNLISTED", "FE_STACK_CORE_MISSING", "FE_STACK_FAMILY_LINT_MISSING"]
5028
5048
  enforcers:
5029
5049
  - {kind: hfs, id: fe-stack-allowlist, at: scripts/hfs/rules/fe-stack.mjs}
5030
5050
  editions: [lite, full]
5031
5051
  docs: [docs/quality-bar.md#r288]
5032
5052
  proves:
5033
- - {path: packages/hfs/src/hfs-fe-stack.spec.mjs, editions: [lite, full], codes: [FE_STACK_UNLISTED, FE_STACK_CORE_MISSING]}
5053
+ - {path: packages/hfs/src/hfs-fe-stack.spec.mjs, editions: [lite, full], codes: [FE_STACK_UNLISTED, FE_STACK_CORE_MISSING, FE_STACK_FAMILY_LINT_MISSING]}
5034
5054
  exemplifiedBy:
5035
5055
  - {path: packages/hfs/templates/fe/app/package.json.tpl, editions: [lite, full]}
5036
- - {path: packages/hfs/src/hfs-fe-stack.spec.mjs, editions: [lite, full], codes: [FE_STACK_UNLISTED, FE_STACK_CORE_MISSING]}
5056
+ - {path: packages/hfs/src/hfs-fe-stack.spec.mjs, editions: [lite, full], codes: [FE_STACK_UNLISTED, FE_STACK_CORE_MISSING, FE_STACK_FAMILY_LINT_MISSING]}
5037
5057
  witness:
5038
- - {path: packages/hfs/src/hfs-fe-stack.spec.mjs, editions: [lite, full], codes: [FE_STACK_UNLISTED, FE_STACK_CORE_MISSING]}
5058
+ - {path: packages/hfs/src/hfs-fe-stack.spec.mjs, editions: [lite, full], codes: [FE_STACK_UNLISTED, FE_STACK_CORE_MISSING, FE_STACK_FAMILY_LINT_MISSING]}
5039
5059
  - id: R289
5040
5060
  code: "BE_APP_ENV_REQUIRED"
5041
5061
  law: "Every declared back-end app owns a tracked apps/<app>/src/<app>.env.ts exporting its typed environment interface and read<App>Env(env: EnvSource). main.ts constructs EnvSource once and delegates its reads to that reader, with no inline parsing. app.module.ts composes module lists only by spreading compose/<area>.ts groups; its own providers are limited to app-wide guards and filters."
@@ -5450,101 +5470,131 @@ rules:
5450
5470
  templateNa: "A storage grant is declared per integration; the canon scaffolds none, and the presigned-upload examples of both editions are the reference."
5451
5471
  - id: R313
5452
5472
  code: "FE_APP_SHELL_FRAME"
5453
- law: "FE-APP-SHELL-1 requires WorkspaceShell viewport=fixed to own the application frame, including persistent header and navigation; hand-built header/nav frames are refused."
5473
+ law: "FE-APP-SHELL-1 gives the selected Grammar shell ownership of the fixed application frame, navbar, subnav and sidebar, with independent navigation and content scroll; StarCi requires WorkspaceShell viewport=fixed with navigation resolving visibility to wide and navigationDrawer or a compactHeader containing a left Drawer with Sidebar presentation=drawer; application layout does not recreate this frame."
5454
5474
  kinds: [lint, design]
5455
5475
  gates: [pre-commit, settle, land, ci]
5456
5476
  failureCodes: ["FE_APP_SHELL_FRAME"]
5457
5477
  enforcers:
5458
- - {kind: eslint-fe, id: app-shell-frame}
5478
+ - {kind: eslint-grammar-starci, id: app-shell-frame}
5459
5479
  editions: [lite, full]
5460
5480
  docs:
5481
+ - knowledge/patterns/fe/index.yaml#FE-RULE-OWNERSHIP
5461
5482
  - {path: knowledge/ui/composition/app-shell.yaml, editions: [lite, full]}
5462
5483
  proves:
5463
- - {path: packages/eslint/fe/app-shell.spec.mjs, editions: [lite, full], codes: [FE_APP_SHELL_FRAME]}
5484
+ - {path: packages/eslint/grammar-starci/app-shell.spec.mjs, editions: [lite, full], codes: [FE_APP_SHELL_FRAME]}
5464
5485
  exemplifiedBy:
5465
- - {path: packages/eslint/fe/app-shell.spec.mjs, editions: [lite, full], codes: [FE_APP_SHELL_FRAME]}
5486
+ - {path: packages/eslint/grammar-starci/app-shell.spec.mjs, editions: [lite, full], codes: [FE_APP_SHELL_FRAME]}
5466
5487
  - {path: examples/full-app/fe/apps/app/src/features/layouts/ShopLayout/component.tsx, edition: full}
5467
5488
  - {path: examples/lite-app/fe/apps/web/src/features/layouts/WorkspaceLayout/component.tsx, edition: lite}
5468
5489
  witness:
5469
- - {path: packages/eslint/fe/app-shell.spec.mjs, editions: [lite, full], codes: [FE_APP_SHELL_FRAME]}
5490
+ - {path: packages/eslint/grammar-starci/app-shell.spec.mjs, editions: [lite, full], codes: [FE_APP_SHELL_FRAME]}
5470
5491
  templateNa: "The app composes its shell from product destinations and identity; full and lite example shells provide the reference."
5471
5492
  - id: R314
5472
5493
  code: "FE_NAVBAR_CONTROL_SIZE"
5473
- law: "FE-APP-SHELL-2 requires every navbar control to declare size=control so Grammar owns the common control height."
5494
+ law: "FE-APP-SHELL-2 keeps navbar controls at one common height and icons at one size per region from the selected Grammar scale; the Grammar owns their concrete values."
5474
5495
  kinds: [lint, design]
5475
5496
  gates: [pre-commit, settle, land, ci]
5476
5497
  failureCodes: ["FE_NAVBAR_CONTROL_SIZE"]
5477
5498
  enforcers:
5478
- - {kind: eslint-fe, id: navbar-control-size}
5499
+ - {kind: eslint-grammar-starci, id: navbar-control-size}
5479
5500
  editions: [lite, full]
5480
5501
  docs:
5502
+ - knowledge/patterns/fe/index.yaml#FE-RULE-OWNERSHIP
5481
5503
  - {path: knowledge/ui/composition/app-shell.yaml, editions: [lite, full]}
5482
5504
  proves:
5483
- - {path: packages/eslint/fe/app-shell.spec.mjs, editions: [lite, full], codes: [FE_NAVBAR_CONTROL_SIZE]}
5505
+ - {path: packages/eslint/grammar-starci/app-shell.spec.mjs, editions: [lite, full], codes: [FE_NAVBAR_CONTROL_SIZE]}
5484
5506
  exemplifiedBy:
5485
- - {path: packages/eslint/fe/app-shell.spec.mjs, editions: [lite, full], codes: [FE_NAVBAR_CONTROL_SIZE]}
5507
+ - {path: packages/eslint/grammar-starci/app-shell.spec.mjs, editions: [lite, full], codes: [FE_NAVBAR_CONTROL_SIZE]}
5486
5508
  - {path: examples/full-app/fe/packages/ecommerce-ui/src/branches/WorkspaceNavbar/component.tsx, edition: full}
5487
5509
  - {path: examples/lite-app/fe/apps/web/src/components/branches/Navbar/component.tsx, edition: lite}
5488
5510
  witness:
5489
- - {path: packages/eslint/fe/app-shell.spec.mjs, editions: [lite, full], codes: [FE_NAVBAR_CONTROL_SIZE]}
5511
+ - {path: packages/eslint/grammar-starci/app-shell.spec.mjs, editions: [lite, full], codes: [FE_NAVBAR_CONTROL_SIZE]}
5490
5512
  templateNa: "The app composes its shell from product destinations and identity; full and lite example shells provide the reference."
5491
5513
  - id: R315
5492
5514
  code: "FE_NAVBAR_CLUSTER"
5493
- law: "FE-APP-SHELL-3 requires the statically composed navbar right cluster to contain a tertiary language IconButton opening DropdownMenu, a theme Switch, a notification IconButton opening Popover and an account AvatarButton opening DropdownMenu, in that order."
5515
+ law: "FE-APP-SHELL-3 orders the navbar controls as language, theme, notifications and account, with each control and its overlay supplied by the selected Grammar."
5494
5516
  kinds: [lint, design]
5495
5517
  gates: [pre-commit, settle, land, ci]
5496
5518
  failureCodes: ["FE_NAVBAR_CLUSTER"]
5497
5519
  enforcers:
5498
- - {kind: eslint-fe, id: navbar-cluster}
5520
+ - {kind: eslint-grammar-starci, id: navbar-cluster}
5499
5521
  editions: [lite, full]
5500
5522
  docs:
5523
+ - knowledge/patterns/fe/index.yaml#FE-RULE-OWNERSHIP
5501
5524
  - {path: knowledge/ui/composition/app-shell.yaml, editions: [lite, full]}
5502
5525
  proves:
5503
- - {path: packages/eslint/fe/app-shell.spec.mjs, editions: [lite, full], codes: [FE_NAVBAR_CLUSTER]}
5526
+ - {path: packages/eslint/grammar-starci/app-shell.spec.mjs, editions: [lite, full], codes: [FE_NAVBAR_CLUSTER]}
5504
5527
  exemplifiedBy:
5505
- - {path: packages/eslint/fe/app-shell.spec.mjs, editions: [lite, full], codes: [FE_NAVBAR_CLUSTER]}
5528
+ - {path: packages/eslint/grammar-starci/app-shell.spec.mjs, editions: [lite, full], codes: [FE_NAVBAR_CLUSTER]}
5506
5529
  - {path: examples/full-app/fe/packages/ecommerce-ui/src/branches/WorkspaceNavbar/component.tsx, edition: full}
5507
5530
  - {path: examples/lite-app/fe/apps/web/src/components/branches/Navbar/component.tsx, edition: lite}
5508
5531
  witness:
5509
- - {path: packages/eslint/fe/app-shell.spec.mjs, editions: [lite, full], codes: [FE_NAVBAR_CLUSTER]}
5532
+ - {path: packages/eslint/grammar-starci/app-shell.spec.mjs, editions: [lite, full], codes: [FE_NAVBAR_CLUSTER]}
5510
5533
  templateNa: "The app composes its shell from product destinations and identity; full and lite example shells provide the reference."
5511
5534
  - id: R316
5512
5535
  code: "FE_APP_SHELL_BOTTOM_TABS"
5513
- law: "FE-APP-SHELL-4 keeps navigation in the Sidebar drawer and refuses a bottom tab bar in the application shell."
5536
+ law: "FE-APP-SHELL-4 preserves the selected Grammar shell navigation model across viewports; an application does not replace its sidebar-derived mobile drawer with an incompatible bottom tab bar."
5514
5537
  kinds: [lint, design]
5515
5538
  gates: [pre-commit, settle, land, ci]
5516
5539
  failureCodes: ["FE_APP_SHELL_BOTTOM_TABS"]
5517
5540
  enforcers:
5518
- - {kind: eslint-fe, id: no-shell-bottom-tabs}
5541
+ - {kind: eslint-grammar-starci, id: no-shell-bottom-tabs}
5519
5542
  editions: [lite, full]
5520
5543
  docs:
5544
+ - knowledge/patterns/fe/index.yaml#FE-RULE-OWNERSHIP
5521
5545
  - {path: knowledge/ui/composition/app-shell.yaml, editions: [lite, full]}
5522
5546
  proves:
5523
- - {path: packages/eslint/fe/app-shell.spec.mjs, editions: [lite, full], codes: [FE_APP_SHELL_BOTTOM_TABS]}
5547
+ - {path: packages/eslint/grammar-starci/app-shell.spec.mjs, editions: [lite, full], codes: [FE_APP_SHELL_BOTTOM_TABS]}
5524
5548
  exemplifiedBy:
5525
- - {path: packages/eslint/fe/app-shell.spec.mjs, editions: [lite, full], codes: [FE_APP_SHELL_BOTTOM_TABS]}
5549
+ - {path: packages/eslint/grammar-starci/app-shell.spec.mjs, editions: [lite, full], codes: [FE_APP_SHELL_BOTTOM_TABS]}
5526
5550
  - {path: examples/full-app/fe/apps/app/src/features/layouts/ShopLayout/component.tsx, edition: full}
5527
5551
  - {path: examples/lite-app/fe/apps/web/src/features/layouts/WorkspaceLayout/component.tsx, edition: lite}
5528
5552
  witness:
5529
- - {path: packages/eslint/fe/app-shell.spec.mjs, editions: [lite, full], codes: [FE_APP_SHELL_BOTTOM_TABS]}
5553
+ - {path: packages/eslint/grammar-starci/app-shell.spec.mjs, editions: [lite, full], codes: [FE_APP_SHELL_BOTTOM_TABS]}
5530
5554
  templateNa: "The app composes its shell from product destinations and identity; full and lite example shells provide the reference."
5531
5555
  - id: R317
5532
5556
  code: "FE_NAVBAR_CREATE"
5533
- law: "FE-APP-SHELL-5 places create actions on their pages and refuses them in the navbar."
5557
+ law: "FE-APP-SHELL-5 places create actions on the page that owns them and keeps them out of the global navbar."
5534
5558
  kinds: [lint, design]
5535
5559
  gates: [pre-commit, settle, land, ci]
5536
5560
  failureCodes: ["FE_NAVBAR_CREATE"]
5537
5561
  enforcers:
5538
- - {kind: eslint-fe, id: no-navbar-create}
5562
+ - {kind: eslint-grammar-starci, id: no-navbar-create}
5539
5563
  editions: [lite, full]
5540
5564
  docs:
5565
+ - knowledge/patterns/fe/index.yaml#FE-RULE-OWNERSHIP
5541
5566
  - {path: knowledge/ui/composition/app-shell.yaml, editions: [lite, full]}
5542
5567
  proves:
5543
- - {path: packages/eslint/fe/app-shell.spec.mjs, editions: [lite, full], codes: [FE_NAVBAR_CREATE]}
5568
+ - {path: packages/eslint/grammar-starci/app-shell.spec.mjs, editions: [lite, full], codes: [FE_NAVBAR_CREATE]}
5544
5569
  exemplifiedBy:
5545
- - {path: packages/eslint/fe/app-shell.spec.mjs, editions: [lite, full], codes: [FE_NAVBAR_CREATE]}
5570
+ - {path: packages/eslint/grammar-starci/app-shell.spec.mjs, editions: [lite, full], codes: [FE_NAVBAR_CREATE]}
5546
5571
  - {path: examples/full-app/fe/packages/ecommerce-ui/src/branches/WorkspaceNavbar/component.tsx, edition: full}
5547
5572
  - {path: examples/lite-app/fe/apps/web/src/components/branches/Navbar/component.tsx, edition: lite}
5548
5573
  witness:
5549
- - {path: packages/eslint/fe/app-shell.spec.mjs, editions: [lite, full], codes: [FE_NAVBAR_CREATE]}
5574
+ - {path: packages/eslint/grammar-starci/app-shell.spec.mjs, editions: [lite, full], codes: [FE_NAVBAR_CREATE]}
5550
5575
  templateNa: "The app composes its shell from product destinations and identity; full and lite example shells provide the reference."
5576
+ - id: R318
5577
+ code: "FE_NESTED_VARIANT"
5578
+ law: "Apps compose Grammar with layout-only CSS; paint utilities, arbitrary paint properties and inline style paint belong to Grammar. Grammar context owns all layer-aware field variants, nested Tabs defaults and the content edge of panel lists; apps omit static field variants, do not force primary Tabs inside a painted surface, do not paint raw surfaces, and add no horizontal list-wrapper padding within the nearest painted Grammar surface."
5579
+ kinds: [lint, design]
5580
+ gates: [pre-commit, settle, land, ci]
5581
+ failureCodes: ["FE_NESTED_VARIANT", "FE_LIST_PANEL_PADDING", "FE_GRAMMAR_LAYOUT_ONLY"]
5582
+ enforcers:
5583
+ - {kind: eslint-fe, id: nested-control-variant}
5584
+ - {kind: eslint-fe, id: no-list-panel-padding}
5585
+ - {kind: eslint-fe, id: no-app-surface-paint}
5586
+ editions: [lite, full]
5587
+ docs: ["docs/code-pattern-enforcement.md#r318-app-grammar-composition"]
5588
+ templateNa: "Product composition is proved by the FE canon's Grammar import and surface fixtures; a template cannot choose product slots or lists."
5589
+ proves:
5590
+ - {path: packages/eslint/fe/surface-rules.spec.mjs, editions: [lite, full], codes: [FE_NESTED_VARIANT, FE_LIST_PANEL_PADDING, FE_GRAMMAR_LAYOUT_ONLY]}
5591
+ exemplifiedBy:
5592
+ - {path: packages/eslint/fe/surface-rules.spec.mjs, editions: [lite, full], codes: [FE_NESTED_VARIANT, FE_LIST_PANEL_PADDING, FE_GRAMMAR_LAYOUT_ONLY]}
5593
+ witness:
5594
+ - {path: packages/eslint/fe/surface-rules.spec.mjs, editions: [lite, full], codes: [FE_NESTED_VARIANT, FE_LIST_PANEL_PADDING, FE_GRAMMAR_LAYOUT_ONLY]}
5595
+ cases:
5596
+ - id: case-1
5597
+ date: "2026-10-25"
5598
+ source: owner
5599
+ quote: "apps on Grammar write layout-only CSS; every visual element lives in @starci/grammar"
5600
+ ruling: "ANATOMY-2 owns contextual field defaults, PADDING-0 owns panel list alignment, and COLLECTION-3 owns composite member avatars for conversation and group identity. Grammar supplies these capabilities; the FE canon rejects static field variants on either layer, primary Tabs inside painted surfaces, raw app surface paint and stacked horizontal list-wrapper padding inside painted surfaces."
@@ -2396,9 +2396,9 @@ slots:
2396
2396
  presence: required
2397
2397
  tracked: tracked
2398
2398
  tier: foundation
2399
- # The app's i18n module: its catalogs and the one call of the repository's i18n factory. The next-intl stack (routing,
2400
- # navigation, request config) is written once per repository: in the i18n package (fe.package.i18n, `createAppI18n`)
2401
- # when the repository has one, else in the only app's module.
2399
+ # The app's routing, request config and catalogs, or its adapter to the shared i18n factory. A single app
2400
+ # owns createNavigation in fe.modules.routes, keeping this public entry safe for its proxy. Shared stacks
2401
+ # belong to fe.package.i18n and expose a routing-only proxy entry separately from navigation.
2402
2402
  requires: [index.ts]
2403
2403
  tests: none
2404
2404
  rules: [FE_I18N_PLACEMENT, FE_I18N_CATALOG]
@@ -8,6 +8,22 @@
8
8
  # a word to scan for).
9
9
  kinds: [config-key, bias-field, verb, flag, code, vocabulary, file]
10
10
  removed:
11
+ - id: fe-landmark-branch-inventory
12
+ kind: vocabulary
13
+ name: LANDMARK_BRANCHES
14
+ use: 'the selected Grammar lint package owns its component vocabulary; the universal FE canon exposes no component inventory'
15
+ since: 1.0.0-alpha.31
16
+ - id: fe-grammar-rule-namespace
17
+ kind: vocabulary
18
+ name: starci-fe Grammar component rules
19
+ match: 'starci-fe/(?:app-shell-frame|no-shell-bottom-tabs|navbar-control-size|navbar-cluster|no-navbar-create|no-raw-structural-element|no-heading-tag-outside-heading-component|status-text-uses-soft-foreground|vendor-primitive-has-named-owner|no-vendor-icon-outside-icon-leaf|heroicons-is-the-glyph-vendor|no-off-scale-glyph-size|no-icon-size-class|destructive-menu-entry-needs-danger-tone|no-decorative-icon-in-metric-cell|no-inline-svg-outside-brand-mark-leaf|no-fractional-step|no-hand-rolled-heading|no-unresolved-token-class|slot-status-through-slotview)\b'
20
+ use: 'the same rule id under starci-grammar/ from the selected Grammar lint package; FE-RULE-OWNERSHIP governs placement'
21
+ since: 1.0.0-alpha.31
22
+ - id: offset-pop-toaster-content-guidance
23
+ kind: vocabulary
24
+ name: toaster-clear-of-the-dock
25
+ use: 'toaster-clear-of-content in the Offset Pop playbook'
26
+ since: 1.0.0-alpha.31
11
27
  - id: cut-seam-command
12
28
  kind: flag
13
29
  name: cut-seam --command
@@ -401,3 +417,16 @@ removed:
401
417
  use: 'the release tag is always <release.tagPrefix><package.json version>; delete the key'
402
418
  since: 1.0.0-alpha.31
403
419
  match: '\btagMatchesVersion\b'
420
+
421
+ - id: grammar-surfacecard-manual-layer
422
+ kind: vocabulary
423
+ name: SurfaceCard manual depth and unpainted frame
424
+ use: 'SurfaceCard derives its depth from the painted parent surface; use an unpainted layout container for grouping and a bounded SurfaceCard for a painted face'
425
+ since: 1.0.0-alpha.31
426
+ match: 'SurfaceCard[^\r\n>]*\s(?:depth=|frame="frameless")'
427
+ - id: grammar-dropdown-negative-tone
428
+ kind: vocabulary
429
+ name: DropdownMenuItem negative tone
430
+ use: 'DropdownMenuItem.tone uses neutral or danger; destructive commands use danger'
431
+ since: 1.0.0-alpha.31
432
+ match: 'DropdownMenuItem(?:Tone|\.tone)[^\r\n]*["'']negative["'']'
@@ -5,6 +5,7 @@ import { readJsonFile as readJson } from '../../lib/json.mjs';
5
5
  import { isInside } from '../../lib/walk.mjs';
6
6
  import { openHfs } from '../slots.mjs';
7
7
  import { byCodeUnit } from '../../lib/list.mjs';
8
+ import { grammarContractFor } from '../../lib/grammar-lint.mjs';
8
9
 
9
10
 
10
11
  /** A file's identity: its resolved real path, or the resolved path when it does not exist. */
@@ -270,19 +271,18 @@ function derivedOwners(root, resolver) {
270
271
 
271
272
  const DECLARED_HANDLER_DECORATORS = ['CommandHandler', 'QueryHandler'];
272
273
 
273
- const GRAMMAR_PACKAGE = '@starci/grammar';
274
-
275
274
  /**
276
- * The Grammar contract of a frontend repository, derived rather than declared: every app's globals.css is a style
277
- * source, every app and every workspace package that depends on the Grammar package is a consumer. null when no app has
275
+ * The selected family's component contract with derived consumers: every app's globals.css is a style
276
+ * source, every app and every workspace package that depends on its package is a consumer. null when no app has
278
277
  * a globals.css to judge (the contract is then reported unavailable, never passed).
279
278
  */
280
- function derivedGrammar(root, packageRoot, workspaces, apps = []) {
279
+ function derivedGrammar(root, packageRoot, workspaces, apps, family) {
281
280
  const styleSources = apps.map(app => `apps/${app.name}/src/app/globals.css`).filter(relative => existingRegularFile(root, relative));
282
281
  if (!styleSources.length) return null;
282
+ const contract = grammarContractFor(family);
283
283
  // Every fe app and package is an npm workspace that declares what it imports (HFS_MONO_WORKSPACE_DEP): each workspace that
284
284
  // declares the Grammar package is a consumer, and so is the app root's manifest when it does.
285
- const declaresGrammar = (pkg) => Boolean(pkg && [pkg.dependencies, pkg.peerDependencies, pkg.devDependencies].some(section => section && Object.hasOwn(section, GRAMMAR_PACKAGE)));
285
+ const declaresGrammar = (pkg) => Boolean(pkg && [pkg.dependencies, pkg.peerDependencies, pkg.devDependencies].some(section => section && Object.hasOwn(section, contract.package)));
286
286
  const appManifest = slash(path.relative(root, path.join(packageRoot, 'package.json')));
287
287
  const consumerManifests = declaresGrammar(readJson(path.join(packageRoot, 'package.json'))) ? [appManifest] : [];
288
288
  for (const workspace of workspaces) {
@@ -292,7 +292,7 @@ function derivedGrammar(root, packageRoot, workspaces, apps = []) {
292
292
  if (declaresGrammar(pkg)) consumerManifests.push(manifest);
293
293
  }
294
294
  if (!consumerManifests.length) return null;
295
- return { package: GRAMMAR_PACKAGE, entry: `${GRAMMAR_PACKAGE}/common`, styleEntry: `${GRAMMAR_PACKAGE}/common.css`, styleSources, consumerManifests, peers: ['react', '@heroui/react', '@xyflow/react'] };
295
+ return { ...contract, styleSources, consumerManifests };
296
296
  }
297
297
 
298
298
  /**
@@ -328,7 +328,7 @@ export function loadArchitectureConfig(repositoryRoot, { hfs } = {}) {
328
328
  hooks: inferred.hooks,
329
329
  modules: inferred.modules,
330
330
  transport: inferred.transport,
331
- grammar: profile === 'fe' ? derivedGrammar(root, packageRoot, workspaces, apps) : null,
331
+ grammar: profile === 'fe' ? derivedGrammar(root, packageRoot, workspaces, apps, opened.repo.grammar) : null,
332
332
  };
333
333
  if (profile === 'fe') assertFrontendRolesDisjoint(root, frontend);
334
334
  return {
@@ -73,11 +73,17 @@ function extraPackageProblems(side, entries) {
73
73
  return [];
74
74
  }
75
75
 
76
+ function grammarProblems(side, grammar) {
77
+ if (grammar === undefined) return [];
78
+ if (side !== 'fe') return ['grammar belongs to the fe side'];
79
+ return typeof grammar === 'string' && NAME.test(grammar) ? [] : ['sides.fe.grammar must name a Grammar family'];
80
+ }
81
+
76
82
  function declarationSideProblems(side, value, names) {
77
83
  const bad = [];
78
84
  const at = `sides.${side}`;
79
85
  if (!isPlainObject(value)) return [`${at} must be an object`];
80
- for (const key of Object.keys(value)) if (!['apps', 'optionalSlots', 'patterns', 'kinds', 'connections', 'reads', 'extraPackages', 'backing'].includes(key)) bad.push(`${at} has unknown key ${key}`);
86
+ for (const key of Object.keys(value)) if (!['apps', 'optionalSlots', 'patterns', 'kinds', 'connections', 'reads', 'extraPackages', 'grammar', 'backing'].includes(key)) bad.push(`${at} has unknown key ${key}`);
81
87
  bad.push(...appShapeProblems(value.apps, at, side, names));
82
88
  if (isBadUniqueList(value.optionalSlots, (slot) => SLOT_ID.test(String(slot)))) bad.push(`${at}.optionalSlots must be a unique list of slot ids`);
83
89
  if (value.backing !== undefined && side !== 'be') bad.push('backing belongs to the be side');
@@ -85,7 +91,7 @@ function declarationSideProblems(side, value, names) {
85
91
  bad.push(...patternShapeProblems(value, at, NAME), ...kindShapeProblems(value, at, NAME));
86
92
  if (isBadUniqueList(value.reads, (read) => typeof read === 'string' && read.length > 0)) bad.push(`${at}.reads must be a unique list of paths`);
87
93
  if (value.connections !== undefined) bad.push(...connectionProblems(side, value));
88
- bad.push(...extraPackageProblems(side, value.extraPackages));
94
+ bad.push(...extraPackageProblems(side, value.extraPackages), ...grammarProblems(side, value.grammar));
89
95
  return bad;
90
96
  }
91
97
 
@@ -12,7 +12,7 @@ import { fail } from './slot-errors.mjs';
12
12
 
13
13
  const HFS_RULES_FILE = 'knowledge/hfs/rules.yaml';
14
14
  const RULE_GATES = Object.freeze(['pre-commit', 'pre-push', 'settle', 'land', 'ci', 'sonar', 'runtime']);
15
- const ENFORCER_FAMILIES = Object.freeze(['eslint-be', 'eslint-fe', 'stylelint', 'machine', 'hfs', 'work-validate', 'sonar', 'runtime']);
15
+ const ENFORCER_FAMILIES = Object.freeze(['eslint-be', 'eslint-fe', 'eslint-grammar-starci', 'stylelint', 'machine', 'hfs', 'work-validate', 'sonar', 'runtime']);
16
16
  const RULE_KINDS = Object.freeze(['codemod', 'lint', 'check', 'design']);
17
17
  const FINDING_CODE = /^[A-Z][A-Z0-9]*(_[A-Z0-9]+)+$/;
18
18
  const ENFORCER_ID = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
@@ -346,7 +346,7 @@ export function loadRuleCatalog({ root = skillRoot, file = path.join(root, HFS_R
346
346
  /** The catalogued why code of a lint finding's rule id (`starci-be/<id>`, `starci-fe/<id>`), or undefined. */
347
347
  lintCode: (ruleId) => {
348
348
  const [plugin, id] = String(ruleId ?? '').split('/');
349
- const kind = (plugin === 'starci-be' && 'eslint-be') || (plugin === 'starci-fe' && 'eslint-fe') || null;
349
+ const kind = (plugin === 'starci-be' && 'eslint-be') || (plugin === 'starci-fe' && 'eslint-fe') || (plugin === 'starci-grammar' && 'eslint-grammar-starci') || null;
350
350
  return kind ? list.find((rule) => rule.enforcers.some((enforcer) => enforcer.kind === kind && enforcer.id === id))?.code : undefined;
351
351
  },
352
352
  /** The rules one enforcer judges, e.g. forEnforcer('eslint-be', 'error-home'). */
@@ -120,6 +120,7 @@ function sideDeclaration(manifest, declaration, name, edition, providers) {
120
120
  connections: Object.freeze((s.connections ?? []).map(connectionView)),
121
121
  providers,
122
122
  reads: Object.freeze([...(s.reads ?? [])]),
123
+ ...(s.grammar === undefined ? {} : { grammar: s.grammar }),
123
124
  ...(s.extraPackages === undefined ? {} : { extraPackages: Object.freeze(s.extraPackages.map(entry => Object.freeze({ ...entry }))) }),
124
125
  manifestVersion: manifest.version,
125
126
  });
@@ -33,6 +33,7 @@ function hfsView(opened, repoRoot) {
33
33
  profile: opened.repo.profile,
34
34
  side: opened.repo.side ?? null,
35
35
  edition: opened.repo.edition ?? 'full',
36
+ ...(opened.repo.grammar === undefined ? {} : { grammar: opened.repo.grammar }),
36
37
  apps: opened.repo.apps,
37
38
  connections: opened.repo.connections,
38
39
  patterns: Object.freeze([...(opened.repo.patterns ?? [])]),
@@ -0,0 +1,48 @@
1
+ // Grammar-family lint selection reads the family catalog; an absent selection never chooses a family.
2
+ import fs from 'node:fs';
3
+ import { parseYamlCached } from './yaml-cached.mjs';
4
+
5
+ const CATALOG_FILE = new URL('../../knowledge/grammars/index.yaml', import.meta.url);
6
+
7
+ function selectedFamily(family) {
8
+ if (typeof family !== 'string' || !family.trim()) throw new Error('sides.fe.grammar must explicitly name the selected Grammar family');
9
+ const catalog = parseYamlCached(fs.readFileSync(CATALOG_FILE, 'utf8'));
10
+ const matches = (catalog.families ?? []).filter(entry => entry.id === family);
11
+ if (matches.length !== 1) throw new Error(`Grammar family ${family} has no declared lint contract in knowledge/grammars/index.yaml`);
12
+ return { catalog, selected: matches[0] };
13
+ }
14
+
15
+ /** The explicitly selected authored family entry; callers share the catalog lookup rather than inferring a family. */
16
+ export function grammarFamilyFor(family) {
17
+ return Object.freeze(selectedFamily(family).selected);
18
+ }
19
+
20
+ /** The declared family's lint contract, including an explicit null package when that family has no rules. */
21
+ export function grammarLintFor(family) {
22
+ const { selected } = selectedFamily(family);
23
+ if (!selected.lint || !Object.hasOwn(selected.lint, 'package')) {
24
+ throw new Error(`Grammar family ${family} has no declared lint contract in knowledge/grammars/index.yaml`);
25
+ }
26
+ const lint = selected.lint;
27
+ if (lint.package === null) return Object.freeze({ family, package: null });
28
+ if (typeof lint.package !== 'string' || !lint.package.startsWith('@starci/eslint-grammar-')
29
+ || typeof lint.factory !== 'string' || !/^[a-zA-Z][a-zA-Z0-9]*$/.test(lint.factory)
30
+ || typeof lint.prefix !== 'string' || !/^[a-z][a-z0-9-]*$/.test(lint.prefix)) {
31
+ throw new Error(`Grammar family ${family} has an invalid lint contract in knowledge/grammars/index.yaml`);
32
+ }
33
+ return Object.freeze({ family, package: lint.package, factory: lint.factory, prefix: lint.prefix });
34
+ }
35
+
36
+ /** The selected family's shared component/export contract, resolved through its catalog reference. */
37
+ export function grammarContractFor(family) {
38
+ const { catalog, selected } = selectedFamily(family);
39
+ const owners = (catalog.families ?? []).filter(entry => entry.id === selected.contractRef);
40
+ const contract = owners.length === 1 ? owners[0].componentContract : null;
41
+ if (!contract || typeof contract.package !== 'string' || !contract.package
42
+ || typeof contract.entry !== 'string' || !contract.entry.startsWith(`${contract.package}/`)
43
+ || typeof contract.styleEntry !== 'string' || !contract.styleEntry.startsWith(`${contract.package}/`)
44
+ || !Array.isArray(contract.peers) || !contract.peers.every(peer => typeof peer === 'string' && peer.trim())) {
45
+ throw new Error(`Grammar family ${family} has no valid component contract in knowledge/grammars/index.yaml`);
46
+ }
47
+ return Object.freeze({ ...contract, peers: Object.freeze([...contract.peers]) });
48
+ }