@starci/hfs 4.7.33 → 4.7.35

package/CHANGELOG.md

@@ -1,6 +1,13 @@
 # Changelog
 
-## Unreleased
+## 4.7.35 - 2026-10-26
+- Changed: the bundled canon pins select @starci/stylelint-canon 2.0.12, @starci/eslint-canon-be 3.4.44, @starci/eslint-canon-fe 9.0.0, the Grammar lint families 0.12.3 and @starci/grammar 0.12.3.
+- Added: `app lint` composes the selected Grammar family lint with the universal front-end canon and refuses canon-fe 9 without it; the Grammar vendor-parity proof reads the generated HeroUI reference; the UI proof checks component ownership and surface layers.
+- Fixed: managed stack renders match and leave unpinned the compose `version` the scaffold declares; the history-hook spec judges the stdin handshake, not a fixed kill; the restamp inventory is active-only and clearer.
+- Changed: the runtime centralizes its parsing and gate summaries.
+
+## 4.7.34 - 2026-10-26
+- Fixed: `starci app db restamp` considers only active migrations when validating names and choosing unoccupied versions. Legacy archive names no longer block preview or apply, and archived files stay untouched.
 - Changed: the loosening check reads the tree as it stands and never its history. The bundled `scripts/lib/loosening-state.mjs` (with `js-lex.mjs` and `loosening-config.mjs`) replaces the diff detector; `HFS_BYPASS_MARKER` (R303) reads it: a suppression word opens a comment, a test marker stands in code, a swallowed failure stands in a shell line or in the string a script hands a shell, a package.json is judged by its scripts, and the same words quoted as data are no bypass. It also refuses a coverage target or threshold below the canon, a relaxing switch, a disabled ESLint rule, a tsconfig strictness option turned off and an exception file that `knowledge/hfs/design-truths.yaml` does not list. `--passWithNoTests`, `--coverageThreshold`, `--no-error-on-unmatched-pattern` and a `--max-warnings` budget are bypasses in a script, a hook or a workflow.
 - Added: `starci app emit` carries class-validator `MaxLength`, `ArrayMaxSize`, `Min` and `Max` of GraphQL input types and REST operation DTOs into the contract (a GraphQL `@inputBounds` directive and an OpenAPI constraint), and the `@starci/hfs/form-bounds` codegen plugin turns them into typed `INPUT_BOUNDS` and `inputBoundsIssues` for the form canon. The app codegen template refuses legacy or unsupported bounds metadata.
 - Changed: the operation emit refuses a non-strict `z.object` (open on the wire), publishes the real maximum length of fixed-format strings (`z.uuid()`, `z.ipv4()` and kin) and keeps `readOnly` out of request schemas.

package/README.md

@@ -84,9 +84,7 @@ Every file of a spec-required role of `ruleParams.be.unitRoles` — a `*.service
 
 The spec skeleton is `Test.createTestingModule({ providers: [Service, { provide: TOKEN, useValue: double }, ...] }).compile()` and `moduleRef.get(Service)`, with one provider per constructor dependency and nothing else, every double imported from `@starci/jest-preset` (the root), and one placeholder `it` per public method. The double of a token comes from `ruleParams.be.specDoubles` of the slot manifest, the table the lint law `spec-infra-double-from-kit` holds a spec to (`*_ENTITY_MANAGER` -> `mockEntityManager()`, `CLOCK` -> `new FakeClock(...)`, `EVENT_BUS` -> `recordingEventBus()`, `QUEUE_OUTBOX` -> `recordingQueueOutbox()`, `CACHE` -> `fakeCache(clock)`, lock, lease, fence and hold -> `fakeLock(clock)`, ids -> `fakeIds()`, `*_OPTIONS` -> a literal to fill in, everything else and every class -> `mock<T>()`), so the skeleton satisfies the law by construction: no cast, no `new` of the service, no ambient clock. A back end only (a front end has no services); the files are written for prettier (print width 120).
 
-`starci app check` reads the app's `hfs.json` and the tracked paths (`git ls-files`), checks the work tree (the root rules once, the side rules per side), and then runs the
-whole architecture machine over each side folder. Every finding carries a why code and its Vietnamese text
-(`modules/kernel/failure-codes.yaml`).
+`starci app check` runs ESLint once per side through the app's installed managed flat config: the backend canon on `be/`, and the universal FE canon plus the explicitly selected Grammar-family package on `fe/`. It also reads the app's `hfs.json` and tracked paths (`git ls-files`), checks the work tree (the root rules once, the side rules per side), and runs the whole architecture machine over each side folder. HFS findings carry their why code and Vietnamese text (`modules/kernel/failure-codes.yaml`); ESLint findings retain their rule id and failure code.
 
 Its own checks (`scripts/hfs/check.mjs`, `scripts/hfs/rules/`; the rendered-file checks (`sync/managed.mjs`) and the prettier check (`sync/format.mjs`) live in `sync/` because they read the templates and the repository's own install, and reach `starci app check` as `extraFindings`; the jest / vitest preset the coverage exclusions come from and prettier are read from the repository's `node_modules`, so run `npm ci` first):
 
@@ -103,7 +101,7 @@ Its own checks (`scripts/hfs/check.mjs`, `scripts/hfs/rules/`; the rendered-file
 | `HFS_CANON_PIN_DRIFT` | error | a dependency not at the exact version of `knowledge/hfs/canon-pins.yaml` |
 | `HFS_SIZE_SOFT_BACKLOG` | info | a source file over `ruleParams.fileLines.soft`; report only, never fails |
 | `HFS_MANAGED_FILE_DRIFT` | error | a managed file that exists but differs from its render (the `managedBy` slots: hooks, workflows, sonar, the back-end `be.tool-config` files, `app.format-config`, the `scripts` block of `app.package-manifest`, compared as parsed JSON) |
-| `HFS_RULE_OFF_WITHOUT_REPLACEMENT` | error | `eslint.config.mjs`, or a front end's `stylelint.config.mjs`, differs from its one-line render, so a rule could be off, warned or redefined in it |
+| `HFS_RULE_OFF_WITHOUT_REPLACEMENT` | error | `eslint.config.mjs`, or a front end's `stylelint.config.mjs`, differs from its managed factory render, so a rule could be off, warned or redefined in it |
 | `HFS_TOOL_CONFIG_LOCAL` | error | a repository holds a tool config outside the managed set (`.eslintrc*`, `.eslintignore`, a second `eslint.config.*` or `stylelint.config.*`, another prettier or lint-staged config, or a jest config in a back end that is not the one root file), a file that defines an ESLint rule or a stylelint plugin, a tool configuration key in a `package.json` (`eslintConfig`, `stylelint`, `prettier`, `lint-staged`, `jest`), or a script that runs eslint, stylelint or prettier with a flag that swaps the configuration |
 | `HFS_SONAR_CONFIG` | error | `sonar-project.properties` differs from its render (no host URL; the ESLint report and HFS import paths), or the stack declaration names another quality gate than the one of `knowledge/sonar-gate.yaml` |
 | `HFS_TS_STRICT` | error | the root `tsconfig.json` sets, lowers or adds anything but `extends` the preset (`be.json`, `next.json`), the template's `exclude` and (back end) the three `paths`; the finding names the flag |
@@ -145,8 +143,8 @@ Its own checks (`scripts/hfs/check.mjs`, `scripts/hfs/rules/`; the rendered-file
 
 The managed files are judged by `sync/managed.mjs` and `sync/ts-strict.mjs` (the package renders the templates; the runtime copy does not). The list of managed
 files is the `managedBy` slots of `slots.yaml`; `starci app sync --write` renders them and `starci app check` compares them, so a hand edit and a forgotten `sync` are the same finding.
-Each finding is reported once: the eslint and stylelint one-liners under R17, `tsconfig.json` under R22 when it names a flag, a workflow or hook that lost a canon step under R13 (or R19 for the format step), everything else under R05.
-The root and both sides are rendered by the one mechanism. The root: the `scripts` block of `app.package-manifest` (`dev:be`, `dev:fe`, `build:be`, `build:fe`, `start:<app>`, `lint`, `lint:fix`, `test`, `test:integration`, `test:e2e`, `test:contract`, `test:stack`, `codegen`, `contract:emit`, `migrate`, `typecheck`, ...; a be script runs from `be/`, where its tsconfig and jest configuration are), `app.format-config`, `app.hooks`, the CI slots (`app.ci`, `app.ci-e2e`, `app.ci-images`), `app.quality-config` and the managed block of `app.git-meta`. A side: its `be.tool-config` or `fe.tool-config` slot — the side's tsconfig (resolving `@starci/tsconfig` from the root `node_modules`) and its eslint one-liner, the back end's build tsconfig, tests tsconfig and jest configuration, the front end's stylelint configuration. `lint` is the one lint gate, `starci app lint`: ESLint over each side with its canon, the app check and stylelint over fe; `lint:fix` is the same with `--fix`. The front end has no test script, no test configuration and no e2e or coverage file: it has no tests, and `FE_NO_TESTS` (R97) refuses any spec, e2e file, test tool or test script under `fe/`. `turbo.json` stays the app's own
+Each finding is reported once: the managed ESLint and stylelint factory configs under R17, `tsconfig.json` under R22 when it names a flag, a workflow or hook that lost a canon step under R13 (or R19 for the format step), everything else under R05.
+The root and both sides are rendered by the one mechanism. The root: the `scripts` block of `app.package-manifest` (`dev:be`, `dev:fe`, `build:be`, `build:fe`, `start:<app>`, `lint`, `lint:fix`, `test`, `test:integration`, `test:e2e`, `test:contract`, `test:stack`, `codegen`, `contract:emit`, `migrate`, `typecheck`, ...; a be script runs from `be/`, where its tsconfig and jest configuration are), `app.format-config`, `app.hooks`, the CI slots (`app.ci`, `app.ci-e2e`, `app.ci-images`), `app.quality-config` and the managed block of `app.git-meta`. A side: its `be.tool-config` or `fe.tool-config` slot — the side's tsconfig (resolving `@starci/tsconfig` from the root `node_modules`) and its managed ESLint factory config, the back end's build tsconfig, tests tsconfig and jest configuration, the front end's stylelint configuration. `lint` is the one lint gate, `starci app lint`: ESLint over each side with its canon, the app check and stylelint over fe; `lint:fix` is the same with `--fix`. The front end has no test script, no test configuration and no e2e or coverage file: it has no tests, and `FE_NO_TESTS` (R97) refuses any spec, e2e file, test tool or test script under `fe/`. `turbo.json` stays the app's own
 (slot `app.task-graph`): it carries the task graph, which no preset can render.
 
 The architecture machine (`scripts/hfs/architecture.mjs` of the runtime, the same code bundled here): tiers and import
@@ -156,12 +154,12 @@ finding under the machine's own rule id (`BE_TIER_DIRECTION`, `HFS_UNUSED_EXPORT
 repository without `typescript` installed fails with `ARCH_TYPESCRIPT_MISSING`; the check never passes because it could not run.
 
 `--fast` judges only what changed since the merge-base of `HEAD` with
-`origin/main` (else `main`; `--base <ref>` names another ref): the slot and pin checks on the changed paths, the machine on the owners
+`origin/main` (else `main`; `--base <ref>` names another ref): ESLint on changed source files, the slot and pin checks on the changed paths, the machine on the owners
 of the changed source files without clones and dead exports, and no file-system tree checks. The required-file and minimum-instance
 checks still cover the whole tree. With no merge-base `--fast` is a refusal (exit 2) that names the fix, never a silent full
 pass.
 
-Exit codes: 0 clean, 1 an error finding, 2 a refusal (not a Git work tree, bad flag, `--fast` with no merge-base). `starci app check` and `starci app lint` never write to the app
+Exit codes: 0 clean, 1 an error finding, 2 a tool could not run or a refusal (not a Git work tree, bad flag, `--fast` with no merge-base). `starci app check` and `starci app lint` never write to the app
 (`starci app lint --fix` lets ESLint and stylelint fix in place).
 
 ## Sonar
@@ -169,7 +167,7 @@ Exit codes: 0 clean, 1 an error finding, 2 a refusal (not a Git work tree, bad f
 One mechanism for both sides: every finding of the canon is imported into Sonar, and the quality gate
 fails while any is open. Nothing is configured per app; the pieces are managed files (`starci app sync`) and this package.
 
-One entry, one report, one file: `npm run lint` is `starci app lint`; `npm run lint -- --sonar reports/lint.sonar.json` writes the ONE Sonar file, read through `sonar.externalIssuesReportPaths`. It carries three engines: `starci-hfs` (the repository findings of `starci app check`, rule id = the finding code), `eslint` (the BE and FE canon plugins alike, rule id = the ESLint rule) and `stylelint` over fe (rule id = the stylelint rule). `starci app lint --format json` prints the same findings as the one report `starci/lint@1` (`{ schema, ok, changed, counts.error, engines, errors[], findings[{ engine, rule, code, severity, path, line, column, message }] }`); `--changed <files...>` restricts ESLint and stylelint to those files and keeps of the repository findings the ones on a listed file or on no file. The exit code is 0 clean, 1 findings, 2 a tool could not run (a missing ESLint install is never a pass).
+One entry, one report, one file: `npm run lint` is `starci app lint`; `npm run lint -- --sonar reports/lint.sonar.json` writes the ONE Sonar file, read through `sonar.externalIssuesReportPaths`. It carries three engines: `starci-hfs` (the repository findings, rule id = the finding code), `eslint` (the BE canon, universal FE canon and selected Grammar-family plugin, rule id = the ESLint rule) and `stylelint` over fe (rule id = the stylelint rule). App lint shares app check's ESLint runner and calls its HFS checks in process, so each side's ESLint config runs once. `starci app lint --format json` prints the same findings as the one report `starci/lint@1` (`{ schema, ok, changed, counts.error, engines, errors[], findings[{ engine, rule, code, severity, path, line, column, message }] }`); `--changed <files...>` restricts ESLint and stylelint to those files and keeps of the repository findings the ones on a listed file or on no file. The exit code is 0 clean, 1 findings, 2 a tool could not run (a missing ESLint install is never a pass).
 
 `--sonar` writes the findings as a Generic Issue Import document (SonarQube 10.3+ format: `{ rules, issues }`) before the verdict, so a
 failing lint still leaves its report. A rule's name and description are the catalog's English title and Vietnamese title, meaning and next step;
@@ -202,8 +200,7 @@ derived from the machine's rule id lists). After changing any of those files, `k
 `starci release sync-runtime --check` fails on a stale copy. Bump `version` here and in the pin when the behaviour changes.
 
 The examples workflow (`.github/workflows/examples.yml`) runs `starci app lint` of this CLI at the root of every `examples/*`
-app with an `hfs.json` (each `examples/<app>` root) and fails on any finding or any tool that could not run;
-`starci app check` alone would miss the machine's source rules, which the canons judge.
+app with an `hfs.json` (each `examples/<app>` root) and fails on any finding or any tool that could not run. This includes the ESLint canons and repository checks also run by `starci app check`, plus stylelint over the frontend stylesheets.
 
 ## Serving knowledge to other packages
 

package/lint/run.mjs

@@ -17,7 +17,7 @@
 // turbo `lint` task); the root `npm run lint` stays the whole app. There is no second linter: a workspace lint is this lint, scoped.
 import fs from 'node:fs';
 import path from 'node:path';
-import { createRequire } from 'node:module';
+import { createRequire, registerHooks } from 'node:module';
 import { spawn } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { linterReport, mergeReports, sonarReport, sourceRootsOf } from '../report/sonar.mjs';
@@ -25,6 +25,7 @@ import { SIDES, appRelativeMessages, loadSlotManifest, readRepoDeclaration } fro
 import { STYLE_GLOB } from '../sync/index.mjs';
 import { byCodeUnit } from '../report/order.mjs';
 import { braceVariants, globExpression } from '../runtime/scripts/lib/glob.mjs';
+import { grammarLintFor } from '../runtime/scripts/lib/grammar-lint.mjs';
 
 // --side judges only that side; root HFS findings belong to be, its Sonar report stays on that side.
 export const LINT_SCHEMA = 'starci/lint@1';
@@ -164,18 +165,46 @@ export function canonScope(config) {
   };
 }
 
-/** Read the installed canon's source selectors, then enumerate that scope; unavailable or unsupported selectors cannot prove coverage. */
-async function sourceFiles({ repoRoot, cwd, side, scope: folderScope }) {
-  const entry = createRequire(path.join(cwd, 'package.json')).resolve(`@starci/eslint-canon-${side}`);
+/** Resolve one canon from this app's install; a package from an enclosing repository cannot prove its lint contract. */
+function ownCanonEntry({ repoRoot, cwd }, packageName) {
+  const require = createRequire(path.join(cwd, 'package.json'));
+  // The entry is imported below, so resolve with Node's import conditions even when a package publishes no require target.
+  // The synchronous hook exists only for this lookup; later package resolution keeps its own conditions.
+  const hook = registerHooks({ resolve: (specifier, context, nextResolve) => nextResolve(specifier, specifier === packageName
+    ? { ...context, conditions: [...new Set([...context.conditions.filter(condition => condition !== 'require'), 'import'])] }
+    : context) });
+  let entry;
+  try { entry = require.resolve(packageName); }
+  finally { hook.deregister(); }
   // The canon must be the app's own install: resolved inside the app root, or inside the app's node_modules when that folder is a link to the install
   // (the runtime's examples lint in a sealed copy whose node_modules links the example's own install, scripts/hfs/example-secrets.mjs).
   const ownInstall = [repoRoot, path.join(repoRoot, 'node_modules')].filter((dir) => fs.existsSync(dir)).map((dir) => fs.realpathSync(dir));
   if (!ownInstall.some((root) => inside(root, fs.realpathSync(entry)))) throw new Error('the installed canon is outside the app root');
+  return entry;
+}
+
+/** Both installed FE canons supply the source config; family selection is explicit and an unavailable factory fails closed. */
+export async function installedLintConfig({ repoRoot, cwd, side }) {
+  const entry = ownCanonEntry({ repoRoot, cwd }, `@starci/eslint-canon-${side}`);
   const canon = await import(pathToFileURL(entry).href);
   const factory = side === 'be' ? canon.starciBeConfig : canon.starciFeConfig;
   if (typeof factory !== 'function' || typeof canon.loadHfs !== 'function') throw new Error('the installed canon has no supported config factory');
-  const config = await factory({ hfs: canon.loadHfs(pathToFileURL(path.join(cwd, 'eslint.config.mjs')).href) });
+  const hfs = canon.loadHfs(pathToFileURL(path.join(cwd, 'eslint.config.mjs')).href);
+  const config = await factory({ hfs });
   if (!Array.isArray(config)) throw new Error('the installed canon did not return a flat config');
+  if (side !== 'fe') return config;
+  const family = grammarLintFor(hfs.grammar);
+  if (family.package === null) return config;
+  const familyCanon = await import(pathToFileURL(ownCanonEntry({ repoRoot, cwd }, family.package)).href);
+  if (typeof familyCanon[family.factory] !== 'function') throw new Error(`${family.package} has no supported ${family.factory} factory`);
+  const familyConfig = await familyCanon[family.factory]({ hfs });
+  if (!Array.isArray(familyConfig)) throw new Error(`${family.package} did not return a flat config`);
+  return [...config, ...familyConfig];
+}
+
+/** Read both installed canons' source selectors, then enumerate that scope; unavailable selectors cannot prove coverage. */
+async function sourceFiles({ repoRoot, cwd, side, scope: folderScope }) {
+  const config = await installedLintConfig({ repoRoot, cwd, side });
   const scope = canonScope(config);
   const files = [];
   const visit = (folder) => {
@@ -217,7 +246,7 @@ function checkedEslintResults({ results, expected, cwd, scope, changed }) {
 }
 
 /** Starts the ESLint child of every side that has work and returns one record per side: skipped, a scope error, or the running child. */
-async function launchEslint({ app, repoRoot, opts, changed, existing, workspace, onFe }) {
+async function launchEslint({ app, repoRoot, opts, changed, existing, workspace, onFe, run = runLinter }) {
   const launches = [];
   for (const side of app ? SIDES.filter((candidate) => opts.side === undefined || opts.side === candidate) : []) {
     if (workspace !== null && side !== STYLE_SIDE) { launches.push({ side, skipped: `outside --workspace ${workspace}` }); continue; }
@@ -227,11 +256,38 @@ async function launchEslint({ app, repoRoot, opts, changed, existing, workspace,
     let expected;
     try { expected = changed ? sources : await sourceFiles({ repoRoot, cwd, side, scope: onFe }); }
     catch (error) { launches.push({ side, scopeError: `eslint source scope is unavailable in ${side}/: ${String(error?.message ?? error)}` }); continue; }
-    launches.push({ side, cwd, expected, run: runLinter({ cwd, pkg: 'eslint', bin: 'eslint', args: ['--format', 'json', ...(opts.fix ? ['--fix'] : []), ...(changed ? sources : [onFe ?? '.'])], bound: repoRoot }) });
+    launches.push({ side, cwd, expected, run: run({ cwd, pkg: 'eslint', bin: 'eslint', args: ['--format', 'json', ...(opts.fix ? ['--fix'] : []), ...(changed ? sources : [onFe ?? '.'])], bound: repoRoot }) });
   }
   return launches;
 }
 
+/** Execute each side's installed ESLint config once; check and lint share scope, coverage and tool-failure judgment. */
+export async function eslintRepository({ repoRoot, app = readRepoDeclaration(loadSlotManifest(), repoRoot), opts = {}, changed = null, existing = [], workspace = null, onFe = null, run }) {
+  const findings = [], errors = [], raw = [];
+  const engine = { sides: {} };
+  if (!app.sides) throw new Error('ESLint runs at the app root, the folder of hfs.json');
+  const launches = await launchEslint({ app, repoRoot, opts, changed, existing, workspace, onFe, run });
+  const runs = await Promise.all(launches.map(launch => launch.run ?? null));
+  launches.forEach((launch, at) => {
+    const { side } = launch;
+    if (launch.skipped) { engine.sides[side] = { files: 0, skipped: launch.skipped }; return; }
+    if (launch.scopeError) { errors.push(launch.scopeError); engine.sides[side] = { files: 0 }; return; }
+    const linted = runs[at];
+    if (linted.error) errors.push(linted.error);
+    if (linted.results) {
+      const checked = checkedEslintResults({ results: linted.results, expected: launch.expected, cwd: launch.cwd, scope: onFe, changed: changed !== null });
+      errors.push(...checked.errors);
+      linted.results = checked.results;
+      const appRelative = appRelativeMessages(side, path.join(repoRoot, side));
+      for (const result of linted.results) for (const message of result.messages ?? []) message.message = appRelative(message.message);
+      raw.push(...linted.results);
+      findings.push(...eslintFindings(linted.results, repoRoot));
+    }
+    engine.sides[side] = { files: linted.results?.length ?? 0 };
+  });
+  return { findings, errors, raw, engine };
+}
+
 /** Starts stylelint over the fe stylesheets (the running child), or returns null when no stylesheet is in scope. */
 function launchStylelint({ repoRoot, opts, changed, existing, onFe }) {
   if (opts.side === 'be') return null;
@@ -244,7 +300,7 @@ function launchStylelint({ repoRoot, opts, changed, existing, onFe }) {
  * Run the whole lint of the app at `repoRoot`. `hfsCheck(repoRoot)` returns the `starci app check` result (`{ findings, tracked }`); the CLI
  * injects it. Returns `{ report, sonar, exit }`; `sonar` is the merged Generic Issue Import document.
  */
-export async function lintRepository({ repoRoot, opts, hfsCheck, trackedFiles = () => [] }) {
+export async function lintRepository({ repoRoot, opts, hfsCheck, trackedFiles = () => [], runLinter: linter }) {
   const changed = opts.changed === null ? null : new Set(opts.changed);
   const errors = [];
   let workspace = null;
@@ -269,31 +325,16 @@ export async function lintRepository({ repoRoot, opts, hfsCheck, trackedFiles =
   const onFe = workspace === null ? null : workspace.slice(STYLE_SIDE.length + 1);
 
   // The linters and the app check are independent: every child starts first, the app check runs while they work, and the results are read in a fixed order.
-  const eslintLaunches = await launchEslint({ app, repoRoot, opts, changed, existing, workspace, onFe });
+  const eslintRun = app ? eslintRepository({ app, repoRoot, opts, changed, existing, workspace, onFe, run: linter }) : null;
   const styleLaunch = app ? launchStylelint({ repoRoot, opts, changed, existing, onFe }) : null;
   const checkRun = app ? Promise.resolve().then(() => hfsCheck(repoRoot)).then((value) => ({ value }), (error) => ({ error })) : null;
 
   // 1. ESLint, once per side, from the side folder with that side's config.
-  engines.eslint = { sides: {} };
-  const eslintRuns = await Promise.all(eslintLaunches.map((launch) => launch.run ?? null));
-  eslintLaunches.forEach((launch, at) => {
-    const { side } = launch;
-    if (launch.skipped) { engines.eslint.sides[side] = { files: 0, skipped: launch.skipped }; return; }
-    if (launch.scopeError) { errors.push(launch.scopeError); engines.eslint.sides[side] = { files: 0 }; return; }
-    const linted = eslintRuns[at];
-    if (linted.error) errors.push(linted.error);
-    if (linted.results) {
-      const checkedResults = checkedEslintResults({ results: linted.results, expected: launch.expected, cwd: launch.cwd, scope: onFe, changed: changed !== null });
-      errors.push(...checkedResults.errors);
-      linted.results = checkedResults.results;
-      // The side canon names side-relative paths in its messages; the report names every path from the app root.
-      const appRelative = appRelativeMessages(side, path.join(repoRoot, side));
-      for (const result of linted.results) for (const message of result.messages ?? []) message.message = appRelative(message.message);
-      raw.eslint.push(...linted.results);
-      findings.push(...eslintFindings(linted.results, repoRoot));
-    }
-    engines.eslint.sides[side] = { files: linted.results?.length ?? 0 };
-  });
+  const eslint = eslintRun ? await eslintRun : { engine: { sides: {} }, errors: [], raw: [], findings: [] };
+  engines.eslint = eslint.engine;
+  errors.push(...eslint.errors);
+  raw.eslint.push(...eslint.raw);
+  findings.push(...eslint.findings);
 
   // 3. stylelint over the fe side's stylesheets.
   if (app) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.7.33",
+  "version": "4.7.35",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",
@@ -50,7 +50,7 @@
     "CHANGELOG.md"
   ],
   "engines": {
-    "node": ">=22.13.0"
+    "node": ">=22.15.0"
   },
   "publishConfig": {
     "access": "public"

package/runtime/knowledge/grammars/index.yaml

@@ -0,0 +1,102 @@
+schema: starci/knowledge-source@1
+id: grammars
+title: Grammar families
+purpose: |
+  Catalog of authored UI Grammar families. Inventory only — not a default-family rule.
+  The selected design specification names the applicable installed family. The app binds that choice
+  explicitly in sides.fe.grammar; the catalog resolves its lint package and component contract.
+  A missing or ambiguous family never silently resolves to a family. DNA snapshots describe the
+  observed implementation; they do not install packages or prove current rendered behavior.
+appliesTo:
+  - grammar
+provenance:
+  limitations: |
+    Component names, tokens and gap tables describe the reference family at observation time.
+    Verify actual package identity/version, exported types, CSS and renderer source in the selected
+    repository before using snapshot APIs or gaps. Record current source references in the selected
+    .starciwork node; an old source census is not current UAT evidence. The current public consumer
+    entry observed for FE work is @starci/grammar/common — confirm installed exports before import.
+    The `common` entry is a DNA snapshot of that semantic entry and nothing more: it declares no palette,
+    no family boundary and no composition playbook, because the entry itself ships none of them.
+guidance:
+  - id: catalog-not-default
+    requirement: |
+      Do not treat this catalog as selecting a default Grammar family. Family choice belongs to the
+      current design specification and its explicit sides.fe.grammar declaration.
+    rationale: |
+      Silent fallback to StarCi would invent product direction and override an absent/ambiguous design.
+  - id: verify-before-use
+    requirement: |
+      Before applying snapshot APIs or recorded gaps, inspect the selected repository's package
+      identity/version, exported types, CSS and renderer source.
+    rationale: |
+      Snapshots are historical; installed exports may differ. Inventing missing APIs is forbidden.
+  - id: ui-owns-universal
+    requirement: |
+      Common semantics, renderer anatomy, state and accessibility remain owned by knowledge/ui.
+      A family owns its scoped visual realization and promoted idioms; the product owns its facts,
+      content, routes and approved composition.
+      Apply FE-RULE-OWNERSHIP in knowledge/patterns/fe/index.yaml when placing requirements and checks.
+    rationale: |
+      Keeps universal UI law separate from family-scoped DNA and product composition.
+topics:
+  - id: common
+    path: common/DNA.yaml
+    title: Common Grammar — DNA
+    summary: |
+      Generated DNA snapshot of the `@starci/grammar/common` public entry: custom properties,
+      the 110 renderers of its registry, their classes, stamped rule ids and recorded gaps. The DNA owns the observed package
+      version and source inventory. Common supplies anatomy, not colour. The snapshot is drift-checked.
+  - id: starci
+    path: starci/index.yaml
+    title: StarCi Core Grammar
+    summary: |
+      Historical snapshot of the StarCi Core family — DNA, idioms, playbook (including composing the
+      0.5.0 forms, overlays and navigation chrome) and family boundaries.
+  - id: offset-pop
+    path: offset-pop/index.yaml
+    title: Offset Pop Grammar
+    summary: |
+      Snapshot of the product-neutral Offset Pop family — cream canvas, ink outline plus hard offset
+      shadow, one pink decision accent with a text-safe accent for text — with DNA, idioms, a
+      mobile-first playbook for playful learning or consumer apps, and family boundaries including two
+      decisions flagged for the family owner.
+families:
+  - id: common
+    title: common
+    componentContract:
+      package: '@starci/grammar'
+      entry: '@starci/grammar/common'
+      styleEntry: '@starci/grammar/common.css'
+      peers: [react, '@heroui/react', '@xyflow/react']
+    packageSnapshot: common/DNA.yaml
+    scope: |
+      DNA snapshot only. This catalog carries no Common-side family boundary, idiom set or composition
+      playbook: `@starci/grammar/common` is the semantic/props entry every visual family is defined over
+      (`defineGrammarFamily`), not a family that ships a palette, so `authority`, `reusableStyle`,
+      `productComposition` and `index` have nothing to name here. Universal semantics, renderer anatomy,
+      state and accessibility remain owned by knowledge/ui.
+  - id: starci
+    title: starci
+    contractRef: common
+    lint:
+      package: '@starci/eslint-grammar-starci'
+      factory: starciGrammarConfig
+      prefix: starci-grammar
+    authority: starci/family.yaml
+    packageSnapshot: starci/DNA.yaml
+    reusableStyle: starci/idioms.yaml
+    productComposition: starci/playbook.yaml
+    index: starci/index.yaml
+  - id: offset-pop
+    title: offset-pop
+    contractRef: common
+    lint:
+      package: '@starci/eslint-grammar-offset-pop'
+      factory: offsetPopGrammarConfig
+      prefix: starci-grammar
+    authority: offset-pop/family.yaml
+    packageSnapshot: offset-pop/DNA.yaml
+    reusableStyle: offset-pop/idioms.yaml
+    productComposition: offset-pop/playbook.yaml
+    index: offset-pop/index.yaml