@starci/hfs 4.9.2 → 4.9.4

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 4.9.4 - 2026-10-28
+
+- Added: the bundled rule catalog carries R323 (`FE_PAGE_HEADER_HAND_ROLLED`, enforced by `@starci/eslint-grammar-core` `no-hand-rolled-page-header`) and its failure-code guidance.
+- Changed: the bundled canon pins follow release F (Grammar family 0.15.3, hfs 4.9.4, canon-fe 9.4.3, canon-be 3.6.3, ai-router 0.3.0).
+
+## 4.9.3 - 2026-10-28
+
+- Changed: the bundled canon pins no longer pin the command line. An app's `starci-harness` is judged and scaffolded at the version of the CLI that runs this package: `main(argv, { harness: { version } })` takes it, and `runtime/scripts/hfs/canon-pins.mjs` (`canonPins`, the one reader of `knowledge/hfs/canon-pins.yaml`) adds the `starci-harness` row from it for HFS_CANON_PIN_DRIFT, HFS_CI_MISSING_CANON and the scaffold's root devDependencies. The CLI depends on this package exactly, so a bundled pin of the CLI tied every CLI release to a new hfs and back. Run without a CLI, nothing judges the app's `starci-harness` and `scaffoldApp` refuses HFS_SCAFFOLD_PIN_MISSING before `git init`. Spec: `src/canon-pins.spec.mjs` (also: every `source:` pin at its folder's version, the five runtime copies byte-identical, `contexts/stack/pins.yaml` in step).
+- Changed: the bundled canon pins follow release E (Grammar family 0.15.2, hfs 4.9.3, canon-fe 9.4.2, canon-be 3.6.2, ai-router 0.3.0).
+
 ## 4.9.2 - 2026-10-28
 
 - Fixed: `repositoryName` (runtime/scripts/hfs/repo-identity.mjs) names a repository by its origin remote, whatever folder holds the clone; the main checkout's folder names it only without an origin. HFS_README_TITLE_INVALID and the stack project name no longer change with the clone folder. Spec: `src/repo-identity.spec.mjs`.

package/README.md

@@ -1,6 +1,6 @@
 # @starci/hfs
 
-The HFS command line of a StarCi app: the one repository of a product, `<app>/` with its root (the `app.*` slots: the one `package.json`, lockfile and `node_modules`, the `hfs.json` declaration of kind `app`, CI, hooks, the `app.starciwork` work area) and its two sides `be/` and `fe/` (slot `app.sides`). It is installed from the npm registry at the exact version in `knowledge/hfs/canon-pins.yaml` (see [`packages/README.md`](../README.md)),
+The HFS command line of a StarCi app: the one repository of a product, `<app>/` with its root (the `app.*` slots: the one `package.json`, lockfile and `node_modules`, the `hfs.json` declaration of kind `app`, CI, hooks, the `app.starciwork` work area) and its two sides `be/` and `fe/` (slot `app.sides`). It is installed from the npm registry as the exact dependency of the CLI that runs it in-process, `starci-harness` (see [`packages/README.md`](../README.md)), which passes `main` its own version as `harness`,
 and it is self-contained: `runtime/` carries the slot manifest, the canon pins, the Vietnamese why
 catalog slice, the loader and the architecture machine with every file it imports, so it runs where there is no runtime
 checkout. The machine loads `typescript` from the app it checks (never its own copy), so run `npm ci` first.
@@ -98,7 +98,7 @@ Its own checks (`scripts/hfs/check.mjs`, `scripts/hfs/rules/`; the rendered-file
 | `HFS_STARCIWORK_LITE_FORBIDDEN` | error | content outside the lite `app.starciwork` boundary: "lite .starciwork holds only workspace.yaml and brand/ (plus .gitignore)" (R212) |
 | `HFS_SLOT_REQUIRED_MISSING` | error | a file or directory a required slot, app or instance must contain |
 | `HFS_MIN_INSTANCES` | error | fewer instances of a slot than `minInstances` |
-| `HFS_CANON_PIN_DRIFT` | error | a dependency not at the exact version of `knowledge/hfs/canon-pins.yaml` |
+| `HFS_CANON_PIN_DRIFT` | error | a dependency not at the exact version of `knowledge/hfs/canon-pins.yaml`, or `starci-harness` not at the version of the CLI that runs the check (`runtime/scripts/hfs/canon-pins.mjs`) |
 | `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 managed factory render, so a rule could be off, warned or redefined in it |

package/emit/db-types.mjs

@@ -16,7 +16,7 @@ import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { parse as parseToml } from 'smol-toml';
-import { parseYaml } from '../runtime/engine/yaml.mjs';
+import { bundledPins } from '../runtime/scripts/hfs/canon-pins.mjs';
 
 /** The repository-relative path of the generated types (the path of slot `app.supabase.types`). */
 export const dbTypesPath = 'supabase/types/database.types.ts';
@@ -56,7 +56,6 @@ class DbTypesError extends Error {
 }
 
 const spawn = (file, args, options = {}) => spawnSync(file, args, { encoding: 'utf8', windowsHide: true, maxBuffer: 64 * 1024 * 1024, ...options });
-const PINS_FILE = new URL('../runtime/knowledge/hfs/canon-pins.yaml', import.meta.url);
 
 /**
  * The one spawn: an argument array, a hidden window, a bound buffer, never a shell. Specs inject a fake of the same shape. The
@@ -65,7 +64,7 @@ const PINS_FILE = new URL('../runtime/knowledge/hfs/canon-pins.yaml', import.met
 const withNpxFallback = (run, platform) => (file, args, options = {}) => {
   const first = run(file, args, options);
   if (file !== SUPABASE_CLI || first.error?.code !== 'ENOENT') return first;
-  const version = parseYaml(fs.readFileSync(PINS_FILE, 'utf8'))?.pins?.[SUPABASE_CLI]?.version;
+  const version = bundledPins()[SUPABASE_CLI]?.version;
   if (!version) return first;
   return platform === 'win32'
     ? run('cmd.exe', ['/d', '/s', '/c', 'npx', '--yes', `${SUPABASE_CLI}@${version}`, ...args], options)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starci/hfs",
-  "version": "4.9.2",
+  "version": "4.9.4",
   "description": "The StarCi app command implementation for scaffolding, linting, checking and synchronizing one product repository.",
   "type": "module",
   "license": "MIT",

package/runtime/knowledge/hfs/canon-pins.yaml

@@ -1,7 +1,8 @@
 schema: starci/canon-pins@1
 purpose: >-
   The exact version of every shared dependency in the StarCi family, including package-owned runtime dependencies. One version per dependency for the whole
-  family. Raising a version is a change to this file first (with the package bump when it is a @starci package),
+  family. The command line itself is not pinned here: an app's starci-harness is the version of the CLI that runs @starci/hfs to
+  judge or scaffold it (scripts/hfs/canon-pins.mjs), since that CLI depends on this package exactly. Raising a version is a change to this file first (with the package bump when it is a @starci package),
   then the repositories' own upgrade lane (each sets the exact version and reinstalls; nothing else installs a @starci package). Read on 2026-09-29 from the packages under
   .claude/packages and from the installed node_modules of the six product repositories; where they disagreed the
   newest version installed in more than one repository won, and the runtime's own version won for @starci packages.
@@ -30,35 +31,35 @@ pins:
     source: packages/event-stream/package.json
     why: 'the one server-sent-events client of every front end (fe-stack event-stream, owner:event-stream-package): the transport client layer (modules/api/sse/clients) creates one instance for the app with the bearer token source and the stream operations follow on it; it carries Last-Event-ID resume, the capped doubling backoff, the heartbeat timeout, the single 401 renewal and the useSWRSubscription adapter, so no app keeps a hand-written reader.'
   '@starci/grammar':
-    version: 0.15.1
+    version: 0.15.3
     group: starci
     install: registry
     side: fe
     source: packages/grammar/package.json
     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.'
   '@starci/eslint-canon-be':
-    version: 3.6.1
+    version: 3.6.3
     group: starci
     install: registry
     side: be
     source: packages/eslint-canon-be/package.json
     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.'
   '@starci/eslint-canon-fe':
-    version: 9.4.1
+    version: 9.4.3
     group: starci
     install: registry
     side: fe
     source: packages/eslint-canon-fe/package.json
     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.'
   '@starci/eslint-grammar-core':
-    version: 0.15.1
+    version: 0.15.3
     group: starci
     install: registry
     side: fe
     source: packages/eslint-grammar-core/package.json
     why: 'the StarCi Grammar component API lint, versioned with @starci/grammar; front ends compose this family package with the universal FE canon.'
   '@starci/eslint-grammar-offset-pop':
-    version: 0.15.1
+    version: 0.15.3
     group: starci
     install: registry
     side: fe
@@ -98,21 +99,14 @@ pins:
     source: packages/test-world/package.json
     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.'
   '@starci/ai-router':
-    version: 0.2.1
+    version: 0.3.0
     group: starci
     install: registry
     side: be
     source: packages/ai-router/package.json
     why: 'the AI pool router of a back end: a NestJS module that routes OpenAI-compatible chat, stream and embeddings calls across keys, models and providers, with @starci/ai-router/testing for its specs; @starci/jest-preset compiles it as an ESM-only dependency.'
-  'starci-harness':
-    version: 1.1.0-alpha.2
-    group: starci
-    install: registry
-    side: both
-    source: cli/package.json
-    why: 'the one StarCi command line (bins starci and starci-harness): a product repository installs it for starci app, which it runs in-process through its exact @starci/hfs dependency, and its codegen loads starci-harness/input-bounds.'
   '@starci/hfs':
-    version: 4.9.2
+    version: 4.9.4
     group: starci
     install: registry
     side: both

package/runtime/knowledge/hfs/rules.yaml

@@ -5687,3 +5687,26 @@ rules:
         source: owner
         quote: "A chip label starts uppercase."
         ruling: "The label of a status chip starts with an uppercase letter (owner ruling chip-label-uppercase); StatusDot capitalises a text label it renders, and the lint refuses a lowercase literal label at its source."
+  - id: R323
+    code: "FE_PAGE_HEADER_HAND_ROLLED"
+    law: "A page is headed by Grammar's PageHeader; a Breadcrumbs trail followed by a SectionHeader in one parent is a page head composed by hand, with no band, no top inset and no separator."
+    kinds: [lint]
+    gates: [pre-commit, settle, land, ci]
+    failureCodes: ["FE_PAGE_HEADER_HAND_ROLLED"]
+    enforcers:
+      - {kind: eslint-grammar-core, id: no-hand-rolled-page-header}
+    editions: [lite, full]
+    docs: [knowledge/patterns/fe/index.yaml#FE-RULE-OWNERSHIP]
+    templateNa: "A template states no page head; the pages are the app's."
+    proves:
+      - packages/eslint-grammar-core/src/page-header.spec.ts
+    exemplifiedBy:
+      - {path: packages/eslint-grammar-core/src/page-header.spec.ts, editions: [lite, full], codes: [FE_PAGE_HEADER_HAND_ROLLED]}
+    witness:
+      - {path: packages/eslint-grammar-core/src/page-header.spec.ts, editions: [lite, full], codes: [FE_PAGE_HEADER_HAND_ROLLED]}
+    cases:
+      - id: case-1
+        date: "2026-10-28"
+        source: owner
+        quote: "Publish Grammar 0.15.3 with PageHeader now, then move all 18 pages to it before deploying. (translated from Vietnamese)"
+        ruling: "A page is headed by Grammar's PageHeader (owner ruling page-header-band): a surface band whose content shares the page content's edges and which ends in its own full-width separator, page tabs standing on it; the lint refuses a page head composed by hand from Breadcrumbs and SectionHeader."

package/runtime/modules/kernel/failure-codes.yaml

@@ -2714,6 +2714,16 @@ FE_PACKAGE_SHAPE:
   owner: op-retry
   kind: check-finding
 
+FE_PAGE_HEADER_HAND_ROLLED:
+  title: "A page head is composed by hand instead of PageHeader"
+  title_vi: "Phần đầu trang được ghép tay thay vì dùng PageHeader"
+  meaning_vi: "Tại <file>, một Breadcrumbs theo sau là một SectionHeader trong cùng một phần tử cha: phần đầu trang ghép tay không có dải nền, không có khoảng đệm trên và không có đường phân cách, nên mỗi trang tự quyết khoảng cách riêng."
+  causes_vi:
+    - "Đặt Breadcrumbs rồi SectionHeader level={1} ở đầu trang hoặc layout."
+  nextStep_vi: "Dùng PageHeader của Grammar với breadcrumbs, title và các khe cần thiết (description, meta, status, mark, actions, tabs) (quy định page-header-band)."
+  owner: op-retry
+  kind: check-finding
+
 FE_PAGE_METADATA_MISSING:
   title: "Every page exports metadata"
   title_vi: "Trang không khai báo metadata"

package/runtime/scripts/hfs/canon-pins.mjs

@@ -0,0 +1,27 @@
+// canon-pins.mjs - the pins an app is judged and scaffolded against. knowledge/hfs/canon-pins.yaml pins every shared dependency
+// but the command line itself: the `starci-harness` row is the version of the CLI that runs this @starci/hfs (it passes its own
+// version to main as `harness`), never a bundled row, since the CLI depends on this package exactly and a bundled pin of the CLI
+// would make each release of one need a release of the other. Run without a CLI (the package's own specs and diagnostics), there
+// is no such row: nothing judges the app's starci-harness, and the scaffold, which needs it, refuses.
+import fs from 'node:fs';
+import path from 'node:path';
+import { skillRoot } from '../../engine/runtime-root.mjs';
+import { parseYaml } from '../../engine/yaml.mjs';
+
+/** The runtime-relative file of the bundled pins. */
+export const CANON_PINS_FILE = 'knowledge/hfs/canon-pins.yaml';
+/** The npm name of the command line that runs @starci/hfs, pinned at its own version. */
+export const HARNESS_PACKAGE = 'starci-harness';
+
+/** The pin map of knowledge/hfs/canon-pins.yaml under `root` (the bundled runtime by default). */
+export const bundledPins = (root = skillRoot) => parseYaml(fs.readFileSync(path.join(root, CANON_PINS_FILE), 'utf8'))?.pins ?? {};
+
+/**
+ * The pin map an app answers to: the bundled pins plus the `starci-harness` row at `harness.version`, the version of the CLI that
+ * runs this package; without `harness` the bundled pins alone.
+ */
+export function canonPins({ root = skillRoot, harness } = {}) {
+  const pins = bundledPins(root);
+  if (harness?.version === undefined) return pins;
+  return { ...pins, [HARNESS_PACKAGE]: { version: harness.version, group: 'starci', install: 'registry', side: 'both' } };
+}

package/runtime/scripts/hfs/check.mjs

@@ -1,6 +1,7 @@
 // hfs-check.mjs - the HFS app check, behind `starci app check | explain` (packages/hfs) and reusable by any
 // runtime check. It reads three things and nothing else: the app's hfs.json, the slot manifest
-// (knowledge/hfs/slots.yaml through scripts/hfs/slots.mjs) and the pins (knowledge/hfs/canon-pins.yaml). It never
+// (knowledge/hfs/slots.yaml through scripts/hfs/slots.mjs) and the pins (canon-pins.mjs: the bundled knowledge/hfs/canon-pins.yaml
+// and the version of the starci-harness that runs the check). It never
 // writes to the repository it inspects.
 //
 // checkRepo() answers, for the tracked paths of one app (git ls-files), per scope (the app root and each side folder):
@@ -64,7 +65,7 @@ import { appWiring, BOOT_PROOF_CODE } from './app-wiring.mjs';
 import { coverageFrom as coverageFromReport } from './coverage-from.mjs';
 import { skillRoot } from '../../engine/runtime-root.mjs';
 import { ARCHITECTURE_RULE_IDS, checkArchitecture } from './architecture/index.mjs';
-import { parseYaml } from '../../engine/yaml.mjs';
+import { canonPins } from './canon-pins.mjs';
 import { readCatalogOnce } from './catalog-once.mjs';
 import { APP_SCOPE, HFS_DECLARATION_FILE, appRelativeMessages, HfsSlotsError, SIDES, createSlotResolver, loadSlotManifest, readRepoDeclaration, resolveRepoDeclaration } from './slots.mjs';
 import { judgedFindings, summarize, withWhy } from './check-results.mjs';
@@ -101,7 +102,6 @@ export { REFUSAL_CODES } from './refusal-codes.mjs';
 // The database rules (R213-R216) read SQL through a WASM parser, so they are async: `starci app check` calls them beside the other emitters and passes the findings in as `extraFindings`.
 export { checkDatabase } from './rules/database.mjs';
 
-const CANON_PINS_FILE = 'knowledge/hfs/canon-pins.yaml';
 export const FAILURE_CODES_FILE = 'modules/kernel/failure-codes.yaml';
 /** The codes this module emits that are not the slot loader's own: the why bundle of packages/hfs ships exactly these plus the loader's. */
 export const CHECK_CODES = Object.freeze([
@@ -151,9 +151,6 @@ export function trackedFiles(repoRoot) {
 
 const fill = (text, bindings) => String(text).replace(VAR, (whole, name) => bindings[name] ?? whole);
 
-/** The pin map of knowledge/hfs/canon-pins.yaml under `root`. */
-const readPins = (root) => parseYaml(fs.readFileSync(path.join(root, CANON_PINS_FILE), 'utf8'))?.pins ?? {};
-
 /** Instances (slot, root, bindings) present in the tracked tree, for every slot that names required files or a minimum. */
 function instancesOf(resolver, files) {
   const found = new Map();
@@ -252,7 +249,7 @@ function sizeSoftFindings({ repoRoot, resolver, files, inScope }) {
  * relative to it, exactly as the standalone repository root was). `files` are the scope's tracked paths; `all` (root only) every
  * tracked path of the app, for the rules that read across it (dependency skew, proof commands).
  */
-function scopeFindings({ repoRoot, root, repo, resolver, files, all = files, scoped, manifest, appSide = false, editionDeclaration = true, phase }) {
+function scopeFindings({ repoRoot, root, harness, repo, resolver, files, all = files, scoped, manifest, appSide = false, editionDeclaration = true, phase }) {
   const inScope = (file) => !scoped || scoped.has(file);
   // A required directory of the root (be/, fe/) is present through the files below it, which are the sides' own.
   const trackedSet = new Set(all);
@@ -265,14 +262,15 @@ function scopeFindings({ repoRoot, root, repo, resolver, files, all = files, sco
   // The runtime repository (kind runtime) is judged here by its tree law only; its own rules run in scripts/hfs/runtime-check.mjs.
   if (repo.kind === RUNTIME_KIND) return findings;
 
-  const pins = readPins(root);
+  const pins = canonPins({ root, harness });
   findings.push(...contentRuleFindings({ repoRoot, repo, resolver, files, all, scoped, pins, inScope, isRoot, appSide, editionDeclaration, manifest, phase }));
   if (!isRoot) findings.push(...sizeSoftFindings({ repoRoot, resolver, files, inScope }));
   return findings;
 }
 
 /**
- * The check of one app. `repoRoot` is the app root (a side folder is checked as that side alone). `declaration` overrides hfs.json
+ * The check of one app. `repoRoot` is the app root (a side folder is checked as that side alone). `harness` ({ version }) is the CLI
+ * that runs the check, whose version is the app's starci-harness pin (canon-pins.mjs). `declaration` overrides hfs.json
  * (a dry run over an app that has none); `files` overrides git ls-files (specs), app-relative. `only` (a list of app-relative paths)
  * limits the per-path checks (slot, pin, size) to those paths; the checks of the tree as a whole (required files, minimum instances,
  * empty directories, untracked entries) are not per-path. `tree: false` skips the file-system checks (empty directories, ghosts,
@@ -284,7 +282,7 @@ function scopeFindings({ repoRoot, root, repo, resolver, files, all = files, sco
  * `phase: 'source'` is the runtime's no-install example-render pass: tracked obligations still run, while ignored generated
  * artifact presence/freshness belongs to the default `workspace` phase after codegen. Ordinary app check/lint always use it.
  */
-export function checkRepo({ repoRoot, root = skillRoot, declaration, files, only, extraFindings = [], tree = files === undefined, manifest = loadSlotManifest({ root }), surface = 'all', phase = 'workspace' }) {
+export function checkRepo({ repoRoot, root = skillRoot, harness, declaration, files, only, extraFindings = [], tree = files === undefined, manifest = loadSlotManifest({ root }), surface = 'all', phase = 'workspace' }) {
   if (!['source', 'workspace'].includes(phase)) throw new Error(`unknown HFS inspection phase ${phase}`);
   const why = readWhy(root);
   let repo;
@@ -303,18 +301,18 @@ export function checkRepo({ repoRoot, root = skillRoot, declaration, files, only
   const keep = (list, scopeRoot) => (surface === 'check' ? list.filter((finding) => !(finding.origin === 'repo' && onLintSurface(scopeRoot, finding))) : list);
   if (repo.profile === APP_SCOPE) {
     const own = tracked.filter((file) => resolver.sideOf(file) === null);
-    findings.push(...keep(scopeFindings({ repoRoot, root, repo, resolver, files: own, all: tracked, scoped, manifest, phase }), repoRoot));
+    findings.push(...keep(scopeFindings({ repoRoot, root, harness, repo, resolver, files: own, all: tracked, scoped, manifest, phase }), repoRoot));
     for (const side of SIDES) {
       const prefix = `${side}/`;
       const sideRoot = path.join(repoRoot, side);
       const sideFiles = tracked.filter((file) => file.startsWith(prefix)).map((file) => file.slice(prefix.length));
       const sideScoped = scoped ? new Set([...scoped].filter((file) => file.startsWith(prefix)).map((file) => file.slice(prefix.length))) : null;
-      const sideFindings = scopeFindings({ repoRoot: sideRoot, root, repo: repo.sides[side], resolver: resolver.sides[side], files: sideFiles, scoped: sideScoped, manifest, appSide: true, editionDeclaration: false, phase });
+      const sideFindings = scopeFindings({ repoRoot: sideRoot, root, harness, repo: repo.sides[side], resolver: resolver.sides[side], files: sideFiles, scoped: sideScoped, manifest, appSide: true, editionDeclaration: false, phase });
       const message = appRelativeMessages(side, sideRoot);
       findings.push(...keep(sideFindings, sideRoot).map((finding) => ({ ...finding, side, path: onSide(side, finding.path), message: message(finding.message) })));
     }
   } else {
-    findings.push(...keep(scopeFindings({ repoRoot, root, repo, resolver, files: tracked, scoped, manifest, phase }), repoRoot));
+    findings.push(...keep(scopeFindings({ repoRoot, root, harness, repo, resolver, files: tracked, scoped, manifest, phase }), repoRoot));
   }
   findings.push(...extraFindings);
   const untrackedSecrets = untrackedSecretFindings({ repoRoot, files: tracked, repo });
@@ -367,9 +365,9 @@ function machineFindings(report) {
  * templates or run the formatter (packages/hfs/sync), judged with checkRepo's own. `machine` is injectable for specs. A missing
  * merge-base under `fast` is an Error, never a silent full pass. `repoRoot` may also be a side folder: that side alone is checked.
  */
-export function checkRepository({ repoRoot, root = skillRoot, fast = false, base, extraFindings = [], manifest = loadSlotManifest({ root }), machine = checkArchitecture, wiring = false, coverageFrom }) {
+export function checkRepository({ repoRoot, root = skillRoot, harness, fast = false, base, extraFindings = [], manifest = loadSlotManifest({ root }), machine = checkArchitecture, wiring = false, coverageFrom }) {
   const changed = fast ? changedSince(repoRoot, base) : null;
-  const slotResult = checkRepo({ repoRoot, root, manifest, extraFindings, surface: 'check', ...(changed ? { only: changed.files, tree: false } : {}) });
+  const slotResult = checkRepo({ repoRoot, root, harness, manifest, extraFindings, surface: 'check', ...(changed ? { only: changed.files, tree: false } : {}) });
   if (slotResult.profile === null) return { ...slotResult, machine: { status: 'skipped', reason: 'hfs.json is not valid' } };
   const repo = readRepoDeclaration(manifest, repoRoot);
   const scopes = repo.profile === APP_SCOPE

package/runtime/scripts/hfs/rules/pipeline.mjs

@@ -1,8 +1,8 @@
 // pipeline.mjs - HFS_CI_MISSING_CANON (R13): CI runs the pinned `starci app lint`.
 //   .github/workflows/ci.yml   a `run:` step that runs the one lint entry: `starci app lint`,
 //                              `npx starci-harness[@<version>] app lint`, or `npm run <script>` whose command runs `starci app lint`
-//                              (`npm run lint`, arguments after `--` allowed); a version named in the step is the starci-harness pin of
-//                              canon-pins.yaml (an installed one is pinned by the pin check, R15)
+//                              (`npm run lint`, arguments after `--` allowed); a version named in the step is the starci-harness pin,
+//                              the version of the CLI that runs the check (canon-pins.mjs; an installed one is pinned by the pin check, R15)
 //   (the push hook is no lint or typecheck step: it checks the release gate, scripts/hfs/runtime-rules/hook-shape.mjs keeps its shape)
 // A missing file is the slot manifest's finding (HFS_SLOT_REQUIRED_MISSING); a file that is present and lacks the step is this rule's.
 // The redirect of `core.hooksPath` away from husky is the architecture machine's (HFS_HOOKS_PATH_REDIRECTED).
@@ -77,7 +77,7 @@ function expanded(command, scripts) {
 /** Only the bundled example runner with its fixed current-app arguments delegates to the following argv. */
 const exampleCommandOf = (command) => command.startsWith(EXAMPLE_RUN_PREFIX) ? command.slice(EXAMPLE_RUN_PREFIX.length) : command;
 
-/** The findings of R13 over the repository at `repoRoot`; `pins` is the parsed canon-pins.yaml pin map. */
+/** The findings of R13 over the repository at `repoRoot`; `pins` is the canon pin map (canon-pins.mjs). */
 export function pipelineFindings({ repoRoot, files, pins }) {
   const findings = [];
   const pinned = pins?.[hfsPackage]?.version;

package/scaffold/add-app.mjs

@@ -7,7 +7,8 @@ import {
 } from "../runtime/scripts/hfs/slots.mjs";
 import { imageFiles, render, TEMPLATES_DIR } from "../sync/index.mjs";
 import { ScaffoldError, pascalOf } from "./service.mjs";
-import { PARTIAL_VARIABLES, bundledPins, callbackSourceFiles, coreFeApps, hasAuthCallback, jsonText, packageJsonText } from "./app.mjs";
+import { bundledPins } from "../runtime/scripts/hfs/canon-pins.mjs";
+import { PARTIAL_VARIABLES, callbackSourceFiles, coreFeApps, hasAuthCallback, jsonText, packageJsonText } from "./app.mjs";
 
 /** The shared fe app core (modules/api, auth, toast, redux, the providers, the hooks): the base tree, then the edition overlay. */
 const CORE_DIRS = Object.freeze({

package/scaffold/add-cli-lite.mjs

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { resolveRepoDeclaration } from "../runtime/scripts/hfs/slots.mjs";
-import { parseYaml } from "../runtime/engine/yaml.mjs";
+import { bundledPins } from "../runtime/scripts/hfs/canon-pins.mjs";
 import { appScripts, appSource, imageFiles, TEMPLATES_DIR } from "../sync/index.mjs";
 import { ScaffoldError } from "./service.mjs";
 import { jsonText, packageJsonText } from "./app.mjs";
@@ -12,7 +12,6 @@ const read = (relative) =>
   fs
     .readFileSync(path.join(TEMPLATES_DIR, ...relative.split("/")), "utf8")
     .replace(/\r\n/g, "\n");
-const PINS_FILE = path.join(import.meta.dirname, "..", "runtime", "knowledge", "hfs", "canon-pins.yaml");
 
 
 const managedScripts = (repo, source) => {
@@ -274,7 +273,7 @@ export function ensureLiteCli({ root, manifest, repo }) {
   if (!fs.existsSync(packageFile))
     throw new ScaffoldError("HFS_ADD_NOT_AN_APP", "add cli needs the app root package.json");
   const packageManifest = JSON.parse(fs.readFileSync(packageFile, "utf8"));
-  const pin = parseYaml(fs.readFileSync(PINS_FILE, "utf8")).pins?.["nest-commander"]?.version;
+  const pin = bundledPins()["nest-commander"]?.version;
   if (typeof pin !== "string" || pin === "")
     throw new ScaffoldError("HFS_ADD_CANON_PIN_MISSING", "add cli needs the nest-commander canon pin");
   packageManifest.dependencies = { ...packageManifest.dependencies, "nest-commander": pin };

package/scaffold/add-queue-lite.mjs

@@ -13,7 +13,8 @@ import { materializeDeclaredPlaceholders } from '../runtime/scripts/hfs/sealed-m
 import { REDIS_IMAGE, TEMPLATES_DIR, redisDevScripts, render } from '../sync/index.mjs';
 import { byCodeUnit } from '../report/order.mjs';
 import { withSqlIdentifierError } from './add-database-lite.mjs';
-import { bundledPins, jsonText, packageJsonText } from './app.mjs';
+import { jsonText, packageJsonText } from './app.mjs';
+import { bundledPins } from '../runtime/scripts/hfs/canon-pins.mjs';
 import { registerLiteExports } from './lite-exports.mjs';
 import { ScaffoldError } from './service.mjs';
 import { YamlBlockEdit } from './yaml-block-edit.mjs';

package/scaffold/add.mjs

@@ -25,7 +25,8 @@ import { addLiteWebhookInbox } from './add-inbox-lite.mjs';
 import { planLiteQueue } from './add-queue-lite.mjs';
 import { addBuiltinLiteCli, fillKnownForms, formsOf, planKind, readAddContext } from './add-plan.mjs';
 export { liteApiTemplates } from './add-plan.mjs';
-import { bundledPins, jsonText, packageJsonText, peerDependencies } from './app.mjs';
+import { jsonText, packageJsonText, peerDependencies } from './app.mjs';
+import { bundledPins } from '../runtime/scripts/hfs/canon-pins.mjs';
 import { byCodeUnit } from '../report/order.mjs';
 import { registerLiteDomainService, registerLiteExports } from './lite-exports.mjs';
 

package/scaffold/app.mjs

@@ -17,6 +17,7 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { loadSlotManifest, resolveRepoDeclaration } from '../runtime/scripts/hfs/slots.mjs';
 import { parseYaml } from '../runtime/engine/yaml.mjs';
+import { HARNESS_PACKAGE, canonPins } from '../runtime/scripts/hfs/canon-pins.mjs';
 import { dbTypesPath, generateDbTypes } from '../emit/db-types.mjs';
 import { TEMPLATES_DIR, appSource, imageFiles, render, renderTargets, writeTargets } from '../sync/index.mjs';
 import { ScaffoldError } from './service.mjs';
@@ -40,7 +41,6 @@ const APP_DIR = '__app__';
 /** The path variable of the project name: `packages/__project__-ui` is written as `packages/<project>-ui`. */
 const PROJECT_DIR = '__project__';
 const TIMESTAMP = '__timestamp__';
-const PINS_FILE = path.join(import.meta.dirname, '..', 'runtime', 'knowledge', 'hfs', 'canon-pins.yaml');
 /**
  * The front-end stack catalog (knowledge/hfs/fe-stack.yaml): the bundled runtime copy, else the runtime checkout's own file (the
  * package inside the StarCi repository before the runtime copy carries it).
@@ -53,8 +53,6 @@ const SONAR_GATE_FILE = path.join(import.meta.dirname, '..', 'runtime', 'knowled
 /** The runtime-peer catalog (knowledge/hfs/peer-integrations.yaml, R111) the package carries. */
 const PEERS_FILE = path.join(import.meta.dirname, '..', 'runtime', 'knowledge', 'hfs', 'peer-integrations.yaml');
 const pascal = name => name.split('-').map(part => part[0].toUpperCase() + part.slice(1)).join('');
-/** The canon pins (knowledge/hfs/canon-pins.yaml) the package carries. */
-export const bundledPins = () => parseYaml(fs.readFileSync(PINS_FILE, 'utf8')).pins;
 
 /** The parsed front-end stack catalog; a package without it cannot know what every front end installs. */
 function bundledFeStack() {
@@ -637,7 +635,8 @@ function emitScaffoldDatabaseTypes(root, name, writes, emitTypes) {
  * `starci app scaffold <name>`: writes the new app under `into`, resolves its lockfile with npm (`lock`, npmLock), and returns
  * `{ root, files }` (app-relative paths, sorted). A new path is first made an empty repository with unborn main (`initGit`), so the
  * app always lives in its own Git repository. `presets` are the jest preset's Sonar exclusions; the CLI passes the copy @starci/hfs
- * ships (bundledPresets). Failure removes only scaffold-owned entries, retaining the .git.
+ * ships (bundledPresets). `harness` ({ version }) is the CLI that runs the scaffold: the root devDependencies name starci-harness at
+ * its version (canon-pins.mjs). Failure removes only scaffold-owned entries, retaining the .git.
  */
 /** Seal declared starter members to a fresh app recipient through the scaffold rollback owner. */
 function initializeScaffoldSecrets(root, writes) {
@@ -659,13 +658,14 @@ function bornRepository(root, initGit) {
   return fs.lstatSync(root);
 }
 
-export function scaffoldApp({ name, into, presets, edition = 'full', authCallback = false, registryVisibility = 'public', manifest = loadSlotManifest(), pins = bundledPins(), lock = npmLock, emitTypes = generateDbTypes, initGit = gitInit, now = () => new Date() }) {
+export function scaffoldApp({ name, into, presets, harness, edition = 'full', authCallback = false, registryVisibility = 'public', manifest = loadSlotManifest(), pins = canonPins({ harness }), lock = npmLock, emitTypes = generateDbTypes, initGit = gitInit, now = () => new Date() }) {
   if (!NAME.test(String(name))) throw new ScaffoldError('HFS_SCAFFOLD_NAME_INVALID', `the app name ${name} must be kebab-case (a project name: ${NAME})`);
   const root = path.resolve(into, name);
   const existing = fs.lstatSync(root, { throwIfNoEntry: false });
   if (existing && !emptyUnbornGit(root, existing)) throw new ScaffoldError('HFS_SCAFFOLD_EXISTS', `${root} already exists; only a plain directory containing solely .git with unborn main and an empty index can be scaffolded`);
   if (!['public', 'private'].includes(registryVisibility)) throw new ScaffoldError('HFS_SCAFFOLD_REGISTRY_VISIBILITY', `--registry-visibility accepts public or private (got ${registryVisibility})`);
   if (typeof authCallback !== 'boolean') throw new ScaffoldError('HFS_SCAFFOLD_NAME_INVALID', 'authCallback must be a boolean');
+  if (!pins[HARNESS_PACKAGE]) throw new ScaffoldError('HFS_SCAFFOLD_PIN_MISSING', `${HARNESS_PACKAGE} has no pin: an app pins the CLI that scaffolds it, so run the scaffold through it (starci app scaffold)`);
   const original = existing ?? bornRepository(root, initGit);
   const declaration = starterDeclaration(name, manifest, edition);
   if (authCallback) enableAuthCallback(declaration);

package/src/main.mjs

@@ -242,7 +242,7 @@ function printExplain(e, out) {
  * The app pass: slots, managed files, formatter, contract snapshots and the architecture machine's check surface, root and sides.
  * `only` limits the formatter to those (app-relative) files.
  */
-async function runCheck({ repoRoot, fast = false, base, only, presets, prettier, dbTypes = false }) {
+async function runCheck({ repoRoot, harness, fast = false, base, only, presets, prettier, dbTypes = false }) {
   const tracked = trackedFiles(repoRoot);
   // Managed files of the root and both sides, the .gitignore block and sonar against their render (R04, R05, R11, ...), and prettier
   // through the app's own install (R19, never under --fast).
@@ -260,7 +260,7 @@ async function runCheck({ repoRoot, fast = false, base, only, presets, prettier,
       contracts = { status: 'checked', apps: emitted.apps };
     }
   }
-  const result = checkRepository({ repoRoot, fast, base, extraFindings });
+  const result = checkRepository({ repoRoot, harness, fast, base, extraFindings });
   if (contracts) result.contracts = contracts;
   return result;
 }
@@ -274,7 +274,7 @@ export function appRootAbove(dir) {
 }
 
 /** `starci app lint`: ESLint per side, the app checks and stylelint over the fe side as one report; see lint/run.mjs. */
-async function lintMain(argv, { cwd, stdout, presets, prettier, runLinter, checkApp = runCheck }) {
+async function lintMain(argv, { cwd, harness, stdout, presets, prettier, runLinter, checkApp = runCheck }) {
   const opts = parseLintArgs(argv);
   // --workspace names a folder from the working directory (`starci app lint --workspace .` is an fe workspace script); the app
   // root is then the nearest folder above it that holds hfs.json, and the workspace is passed on app-relative.
@@ -283,7 +283,7 @@ async function lintMain(argv, { cwd, stdout, presets, prettier, runLinter, check
   if (workspaceDir) opts.workspace = path.relative(repoRoot, workspaceDir).split(path.sep).join('/');
   const { report, sonar, exit } = await lintRepository({
     repoRoot, opts, trackedFiles, runLinter,
-    hfsCheck: (root) => checkApp({ repoRoot: root, only: opts.changed ?? undefined, presets, prettier }),
+    hfsCheck: (root) => checkApp({ repoRoot: root, harness, only: opts.changed ?? undefined, presets, prettier }),
   });
   if (opts.sonar !== undefined) writeReport(path.resolve(cwd, opts.sonar), sonar);
   if (opts.format === 'json') stdout(`${JSON.stringify(report, null, 2)}
@@ -346,10 +346,10 @@ function printCheckProofs(result, out) {
   if (result.coverage) out(formatCoverageReport(result.coverage));
 }
 
-async function checkMain(opts, { cwd: repoRoot, edition, stdout: out, presets, prettier, checkApp = runCheck, runLinter }) {
+async function checkMain(opts, { cwd: repoRoot, harness, edition, stdout: out, presets, prettier, checkApp = runCheck, runLinter }) {
   if (opts.positional.length) throw new Error('starci app check takes no path');
   if (opts.base !== undefined && opts.fast !== true) throw new Error('--base names the ref --fast compares with; it needs --fast');
-  const checked = await checkEdition({ repoRoot, edition, normal: () => checkApp({ repoRoot, fast: opts.fast === true, base: opts.base, presets, prettier, dbTypes: opts['db-types'] === true }), presets, prettier });
+  const checked = await checkEdition({ repoRoot, edition, normal: () => checkApp({ repoRoot, harness, fast: opts.fast === true, base: opts.base, presets, prettier, dbTypes: opts['db-types'] === true }), presets, prettier });
   const proof = withCheckProofs(checked, { repoRoot, edition, wiring: opts.wiring === true, coverageFrom: opts['coverage-from'] });
   const changed = opts.fast === true ? changedSince(repoRoot, proof.fast?.base ?? opts.base).files : null;
   const existing = changed ? changed.filter(file => fs.existsSync(path.join(repoRoot, file))) : [];
@@ -397,10 +397,10 @@ function addMain(opts, { cwd: repoRoot, stdout: out }) {
   return 0;
 }
 
-async function scaffoldMain(opts, { cwd, edition = 'full', presets, lock, stdout: out }) {
+async function scaffoldMain(opts, { cwd, harness, edition = 'full', presets, lock, stdout: out }) {
   const [name, ...extra] = opts.positional;
   if (!name || extra.length) throw new Error('starci app scaffold takes `<name> [--into <dir>] [--edition full|lite] [--registry-visibility public|private]`');
-  const { root: created, files } = scaffoldApp({ name, into: path.resolve(cwd, opts.into ?? '.'), edition, presets: presets ?? scaffoldPresets(), ...(opts['registry-visibility'] === undefined ? {} : { registryVisibility: opts['registry-visibility'] }), ...(lock ? { lock } : {}) });
+  const { root: created, files } = scaffoldApp({ name, into: path.resolve(cwd, opts.into ?? '.'), harness, edition, presets: presets ?? scaffoldPresets(), ...(opts['registry-visibility'] === undefined ? {} : { registryVisibility: opts['registry-visibility'] }), ...(lock ? { lock } : {}) });
   out(`starci app scaffold: created ${created} (${files.length} files); next: starci npm ci (the lockfile, then the git hooks through npm run prepare; after a raw npm ci --ignore-scripts run npm run prepare), then starci app lint\n`);
   return 0;
 }
@@ -449,9 +449,13 @@ function errorMessage(error) {
   return `starci app: ${error.message}\n${USAGE}`;
 }
 
-/** `run` injects the Supabase runner, `runLinter` the linter transport, `checkApp` the HFS check and `stackIo` Swarm tools; production defaults execute every check. */
+/**
+ * `harness` ({ version }) is the CLI that runs this package in-process: its version is the starci-harness an app is judged and
+ * scaffolded at (runtime/scripts/hfs/canon-pins.mjs). `run` injects the Supabase runner, `runLinter` the linter transport, `checkApp`
+ * the HFS check and `stackIo` Swarm tools; production defaults execute every check.
+ */
 export async function main(argv, {
-  cwd: baseCwd = process.cwd(), stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), presets, prettier, lock, run, stackMain,
+  cwd: baseCwd = process.cwd(), harness, stdout = (s) => process.stdout.write(s), stderr = (s) => process.stderr.write(s), presets, prettier, lock, run, stackMain,
   env = process.env, stdin, sops, tools, platform, stackIo, runLinter, checkApp,
 } = {}) {
   try {
@@ -460,7 +464,7 @@ export async function main(argv, {
     const out = global.quiet ? () => {} : stdout;
     if (global.help) { out(USAGE); return 0; }
     if (!VERBS.includes(verb)) { stderr(USAGE); return 2; }
-    return await dispatchMain(verb, rest, { cwd: global.cwd, edition: global.edition, stdout: out, stderr, presets, prettier, lock, run, stackMain, env, stdin, sops, tools, platform, stackIo, runLinter, checkApp });
+    return await dispatchMain(verb, rest, { cwd: global.cwd, harness, edition: global.edition, stdout: out, stderr, presets, prettier, lock, run, stackMain, env, stdin, sops, tools, platform, stackIo, runLinter, checkApp });
   } catch (error) {
     stderr(errorMessage(error));
     return 2;

package/upgrade/index.mjs

@@ -7,20 +7,12 @@
 import fs from "node:fs";
 import path from "node:path";
 import { remember, ensureParent, writeFile, restore } from "./file-state.mjs";
-import { parseYaml } from "../runtime/engine/yaml.mjs";
+import { bundledPins } from "../runtime/scripts/hfs/canon-pins.mjs";
 import { loadSlotManifest } from "../runtime/scripts/hfs/slots.mjs";
 import { LOCK_STEP, npmLock } from "../scaffold/app.mjs";
 import { WORLD_MARKER, testWorldFiles } from "../scaffold/test-world.mjs";
 import { loadHfs } from "../sync/index.mjs";
 
-const PACKAGE_ROOT = path.join(import.meta.dirname, "..");
-const PINS_FILE = path.join(
-  PACKAGE_ROOT,
-  "runtime",
-  "knowledge",
-  "hfs",
-  "canon-pins.yaml",
-);
 const FULL_DEV_DEPENDENCIES = Object.freeze([
   "@nestjs/testing",
   "@starci/jest-preset",
@@ -111,7 +103,7 @@ function fullCompletion(root, declaration) {
     (name) => current.devDependencies?.[name] === undefined && current.dependencies?.[name] === undefined,
   );
   if (missing.length) {
-    const pins = parseYaml(fs.readFileSync(PINS_FILE, "utf8")).pins;
+    const pins = bundledPins();
     const added = pinnedPackage(root, pins).devDependencies;
     const devDependencies = Object.fromEntries(
       Object.entries({ ...current.devDependencies, ...Object.fromEntries(missing.map((name) => [name, added[name]])) })