@starci/eslint-canon-fe 8.0.9 → 8.1.0

package/CHANGELOG.md

@@ -1,7 +1,8 @@
 # Changelog
 
-## Unreleased
+## 8.1.0 - 2026-10-08
 
+- New: the `sonar-parity` law (R235 `SCAN_SMELL`): `no-await-in-loop` (S9382), `prefer-code-point` (S7758), `prefer-string-raw` (S7780), `no-nested-conditional` (S3358), `no-void-operator` (S3735), `no-unused-import` (S1128), `prefer-export-from` (S7763) and `no-unused-prop-types` (S6767), each the syntax-tree form of the Sonar rule SonarCloud flagged in the example apps, shared with the back-end canon through the bundled `runtime/scripts/lib/sonar-syntax-rules.mjs`. The factory also turns on the typescript-eslint rules `no-deprecated` (S1874), `no-base-to-string` (S6551) and `require-await` (S7503); `@typescript-eslint/eslint-plugin` becomes a dependency of this package.
 - Changed: `one-outcome-union` reads the Outcome home from the slot manifest (`outcomeHome` on `fe.transport.outcome`, `fe.package.api.outcome` and the lite `fe.modules.db.outcome`, i.e. `modules/db/outcome.ts`) instead of two slot ids in code; a lite app's db owner is its transport, so its `modules/db/outcome.ts` is THE union and a second one anywhere else is still refused. Full is unchanged.
 - Changed: `public-component-signature` accepts a component with no parameter; `no-raw-structural-element` names `Region`, `NavLandmark`, `List` and `ListItem` as owners of section, nav, ul/ol and li; FE-I18N-1 and FE-TYPING-6 canon text (request locale through `next/root-params`, no `void props`); the FE_SWR_KEY_IDENTITY check reads `&&` and `||` gates in its bundled runtime.
 ## Unreleased (C0 batch)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) StarCi contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -21,6 +21,7 @@ flat-config blocks and owns everything about the law: which files are linted (fr
 recommended set lifted to `error`), typed linting, and the inline-directive fence (`noInlineConfig` plus
 `reportUnusedDisableDirectives`). The repository states nothing.
 
+- The **Sonar parity** law (R235): the smells SonarCloud measures that a lint rule can decide, `no-await-in-loop`, `prefer-code-point`, `prefer-string-raw`, `no-nested-conditional`, `no-void-operator`, `no-unused-import`, `prefer-export-from` and `no-unused-prop-types`, plus the typescript-eslint rules `no-deprecated`, `no-base-to-string` and `require-await` the factory turns on (they read types, so the source block is typed). A Next `matcher` string keeps its escapes (the segment config is read statically); `*.spec.ts` and `*.e2e-spec.ts` are outside the scan, so outside these rules.
 - The **ignore** block: `node_modules`, `.next`, `dist`, `coverage`, `__generated__` and `.starci/`.
 - The **source** block governs `apps/*/src/**` and `packages/*/src/**` with types (`parserOptions.projectService`) and
   `settings.starci.hfs`, the slot view path-scoped rules ask (`lib/hfs.mjs` `hfsOf`), never a path pattern.
@@ -34,7 +35,7 @@ Each law has a page under [`docs/`](docs) with, for every rule, an invalid and a
 its Vietnamese why. New in 5.0: [env-owner](docs/env-owner.md), [transport](docs/transport.md),
 [client-boundary](docs/client-boundary.md), [hooks-folder](docs/hooks-folder.md),
 [next-conventions](docs/next-conventions.md), [translation](docs/translation.md) (no literal copy at any
-tier, no `vn-ok`), [brand-values](docs/brand-values.md), [native-controls](docs/native-controls.md),
+tier), [brand-values](docs/brand-values.md), [native-controls](docs/native-controls.md),
 [size-and-state-budget](docs/size-and-state-budget.md) and [lint-escape-hatch](docs/lint-escape-hatch.md). New in 5.1: [lists](docs/lists.md), [hygiene](docs/hygiene.md), [formatting](docs/formatting.md) and [type-safety](docs/type-safety.md), plus rules added to next-conventions, client-boundary, native-controls and transport. New in 6.1: `no-vietnamese-in-source` (English-only identifiers, strings, comments and test titles; the i18n fixtures slot `e2e/fixtures/i18n/` is the one exemption). New in 6.0: `effect-subscription-needs-cleanup` (timers, frames, listeners, observers, sockets and subscriptions are released against the same handle), `server-module-marks-server-only` ([client-boundary](docs/client-boundary.md)), `no-data-fetch-in-effect` sees indirect loads, `no-hardcoded-copy` reads templates and sentence values, `no-inline-lint-config` refuses `NOSONAR` and the coverage/formatter switches. Also new in 6.0: [grammar-boundary](docs/grammar-boundary.md) (`no-raw-structural-element`), `one-outcome-union` ([transport](docs/transport.md)), `i18n-stack-in-one-module` ([next-conventions](docs/next-conventions.md)), [size-growth](docs/size-growth.md) (`file-size-growth`: a file over the manifest's line budget is not born large and does not grow; the budget is `ruleParams.fe.fileLines`, read from the manifest copy in `runtime/`).
 
 Older laws cover comments, file layout, icons and vendor ownership, landmarks, loading states,

package/comments.mjs

@@ -6,8 +6,7 @@
  * chunks and JSX text alike - everywhere prose can hide in a source file.
  *
  * `no-vietnamese-in-source` holds the English-only law: identifiers, string literals, template text, JSX text,
- * comments and test titles carry no Vietnamese letter. The old `vn-ok: <reason>` pragma is gone (it was used 490
- * times in one repository, and one escape is enough to turn a rule into a comment convention). Detection is
+ * comments and test titles carry no Vietnamese letter. There is no exemption marker. Detection is
  * structural on characters (`scripts/lib/language.mjs`, folded to NFC), never a word list.
  *
  * The exceptions that remain are placements, not judgements, and that is on purpose: a locale dictionary
@@ -16,6 +15,7 @@
  */
 
 import { hasSecondLanguage } from "./runtime/scripts/lib/language.mjs"
+import { jsdocBefore } from "./runtime/scripts/lib/jsdoc.mjs"
 import { fileOf, inSlot } from "./lib/scope.mjs"
 
 /**
@@ -82,13 +82,12 @@ export const requireExportJsdoc = {
     schema: [],
     messages: {
       jsdoc:
-        "`{{name}}` is exported with no documentation block. An export is read far more often than it is written, and by people who never open the body - name the ROLE it plays, not the signature, which the signature already states.",
+        "`{{name}}` is exported without an adjacent JSDoc description. An export is read far more often than it is written, and by people who never open the body - name the ROLE it plays, not the signature, which the signature already states.",
     },
   },
   create(context) {
     const source = context.sourceCode || context.getSourceCode()
-    const hasBlock = (node) =>
-      source.getCommentsBefore(node).some((comment) => comment.type === "Block" && comment.value.startsWith("*"))
+    const hasBlock = (node) => jsdocBefore(source, node) !== null
     const check = (node) => {
       const declaration = node.declaration
       if (!declaration) return

package/docs/lint-escape-hatch.md

@@ -2,13 +2,13 @@
 
 Law module: `lint-escape-hatch.mjs`. Catalogue: R18 HFS_INLINE_SUPPRESSION.
 
-No `eslint-disable` (line, next-line, block), `eslint-enable`, `eslint-env`, inline `eslint rule: ...` config, `@ts-ignore`, `@ts-expect-error`, `@ts-nocheck`, no retired `vn-ok:` pragma, and no `NOSONAR`, `@sonar-ignore`, `istanbul ignore`, `c8 ignore`, `v8 ignore`, `prettier-ignore` or `stylelint-disable` comment. `noInlineConfig` makes a directive ineffective, this rule makes it a finding, and `reportUnusedDisableDirectives` reports a leftover that suppresses nothing. The rule covers `src/**`, specs and the e2e tree.
+No `eslint-disable` (line, next-line, block), `eslint-enable`, `eslint-env`, inline `eslint rule: ...` config, `@ts-ignore`, `@ts-expect-error`, `@ts-nocheck`, and no `NOSONAR`, `@sonar-ignore`, `istanbul ignore`, `c8 ignore`, `v8 ignore`, `prettier-ignore` or `stylelint-disable` comment. `noInlineConfig` makes a directive ineffective, this rule makes it a finding, and `reportUnusedDisableDirectives` reports a leftover that suppresses nothing. The rule covers `src/**`, specs and the e2e tree.
 
 Every rule below is an error in `starciFeConfig`; none can be switched off or suppressed inline.
 
 ## `starci-fe/no-inline-lint-config`
 
-Source cannot change its own lint or type-check policy, and the vn-ok pragma is retired.
+Source cannot change its own lint or type-check policy.
 
 **Invalid** (`src/components/blocks/Feed/index.tsx`)
 
@@ -17,7 +17,7 @@ Source cannot change its own lint or type-check policy, and the vn-ok pragma is
 // @ts-ignore
 // NOSONAR
 /* istanbul ignore next */
-const s = "x" // vn-ok: reason
+const s = "x" // eslint-disable-line no-console
 ```
 
 **Valid** (`src/components/blocks/Feed/index.tsx`)
@@ -31,4 +31,4 @@ const s = 1
 
 **Why:** There is a rule-disabling comment at `<file>:<line>`. HFS does not allow disabling in place - fix the code, or propose changing the rule.
 
-**Fix:** Remove `eslint-disable`, `@ts-ignore`, `@ts-expect-error` or `vn-ok` and fix the cause.
+**Fix:** Remove `eslint-disable`, `@ts-ignore`, or `@ts-expect-error` and fix the cause.

package/docs/translation.md

@@ -2,7 +2,7 @@
 
 Law module: `translation.mjs`. Catalogue: R58 FE_I18N_LITERAL.
 
-No text a reader can see or hear is written in source, at any tier and in any language: it is read from a `next-intl` catalogue through `t()`. There is no `vn-ok` pragma, no endonym exemption and no `resources/` copy folder; the catalogues (`messages/<locale>.json`), fixtures and specs are the only content paths. The notion of a literal is the same as the repository's i18n catalog check: a word is two or more letters, and the copy attributes are `label`, `title`, `alt`, `placeholder` and the `aria-*` set.
+No text a reader can see or hear is written in source, at any tier and in any language: it is read from a `next-intl` catalogue through `t()`. There is no pragma, no endonym exemption and no `resources/` copy folder; the catalogues (`messages/<locale>.json`), fixtures and specs are the only content paths. The notion of a literal is the same as the repository's i18n catalog check: a word is two or more letters, and the copy attributes are `label`, `title`, `alt`, `placeholder` and the `aria-*` set.
 
 Every rule below is an error in `starciFeConfig`; none can be switched off or suppressed inline.
 
@@ -51,4 +51,4 @@ A template literal with substitutions is copy when its static parts contain a wo
 
 **Why:** The text `"<text>"` at `<file>:<line>` does not go through `t()`.
 
-**Fix:** Move the sentence into `modules/i18n/messages/<locale>.json` and read it with `t("key")`; there is no exception and no `vn-ok`.
+**Fix:** Move the sentence into `modules/i18n/messages/<locale>.json` and read it with `t("key")`; there is no exception.

package/file-layout.mjs

@@ -346,7 +346,7 @@ export const sourceTierMarkerMatchesFolder = {
   },
 }
 
-/** `shells/` no longer exists; vendor mechanics are closed named branches. */
+/** `shells/` is not a tier; vendor mechanics are closed named branches. */
 export const noShellTier = {
   meta: {
     type: "problem",

package/icon.mjs

@@ -19,7 +19,7 @@ import { fileOf, isComponentFile, isProductSource, kindOfFile, roleOfFile } from
 /** The one module allowed to name a glyph from a library: the entry of the leaf owner named `Icon`. */
 const ICON_LEAF = { kind: "leaves", owner: "Icon" }
 
-/** Repeated goal / metric cells are text-led in the legacy reference: the entry of the composite owner named `LabelledProgressRow`. */
+/** Repeated goal / metric cells are text-led in the reference: the entry of the composite owner named `LabelledProgressRow`. */
 const LABELLED_PROGRESS_ROW = { kind: "composites", owner: "LabelledProgressRow" }
 
 /**
@@ -169,7 +169,7 @@ export const noDecorativeIconInMetricCell = {
     schema: [],
     messages: {
       decorative:
-        "`LabelledProgressRow` is a repeated metric cell, not a feature entry. Its legacy reference is text-led, so an `Icon` here invents emphasis and repeats glyph meanings across the grid. Keep the label and figure; reserve tiny glyphs for generic state or action semantics actually present in the reference.",
+        "`LabelledProgressRow` is a repeated metric cell, not a feature entry. Its reference is text-led, so an `Icon` here invents emphasis and repeats glyph meanings across the grid. Keep the label and figure; reserve tiny glyphs for generic state or action semantics actually present in the reference.",
     },
   },
   create(context) {

package/index.mjs

@@ -47,6 +47,7 @@ import { recommended as typeSafetyRecommended, rules as typeSafetyRules } from "
 import { recommended as typographyRecommended, rules as typographyRules } from "./typography.mjs"
 import { recommended as vendorRecommended, rules as vendorRules } from "./vendor-boundary.mjs"
 import { recommended as projectGraphRecommended, rules as projectGraphRules } from "./project-graph.mjs"
+import { recommended as sonarParityRecommended, rules as sonarParityRules } from "./sonar-parity.mjs"
 import { buildFeConfig } from "./lib/config.mjs"
 import { why } from "./lib/why.mjs"
 
@@ -88,6 +89,7 @@ const CONTRIBUTIONS = [
   { law: "type-safety", rules: typeSafetyRules, recommended: typeSafetyRecommended },
   { law: "typography", rules: typographyRules, recommended: typographyRecommended },
   { law: "vendor-boundary", rules: vendorRules, recommended: vendorRecommended },
+  { law: "sonar-parity", rules: sonarParityRules, recommended: sonarParityRecommended },
 ]
 
 /** Every gathered law. */
@@ -176,6 +178,9 @@ const loadReactHooks = () => {
   throw new Error("starciFeConfig needs eslint-plugin-react-hooks 7 or newer: npm i -D eslint-plugin-react-hooks")
 }
 
+/** The typescript-eslint plugin whose type-aware rules the factory borrows (Sonar S1874, S6551 and S7503); a dependency of this package. */
+const loadTsPlugin = () => createRequire(import.meta.url)("@typescript-eslint/eslint-plugin")
+
 /**
  * The React Hooks rules of a plugin, all at error.
  *
@@ -226,6 +231,7 @@ export const starciFeConfig = ({ hfs } = {}) => {
     hfs,
     plugin,
     reactHooks,
+    tsPlugin: loadTsPlugin(),
     source: { ...recommended, ...reactHooksRules(reactHooks) },
   })
 }

package/lib/config.mjs

@@ -23,6 +23,13 @@ export const SOURCE_FILES = Object.freeze(["apps/*/src/**/*.{ts,tsx}", "packages
 /** Build output, installed packages, generated wire types and the harness's report directory are never linted. */
 export const IGNORED = Object.freeze(["**/node_modules/**", "**/.next/**", "**/dist/**", "**/coverage/**", "**/__generated__/**", ".starci/**"])
 
+/** The type-aware typescript-eslint rules the canon borrows for Sonar S1874 (a deprecated API), S6551 (an object turned into text) and S7503 (an `async` function that never awaits), all `error`. */
+export const BORROWED = Object.freeze({
+  "@typescript-eslint/no-deprecated": "error",
+  "@typescript-eslint/no-base-to-string": "error",
+  "@typescript-eslint/require-await": "error",
+})
+
 const levelOf = (setting) => (Array.isArray(setting) ? setting[0] : setting)
 
 /**
@@ -33,9 +40,10 @@ const levelOf = (setting) => (Array.isArray(setting) ? setting[0] : setting)
  * @param {object} input.plugin - The canon plugin.
  * @param {Record<string, unknown>} input.source - The source-tree levels (canon rules plus the React Hooks rules).
  * @param {object} input.reactHooks - The React Hooks plugin.
+ * @param {object} input.tsPlugin - The typescript-eslint plugin.
  * @returns {Array<object>} The flat config: one ignore block and one typed source block.
  */
-export const buildFeConfig = ({ hfs, plugin, source, reactHooks }) => {
+export const buildFeConfig = ({ hfs, plugin, source, reactHooks, tsPlugin }) => {
   if (!hfs || typeof hfs.slotOf !== "function" || typeof hfs.repoRoot !== "string") {
     throw new Error("starciFeConfig needs { hfs: loadHfs(import.meta.url) } - the rules read the repository's slots through it")
   }
@@ -55,9 +63,9 @@ export const buildFeConfig = ({ hfs, plugin, source, reactHooks }) => {
         parserOptions: { projectService: true, tsconfigRootDir: hfs.repoRoot, ecmaFeatures: { jsx: true } },
       },
       linterOptions: { ...linterOptions },
-      plugins: { "starci-fe": plugin, "react-hooks": reactHooks },
+      plugins: { "starci-fe": plugin, "react-hooks": reactHooks, "@typescript-eslint": tsPlugin },
       settings,
-      rules: { ...source },
+      rules: { ...source, ...BORROWED },
     },
   ]
 }

package/lib/types.mjs

@@ -50,7 +50,7 @@ export const declarationsOf = (context, identifier) => {
   if (!tsNode) return []
   let symbol = checker.getSymbolAtLocation(tsNode)
   if (!symbol) return []
-  if (symbol.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol)
+  if ((symbol.flags & ts.SymbolFlags.Alias) !== 0) symbol = checker.getAliasedSymbol(symbol)
   return symbol.getDeclarations?.() ?? []
 }
 

package/lib/why.mjs

@@ -92,7 +92,7 @@ export const why = {
   "no-hardcoded-copy": {
     code: "FE_I18N_LITERAL",
     en: "The text `\"<text>\"` in `<file>:<line>` does not go through `t()`.",
-    fix: "Move the sentence into `modules/i18n/messages/<locale>.json` and read it with `t(\"key\")`; no exceptions and no `vn-ok`.",
+    fix: "Move the sentence into `modules/i18n/messages/<locale>.json` and read it with `t(\"key\")`; no exceptions.",
   },
   "no-raw-brand-value": {
     code: "FE_STYLE_TOKEN_ONLY",
@@ -127,7 +127,7 @@ export const why = {
   "no-inline-lint-config": {
     code: "HFS_INLINE_SUPPRESSION",
     en: "A comment disabling a rule sits at `<file>:<line>`. HFS does not allow in-place suppression - fix the code, or propose a rule change.",
-    fix: "Remove `eslint-disable`, `@ts-ignore`, `@ts-expect-error` or `vn-ok` and fix the cause.",
+    fix: "Remove `eslint-disable`, `@ts-ignore` or `@ts-expect-error` and fix the cause.",
   },
   "no-double-cast": {
     code: "FE_TYPE_ESCAPE",

package/lint-escape-hatch.mjs

@@ -7,7 +7,6 @@
  *
  *   eslint-disable / -next-line / -line / -enable / -env, and `/* eslint rule: "off" *\/`
  *   @ts-ignore, @ts-expect-error, @ts-nocheck
- *   vn-ok: <reason>   - the retired second-language pragma; it excuses nothing any more
  *   NOSONAR, @sonar-ignore                        - Sonar's own switches
  *   istanbul ignore, c8 ignore, v8 ignore         - a line taken out of the coverage the gate reads
  *   prettier-ignore                               - a region taken out of the formatter
@@ -46,14 +45,11 @@ const TS_DIRECTIVE = /^\s*(?:\/\s*)?@ts-(?:ignore|expect-error|nocheck)\b/
 const TOOL_DIRECTIVE =
   /\bNOSONAR\b|^\s*@sonar-ignore\b|^\s*(?:istanbul|c8|v8)\s+ignore\b|^\s*prettier-ignore(?:-start|-end)?\b|^\s*stylelint-(?:disable(?:-next-line|-line)?|enable)\b/i
 
-/** The retired second-language pragma. Present anywhere in a comment, it is a finding. */
-const RETIRED_PRAGMA = /\bvn-ok:/
-
 /** Inline lint configuration is repository policy, never a file-local choice. */
 export const noInlineLintConfig = {
   meta: {
     type: "problem",
-    docs: { description: "Source cannot change its own lint or type-check policy, and the vn-ok pragma is retired." },
+    docs: { description: "Source cannot change its own lint or type-check policy." },
     schema: [],
     messages: {
       directive:
@@ -62,8 +58,6 @@ export const noInlineLintConfig = {
         "A TypeScript suppression directive. It turns the compiler off for code that is failing the check for a reason. Fix the type, or change the shared contract that produced it; there is no local exception path.",
       tool:
         "A Sonar, coverage, formatter or stylelint suppression (`NOSONAR`, `@sonar-ignore`, `istanbul ignore`, `c8 ignore`, `prettier-ignore`, `stylelint-disable`). It removes this code from a gate that is failing it for a reason, and the next reader cannot tell a measured exception from an avoided fix. Fix the code, or change the shared rule or the coverage threshold; there is no local exception path.",
-      pragma:
-        "`vn-ok:` was the second-language escape hatch and it is retired: user-facing text comes from a `next-intl` catalogue through `t()`, and there is no comment that excuses a literal. Remove the pragma and move the string.",
     },
   },
   create(context) {
@@ -75,7 +69,6 @@ export const noInlineLintConfig = {
           if (ESLINT_DIRECTIVE.test(comment.value)) context.report({ node: comment, messageId: "directive" })
           else if (TS_DIRECTIVE.test(comment.value)) context.report({ node: comment, messageId: "typescript" })
           else if (TOOL_DIRECTIVE.test(comment.value)) context.report({ node: comment, messageId: "tool" })
-          else if (RETIRED_PRAGMA.test(comment.value)) context.report({ node: comment, messageId: "pragma" })
         }
       },
     }

package/next-conventions.mjs

@@ -28,15 +28,15 @@ export const noMiddlewareFile = {
     schema: [],
     messages: {
       file:
-        "`{{name}}` is the retired name of the request interceptor. Next 16 calls it `proxy.ts`: rename the file and export the handler as `proxy`.",
+        "`{{name}}` is not the request interceptor file: Next 16 reads `proxy.ts`. Rename the file and export the handler as `proxy`.",
       export:
-        "The handler in `proxy.ts` is exported as `middleware`, which is the retired name. Export it as `proxy`.",
+        "The handler in `proxy.ts` is exported as `middleware`, but Next 16 reads `proxy`. Export it as `proxy`.",
     },
   },
   create(context) {
     const file = fileOf(context)
-    // The retired name has a slot of its own (`fe.source-root-retired`, forbidden); the interceptor is the `proxy` role of `fe.source-root-pinned`.
-    if (inSlot(context, "fe.source-root-retired")) {
+    // `middleware.ts` has a slot of its own (`fe.source-root-middleware`, forbidden); the interceptor is the `proxy` role of `fe.source-root-pinned`.
+    if (inSlot(context, "fe.source-root-middleware")) {
       return { Program: (node) => context.report({ node, messageId: "file", data: { name: baseName(file) } }) }
     }
     if (!inSlot(context, "fe.source-root-pinned") || roleOfFile(context) !== "proxy") return {}

package/package.json

@@ -1,15 +1,16 @@
 {
   "name": "@starci/eslint-canon-fe",
-  "version": "8.0.9",
+  "version": "8.1.0",
   "description": "The StarCi front-end lint canon: every rule its laws publish, gathered as one flat-config plugin and attached by one factory.",
   "type": "module",
-  "license": "UNLICENSED",
+  "license": "MIT",
   "private": false,
   "exports": {
     ".": "./index.mjs"
   },
   "main": "./index.mjs",
   "files": [
+    "LICENSE",
     "*.mjs",
     "lib/*.mjs",
     "runtime/**",
@@ -42,6 +43,7 @@
     "canon"
   ],
   "dependencies": {
+    "@typescript-eslint/eslint-plugin": "^8.70.0",
     "@typescript-eslint/parser": "^8.70.0"
   }
 }

package/runtime/config.example.yaml

@@ -0,0 +1,187 @@
+# config.example.yaml — seed for the per-project owner config.
+# The installer copies this file to the gitignored `config.yaml` next to it;
+# owners edit that copy. Everything below is read at runtime — no key here is
+# decorative. Kernel route precedence: explicit `--agent` flag >
+# `kernel` below > the tier chain (modules/models/tiers.yaml).
+language: vi
+model: null
+effort: medium
+# Explicit current owner adoption is required; shipped defaults grant no trust or purge authority.
+# launchTrust: {profile: automatic, approvedBy: owner, approvalRef: '<current approval>', roots: ['<exact absolute repository root>']}
+# profile: declined preserves an explicit decision; provider-side declines also remain authoritative.
+launchTrust: null
+# retention: {workflowPurge: {approvedBy: owner, approvalRef: '<current approval>', repos: ['<exact absolute ledger-owner repo>']}}
+retention: null
+# kernel — the long-lived [Kernel] seat. It takes the `high` tier of modules/models/tiers.yaml (an ordered chain of
+# members; the picker takes the first member with tokens after your bias and the balance step; docs/config-format.md).
+# {agent?, model?, effort?}: agent and/or model PIN the seat — the bias `only`, keeping the tier's model of that agent
+# (an explicit `--agent` flag is the same bias and wins). effort: the seat's effort; null takes the tier member's effort.
+kernel: {effort: high}
+# parallel — the one knob for how wide the workers run. `gear` indexes the agent
+# table in modules/models/runtimes.yaml allocation.slicing.size: a long (`l`)
+# operation asks for the `l.agents[gear]` agents, an extra-long (`xl`) one for
+# `xl.agents[gear]`; `s` and `m` operations are always one agent. Declared gears
+# are allocation.slicing.gears — an undeclared value fails closed. Absent means
+# the first declared gear. A gear raises only what `starci kernel estimate` requests; it
+# never raises a pool's maxParallel, maxParallelOps or budgets.maxOps below.
+parallel: {gear: 1}
+# supervisor — the optional chat digest cadence. pollIntervalMs controls
+# scripts/supervisor/poll.mjs when run continuously (its floor is the config
+# validation of engine/config.mjs); null uses scripts/machine/home.mjs
+# DEFAULTS, and --interval-ms overrides this key.
+# The reconciler engine owns host runtime cadence and restores seats after reboot.
+# repos: managed product ledger-owner repositories for the reconciler and Supervisor tools,
+# relative to the source root (the directory holding this skill) or absolute.
+# --repo on the poll command line can add another. stallMinutes (optional,
+# integer >= 5) marks a running workflow STALLED in scripts/supervisor/stall.mjs;
+# the Workflow controller turns actionable findings into Decision Items. The [Supervisor]
+# kernel (docs/supervisor.md) also takes, optional, defaults in home.mjs DEFAULTS:
+#   kernel: {agent, model, effort}   its agent pin (default: the kernel pin below)
+#   workers: {base, max}             the adaptive [Worker] cap, 0 to 10 (0 = the Supervisor runs no fix worker)
+#   landGate: {mode: shared}         shared lets running lanes commit directly; exclusive = gate only. A land
+#                                    fast-forwards LOCAL main only: the remote main moves with a release (starci release cut)
+supervisor:
+  # mode: chat (default) - the owner's desktop chat session is the Supervisor: it owns channel 'main'
+  #   and reads Decision Items; nothing starts a [Supervisor] kernel. kernel - the optional [Supervisor]
+  #   Orca kernel (scripts/supervisor/start-supervisor.mjs), kept alive by the reconciler Host controller.
+  #   See docs/supervisor.md.
+  # mode: chat
+  pollIntervalMs: null
+  repos: []
+  # frozenMinutes: <n>   # Host seat check: a busy frame unchanged this long is frozen, not busy
+  # landGate: {mode: shared|exclusive}
+# delegation — while the owner is away, a named delegate (e.g. the supervisor chat) may
+# answer owner asks until the given time; excluded classes stay owner-only. null = none.
+#   delegation: {asks: supervisor, until: 2026-09-23T09:00:00+07:00,
+#     excludes: [credentials, oauth-consent, payments, legal, payment-provider]}
+delegation: null
+# budgets — the owner's ceiling, surfaced by every plan before `ok`. Null = unbounded.
+budgets:
+  maxOps: null       # max concurrent dispatched ops one workflow may hold open;
+                     # route/dispatch refuse `max-ops` at min(this, maxParallelOps)
+# allocation — the owner's default grant for a pool whose capacity is an explicit grant (Devin).
+#   grants: '<pool>=<slots>@<role>+<role>' — the default grant every workflow gets. Once a grants list is
+#     declared it is the whole set: a pool whose registry.yaml capacityAuthority is explicit-workflow-quota
+#     (Devin) routes only for the roles and up to the running slots a grant names ([] closes it).
+allocation:
+  grants: [devin-agent=10@implement+verify+write]
+# models — optional overrides of the shipped model tiers (modules/models/tiers.yaml owns the defaults). Every key is optional:
+#   tiers:   {<tier>: [{agent, model, effort?}, ...]}  replaces or adds one tier's ordered member chain
+#   seats:   {<seat>: <tier>}                          remaps a seat (supervisor, kernel, worker, planner, validator, kernelManager)
+#   balance: {maxStreak, maxSharePercent}              a head member picked maxStreak times in a row, or holding more than
+#                                                      maxSharePercent of the tier's running seats, yields to the next member
+#   usage:   {reservePercent, biasPercent}             a member at reservePercent of its tokens is skipped; an owner bias
+#                                                      naming it keeps it usable up to biasPercent; never above it
+models: {}
+# connectors — the owner's public ask channel (docs/connectors.md). Everything is off by default.
+# One local gateway (scripts/connectors/ask-gateway.mjs) fronts every serve-ask form; a Cloudflare
+# tunnel (scripts/connectors/tunnel.mjs) publishes the gateway; when serve-ask binds a form, the
+# kernel's ask path sends the owner one Telegram message (scripts/connectors/telegram.mjs) with the
+# question, its options and the public link. Telegram carries owner asks only.
+# SECRETS NEVER GO IN THIS FILE: tokenEnv/botTokenEnv NAME an environment variable holding the token
+# (or <NAME>_FILE pointing at a custody file); a value that is not an UPPER_SNAKE env var name is refused.
+#   Host credentials use the canonical runtime root secret.env; docs/host-secrets.md owns setup.
+#     Supplied environment values win, including blank values. Missing local file adds no values.
+#   repos: ledger-owner repository roots whose asks go public, relative to the source root (the
+#     directory holding this skill) or absolute. [] = the source root plus every .workspaces project owner.
+#   gateway.port: the one fixed local port the tunnel points at (outside the 6969..7069 form band).
+#   cloudflare.mode: off | quick | named.
+#     quick — `cloudflared tunnel --url`, a random https://*.trycloudflare.com host, no account, no auth,
+#       a new host on every restart. Good for decisions only.
+#     named — a fixed `hostname`, authenticated one of two ways: `tunnel` (UUID) + `credentialsFile`
+#       (the JSON `cloudflared tunnel create` wrote; the manager writes its own ingress config mapping
+#       hostname -> the gateway and never reads ~/.cloudflared/config.yml), or a remotely managed tunnel
+#       token in `tokenEnv` (its public hostname is routed to http://127.0.0.1:<gateway.port> in the
+#       Cloudflare dashboard).
+#   cloudflare.access: whether a Cloudflare Access application guards `hostname` (informational; false
+#     prints a warning). Recommended for anything beyond yes/no decisions.
+#   telegram.enabled / chatId: the owner's chat with the bot (BotFather token in botTokenEnv). Send the
+#     bot /start, then `starci connect telegram discover-chat` prints the chat id.
+#   telegram.exposeCredentialAsks: false keeps a credential/secret ask off the public link — the message
+#     says to answer it on this machine and carries only the localhost link, and the gateway refuses it.
+connectors:
+  repos: []
+  gateway: {port: 7070}
+  cloudflare: {mode: off, tunnel: null, credentialsFile: null, tokenEnv: CLOUDFLARE_TUNNEL_TOKEN, hostname: null, access: false}
+  telegram:
+    enabled: false
+    botTokenEnv: TELEGRAM_BOT_TOKEN
+    chatId: null
+    exposeCredentialAsks: false
+# asks — owner asks that carry a recommended option (question.recommended, or exactly one option
+# marked "(recommended)" or its Vietnamese equivalents). autoAcceptRecommended: true answers such an
+# ask with its recommendation instead of serving the form: the ledger records ask-answered with
+# answeredBy auto-recommended, the kernel is woken, and Telegram gets one plain message naming the
+# pick. A later owner answer supersedes it. excludes lists the ask classes that always reach the owner:
+#   credential — any ask with secret fields, or of kind credential, account, access or consent;
+#   handover — every handover.review ask (always excluded, even when removed from this list);
+#   draw-review — the opt-out for drawings (interface.draw, scripts/work/draw-review.mjs): unlisted, a
+#     drawing the owner did not ask to review is accepted without the owner (its accept option is the
+#     recommendation); a drawing the owner asked for (a prior owner redraw of the record, the owner
+#     opened its form, or question.ownerRequested) always reaches the owner;
+#   or any ask kind: information, authority, business-decision, irreversible-confirmation, ...
+asks:
+  autoAcceptRecommended: false
+  excludes: [credential, irreversible-confirmation, handover]
+# uat — the machine-wide UAT ceiling. At most maxConcurrent UAT runs (a browser session, a player, the
+# app it drives) execute at once on this host, across every workflow; the rest wait queued for a slot
+# (scripts/uat/uat-slots.mjs, lock files under <runtime>/uat-slots). A slot whose holder died is
+# reclaimed. STARCI_UAT_MAX_CONCURRENT overrides it for one process tree.
+uat:
+  maxConcurrent: 10
+# orca — the owner's Orca app settings the runtime must know (engine/orca-config.mjs orcaSettings). maxWorkerDepth MUST equal
+# the worker depth set in the Orca app: the deepest worker Orca starts under the owner's chat (chat 0, Kernel or
+# Supervisor 1, op or [Worker] 2, draw critic 3). Orca exposes no read of it, so the runtime trusts this value and refuses
+# a deeper launch before worker-start (worker-depth-exceeded). `start --check` with STARCI_ORCA_LIVE=1 measures Orca's
+# real limit and turns red when the two differ.
+orca:
+  maxWorkerDepth: 4
+# debugLoop — the debug watcher. Workflow DEBUG is a /loop of the chat that started the workflow (the /starci skill sets it up in
+# Claude Code and Codex; no seat, no background agent, nothing in the runtime schedules it). Each tick runs the read-only
+# `starci debug digest`. interval is the loop cadence (<n>s | <n>m | <n>h, default `10m` = `debugLoop.interval`); worktreeLimit is the
+# per-repository core-watch alert threshold (default `40` = `debugLoop.worktreeLimit`). Both keys are optional (engine/config.mjs DEBUG_LOOP_DEFAULTS).
+debugLoop:
+  interval: 10m
+  worktreeLimit: 40
+# reconciler — the host's one reconciler engine (scripts/reconciler/engine.mjs; contract
+# modules/reconciler/reconciler.yaml). Each controller runs off | shadow (reads, records what it would do as
+# reconciler.would rows, runs nothing) | active (acts; the old loop yields that duty via scripts/reconciler/owns.mjs).
+# profile — the operational default of every controller, so a host is never left all-shadow by accident:
+#   operational  job, host, workflow, resource active (they settle jobs, start services and seats, wake stalled
+#                workflows, throttle); gc, workers, learning shadow. The `start` skill applies and checks it.
+#   observe      every controller shadow (read-only; a debugging or audit host).
+#   (absent)     only the explicit controllers.<name>.mode entries count; an unnamed controller is off.
+# controllers.<name>.mode overrides the profile for that one controller (e.g. gc: {mode: active}).
+# Rollback of a controller: set its mode to off (the old loops take the duty back within
+# allocation.reconciler.heartbeatStaleMs). Numbers: modules/models/runtimes.yaml allocation.reconciler.
+reconciler:
+  enabled: true
+  profile: operational
+  controllers: {}
+# specs.unit / specs.e2e in workflows (the `specs` map near the top; owner 2026-09-28 "speed up development;
+# test later when asked"; scripts/route/spec-deferral.mjs). Each op brief's policy.specsToggle says what it does:
+#   unit: false - backend.implement, interface.implement and code.refactor run no jest/vitest/test:ci/coverage
+#     and demand no changed-line coverage (Sonar still runs: bugs, smells, security gate);
+#     test.author legs are never dispatched; review/handover gates do not count unit tests or coverage.
+#   e2e: false - e2e.verify legs and e2e test authoring are never dispatched; uat.verify is not e2e.
+#   A leg that is not dispatched settles `deferred: specs.<class>=false` with no attempt spent and the workflow
+#   proceeds past it; starci kernel status lists testsDeferred and `starci kernel run-deferred-tests --workflow <id> [--kind unit|e2e]`
+#   runs them later. Read on every wake: flipping a switch needs no restart.
+# roots — where this host keeps the archive, the lane worktrees and its temporary files, when the owner moves them off the defaults.
+# All keys are optional absolute directories; env STARCI_ARCHIVE_ROOT / STARCI_LANES_ROOT / STARCI_TEMP_ROOT win over them, and an
+# absent key means <starciLocalRoot>/archive (<runtime root>/.runtime/archive), the per-user profile lanes directory, kept out of the checkout (scripts/machine/home.mjs lanesRoot),
+# and the OS temp directory (engine/temp-root.mjs tempRoot; the processes the runtime starts get it as TEMP/TMP/TMPDIR). No host location lives in
+# a tracked file: set the real directories only in the gitignored config.yaml copy, e.g.
+#   roots: {archive: <absolute directory>, lanes: <absolute directory>, temp: <absolute directory>}
+# sonar — the SonarCloud organization the release's Sonar proof of the example apps analyses in (scripts/supervisor/release-sonarcloud.mjs). It is configuration, not a secret,
+# so it lives here and not in secret.env; the project keys are <organization>_starci-example-<app>. The environment variable SONAR_ORGANIZATION wins over it (CI reads the
+# repository variable of the same name). Empty until the owner sets it in the gitignored config.yaml copy, e.g.
+#   sonar: {organization: <the organization key shown on sonarcloud.io>}
+sonar: {organization: null}
+# resources — the host capacity floors the dispatch gate enforces, over the shipped numbers of modules/models/runtimes.yaml allocation.resources
+# (scripts/machine/host-resources.mjs; docs/config-format.md "Host resource floors"). Every key is optional (a number above 0, or null):
+#   minFreeDiskGb  free GB a drive holding the temp root or the repository must keep
+#   minFreeDiskPct the same floor as a percentage of the drive's size; with minFreeDiskGb the larger requirement applies
+#   minFreeRamPct  free-RAM percentage below which no new heavy op starts
+# set them only in the gitignored config.yaml copy, e.g.
+#   resources: {minFreeDiskGb: 5, minFreeDiskPct: 1, minFreeRamPct: 10}

package/runtime/engine/by-code-unit.mjs

@@ -0,0 +1,12 @@
+// by-code-unit.mjs - the comparator of a bare `Array.prototype.sort()`, owned beside the engine files that digest and canonicalize (scripts/lib/list.mjs re-exports it).
+
+/**
+ * The comparator of a bare `Array.prototype.sort()`: values compared as strings by UTF-16 code unit. Pass it to `sort` and
+ * `toSorted` so the order is stated, and stays byte-identical to the default order that digests and canonical output depend on.
+ */
+export const byCodeUnit = (a, b) => {
+  const left = String(a);
+  const right = String(b);
+  if (left < right) return -1;
+  return left > right ? 1 : 0;
+};