@starci/hfs 1.0.0 → 2.0.0

package/runtime/scripts/lib/hfs-rules/fe-no-tests.mjs

@@ -0,0 +1,47 @@
+// fe-no-tests.mjs - FE_NO_TESTS (R97): a front-end repository has no tests by standard (owner 2026-09-30). There is no exception: a spec
+// anywhere in a front-end repository is a finding, `scripts/` included.
+//   - a tracked test file: `*.spec.*`, `*.test.*`, `*-spec.*` (also `*.e2e-spec.*`);
+//   - a tracked test directory: `e2e/`, `__tests__/`, `__mocks__/` or `test-support/`;
+//   - a tracked test-tool file: `vitest.*`, `jest.*`, `playwright.*` (config, setup, workspace), `cypress.config.*`, `tsconfig.e2e.json`, `e2e.yml`;
+//   - a test script in a package.json: a script named `test`, `test:*` (or with a pre/post prefix), or one that runs a test runner;
+//   - a test dependency in a package.json: a test runner, a test environment, testing-library or an axe package.
+// The check reads the tracked tree and the manifests only. One finding per path (a manifest: one per script or dependency), and it is
+// the only finding of a test file: the slot check leaves these paths to it (isFeTestPath).
+import { found, readJson } from './read.mjs';
+
+export const FE_NO_TESTS = 'FE_NO_TESTS';
+const SPEC_FILE = /(?:\.(?:spec|test)|-spec)\.[cm]?[jt]sx?$/;
+const TEST_DIRECTORY = /(?:^|\/)(?:e2e|__tests__|__mocks__|test-support)\//;
+const TEST_TOOL_FILE = /(?:^|\/)(?:(?:vitest|jest|playwright)\.[^/]+|cypress\.config\.[^/]+|tsconfig\.e2e\.json|e2e\.ya?ml)$/;
+const TEST_SCRIPT_NAME = /^(?:pre|post)?test(?::|$)/;
+const TEST_RUNNER_COMMAND = /(?:^|[\s&|;(])(?:npx\s+)?(?:vitest|jest|playwright|cypress|mocha)(?=$|[\s&|;)])|\bnode\s+(?:--\S+\s+)*--test\b/;
+const TEST_DEPENDENCY = /^(?:vitest|@vitest\/.+|playwright|playwright-core|@playwright\/.+|jest|@jest\/.+|ts-jest|babel-jest|@types\/jest|jest-[\w-]+|mocha|@types\/mocha|cypress|@testing-library\/.+|jsdom|@types\/jsdom|happy-dom|axe-core|@axe-core\/.+|vitest-axe|@starci\/(?:vitest|jest|playwright)-preset)$/;
+const DEPENDENCY_SECTIONS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+
+/** True for a path FE_NO_TESTS owns: a spec file, a test directory or a test-tool file. */
+export const isFeTestPath = (file) => SPEC_FILE.test(file) || TEST_DIRECTORY.test(file) || TEST_TOOL_FILE.test(file);
+
+/** The findings of R97 over the tracked paths `files` of a front-end repository at `repoRoot`. */
+export function feNoTestsFindings({ repoRoot, files }) {
+  const findings = [];
+  for (const file of files) {
+    if (isFeTestPath(file)) {
+      const what = SPEC_FILE.test(file) ? 'a test file' : TEST_DIRECTORY.test(file) ? 'inside a test directory' : 'test tooling';
+      findings.push(found(FE_NO_TESTS, file, `${file} is ${what}; a front-end repository has no tests, no test tooling and no exception: delete it`));
+      continue;
+    }
+    if (file !== 'package.json' && !file.endsWith('/package.json')) continue;
+    if (file.includes('node_modules/')) continue;
+    const pkg = readJson(repoRoot, file);
+    if (!pkg || typeof pkg !== 'object') continue;
+    for (const [name, command] of Object.entries(pkg.scripts ?? {})) {
+      if (TEST_SCRIPT_NAME.test(name) || TEST_RUNNER_COMMAND.test(String(command))) findings.push(found(FE_NO_TESTS, file, `${file} script ${name} is a test script (${String(command).slice(0, 80)}); a front-end repository has no tests: delete the script`));
+    }
+    for (const section of DEPENDENCY_SECTIONS) {
+      for (const name of Object.keys(pkg[section] ?? {})) {
+        if (TEST_DEPENDENCY.test(name)) findings.push(found(FE_NO_TESTS, file, `${file} ${section} names ${name}, a test dependency; a front-end repository has no tests: delete the dependency`));
+      }
+    }
+  }
+  return findings;
+}

package/runtime/scripts/lib/hfs-rules/frontend.mjs

@@ -0,0 +1,124 @@
+// frontend.mjs - the front-end tree checks of hfs check, per app (`apps/<app>`, kind next):
+//   FE_WIRE_GENERATED (R52)     wire types come from the contract copy: an app that keeps `modules/api/contract/*` declares the
+//                               `codegen` script and runs it before `build` and `typecheck` (prebuild, pretypecheck), and its
+//                               generated types on disk (`modules/api/__generated__/`, never tracked) are not older than the copy
+//   FE_I18N_PLACEMENT (R59)     next-intl with the `[locale]` segment: `next-intl` is a dependency (of the app, the root or the shared
+//                               i18n package under `packages/`), every route file sits under
+//                               `src/app/[locale]/` (the root redirect page, global-error and health probes excepted), locale
+//                               routing is `src/proxy.ts` and never `middleware.ts`, and the default locale's catalog `vi.json` exists
+//   FE_I18N_CATALOG (R60)       every `modules/i18n/messages/<locale>.json` has the same key set
+// The files each app must hold (routing.ts, navigation.ts, request.ts, messages/, the [locale] layout) are the slot manifest's requires
+// (HFS_SLOT_REQUIRED_MISSING); which source may hold display text and how copy resolves is eslint-fe's.
+import fs from 'node:fs';
+import path from 'node:path';
+import { found, readJson } from './read.mjs';
+
+export const WIRE_GENERATED = 'FE_WIRE_GENERATED';
+export const I18N_PLACEMENT = 'FE_I18N_PLACEMENT';
+export const I18N_CATALOG = 'FE_I18N_CATALOG';
+export const DEFAULT_LOCALE = 'vi';
+const ROUTE_FILE = /\/(?:page|layout|template|loading|error|not-found)\.[jt]sx?$/;
+const LOCALE = /^[a-z]{2,3}(?:-[A-Za-z0-9]+)*$/;
+const STALE_MS = 1000;
+
+/** Every leaf key of a parsed catalog as a dotted path. */
+export function catalogKeys(value, prefix = '') {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return [prefix];
+  const entries = Object.entries(value);
+  return entries.length ? entries.flatMap(([key, child]) => catalogKeys(child, prefix ? `${prefix}.${key}` : key)) : [prefix];
+}
+
+/** The newest modification time (ms) of any file below `dir`, or null when it holds none. */
+function newestBelow(dir) {
+  let newest = null;
+  const walk = (current) => {
+    let entries;
+    try { entries = fs.readdirSync(current, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      const target = path.join(current, entry.name);
+      if (entry.isDirectory()) walk(target);
+      else try { newest = Math.max(newest ?? 0, fs.statSync(target).mtimeMs); } catch { /* vanished while reading */ }
+    }
+  };
+  walk(dir);
+  return newest;
+}
+
+const scriptsOf = (repoRoot, file) => readJson(repoRoot, file)?.scripts ?? {};
+
+function wireFindings({ repoRoot, app, tracked }) {
+  const base = `apps/${app}`;
+  const copies = tracked.filter((file) => file.startsWith(`${base}/src/modules/api/contract/`));
+  if (!copies.length) return [];
+  const findings = [];
+  const manifest = `${base}/package.json`;
+  const scripts = scriptsOf(repoRoot, manifest);
+  const rootScripts = scriptsOf(repoRoot, 'package.json');
+  // A root script that only fans out to the workspaces (`npm run x --workspaces`, the managed FE root) is not this app's
+  // script: the app's own manifest must declare it.
+  const delegates = (script) => /(?:^|\s)--workspaces?(?:\s|=|$)/.test(String(script ?? ''));
+  const wired = (name) => scripts[name] ?? (delegates(rootScripts[name]) ? undefined : rootScripts[name]);
+  if (typeof wired('codegen') !== 'string') findings.push(found(WIRE_GENERATED, manifest, `${app} keeps a contract copy but declares no \`codegen\` script; wire types are generated from the copy, never typed by hand`, { app }));
+  else for (const hook of ['prebuild', 'pretypecheck']) {
+    if (!/\bcodegen\b/.test(String(wired(hook) ?? ''))) findings.push(found(WIRE_GENERATED, manifest, `${app} does not run codegen in \`${hook}\`; generate the wire types before build and typecheck`, { app, script: hook }));
+  }
+  const generated = `${base}/src/modules/api/__generated__`;
+  const built = newestBelow(path.join(repoRoot, generated));
+  if (built !== null) {
+    for (const copy of copies) {
+      let changed;
+      try { changed = fs.statSync(path.join(repoRoot, copy)).mtimeMs; } catch { continue; }
+      if (built + STALE_MS < changed) findings.push(found(WIRE_GENERATED, generated, `${generated} is older than ${copy}; run \`npm run codegen\` so the wire types match the contract copy`, { app, copy }));
+    }
+  }
+  return findings;
+}
+
+function placementFindings({ repoRoot, app, tracked }) {
+  const base = `apps/${app}`;
+  const findings = [];
+  const declares = (file) => { const pkg = readJson(repoRoot, file); return pkg ? ['dependencies', 'devDependencies'].some((section) => pkg[section]?.['next-intl'] !== undefined) : false; };
+  const manifest = `${base}/package.json`;
+  // The next-intl stack is written once per repository: in the app, or in the shared `packages/<family>-i18n` the apps call.
+  const shared = tracked.filter((file) => /^packages\/[^/]+\/package\.json$/.test(file));
+  if (tracked.includes(manifest) && ![manifest, 'package.json', ...shared].some(declares)) findings.push(found(I18N_PLACEMENT, manifest, `${app} does not depend on next-intl (nor does the root or a shared package); every app uses next-intl with the [locale] segment`, { app }));
+  if (!tracked.includes(`${base}/src/proxy.ts`)) findings.push(found(I18N_PLACEMENT, `${base}/src/proxy.ts`, `${app} has no src/proxy.ts; locale routing lives in proxy.ts`, { app }));
+  for (const file of tracked.filter((f) => new RegExp(`^${base}/src/middleware\.[cm]?[jt]s$`).test(f))) findings.push(found(I18N_PLACEMENT, file, `${file} is a middleware file; Next 16 routes through src/proxy.ts`, { app }));
+  const appDir = `${base}/src/app/`;
+  for (const file of tracked.filter((f) => f.startsWith(appDir) && ROUTE_FILE.test(f))) {
+    const rel = file.slice(appDir.length);
+    if (rel.startsWith('[locale]/') || rel.startsWith('health/') || ['page.tsx', 'not-found.tsx', 'layout.tsx'].includes(rel)) continue;  // next-intl's root not-found and its layout
+    findings.push(found(I18N_PLACEMENT, file, `${file} is a route file outside the [locale] segment; every page, layout and boundary sits under src/app/[locale]/`, { app }));
+  }
+  const messages = `${base}/src/modules/i18n/messages/`;
+  const catalogs = tracked.filter((f) => f.startsWith(messages) && f.endsWith('.json'));
+  if (!catalogs.includes(`${messages}${DEFAULT_LOCALE}.json`)) findings.push(found(I18N_PLACEMENT, `${messages}${DEFAULT_LOCALE}.json`, `${app} has no ${DEFAULT_LOCALE}.json catalog; the default locale is ${DEFAULT_LOCALE}`, { app }));
+  for (const file of catalogs) {
+    const name = path.posix.basename(file, '.json');
+    if (path.posix.dirname(file) + '/' !== messages || !LOCALE.test(name)) findings.push(found(I18N_PLACEMENT, file, `${file} is not a <locale>.json catalog directly under modules/i18n/messages/`, { app }));
+  }
+  return findings;
+}
+
+function catalogFindings({ repoRoot, app, tracked }) {
+  const messages = `apps/${app}/src/modules/i18n/messages/`;
+  const catalogs = tracked.filter((f) => f.startsWith(messages) && f.endsWith('.json') && f.slice(messages.length).indexOf('/') === -1);
+  const keys = new Map();
+  for (const file of catalogs) {
+    const parsed = readJson(repoRoot, file);
+    if (parsed !== null) keys.set(file, new Set(catalogKeys(parsed)));
+  }
+  if (keys.size < 2) return [];
+  const all = new Set([...keys.values()].flatMap((set) => [...set]));
+  const findings = [];
+  for (const [file, set] of keys) {
+    const missing = [...all].filter((key) => !set.has(key)).sort();
+    if (missing.length) findings.push(found(I18N_CATALOG, file, `${file} lacks ${missing.length} key${missing.length === 1 ? '' : 's'} another locale has (${missing.slice(0, 5).join(', ')}${missing.length > 5 ? ', ...' : ''}); every catalog holds the same keys`, { app, missing }));
+  }
+  return findings;
+}
+
+/** The front-end tree findings of R52, R59 and R60 for every `next` app of the repository. */
+export function frontendFindings({ repoRoot, files, repo }) {
+  return repo.apps.filter((a) => a.kind === 'next').flatMap((a) => [wireFindings, placementFindings, catalogFindings].flatMap((check) => check({ repoRoot, app: a.name, tracked: files })));
+}

package/runtime/scripts/lib/hfs-rules/lint-suppression.mjs

@@ -0,0 +1,34 @@
+// lint-suppression.mjs - HFS_LINT_SUPPRESSION_FILE (R104): a repository keeps no lint-suppression file, script or option. A finding is
+// fixed in the code (or the rule is changed in the canon); it is never recorded away in a file that lets it stay.
+//   - a file named `eslint.suppressions*` or `eslint-suppressions*`;
+//   - a package.json script named `lint:suppressions` (or any `<x>:suppressions`), or one that passes `--suppressions-location`,
+//     `--suppress-all`, `--suppress-rule` or `--prune-suppressions` to eslint;
+//   - an `eslint.config.*` that names a suppressions configuration.
+// Comment-level suppression (`eslint-disable`) is the lint rule `no-inline-suppression`'s (R18).
+import { found, readJson, readText } from './read.mjs';
+
+export const LINT_SUPPRESSION_FILE = 'HFS_LINT_SUPPRESSION_FILE';
+const SUPPRESSION_FILE = /(?:^|\/)eslint[.-]suppressions[^/]*$/;
+const SUPPRESSION_SCRIPT_NAME = /(?:^|:)suppressions$/;
+const SUPPRESSION_FLAG = /--(?:suppressions-location|suppress-all|suppress-rule|prune-suppressions)\b/;
+const ESLINT_CONFIG = /(?:^|\/)eslint\.config\.[cm]?[jt]s$/;
+const CONFIG_SUPPRESSION = /suppressions/i;
+
+/** The findings of R104 over the tracked paths `files` of the repository at `repoRoot`. */
+export function lintSuppressionFindings({ repoRoot, files }) {
+  const findings = [];
+  for (const file of files) {
+    if (file.includes('node_modules/')) continue;
+    if (SUPPRESSION_FILE.test(file)) findings.push(found(LINT_SUPPRESSION_FILE, file, `${file} is a lint-suppression file; a finding is fixed in the code, never recorded in a file that lets it stay`));
+    else if (ESLINT_CONFIG.test(file)) {
+      const text = readText(repoRoot, file);
+      if (text !== null && CONFIG_SUPPRESSION.test(text)) findings.push(found(LINT_SUPPRESSION_FILE, file, `${file} passes a suppressions configuration to eslint; a repository suppresses nothing`));
+    } else if (file === 'package.json' || file.endsWith('/package.json')) {
+      const pkg = readJson(repoRoot, file);
+      for (const [name, command] of Object.entries(pkg?.scripts ?? {})) {
+        if (SUPPRESSION_SCRIPT_NAME.test(name) || SUPPRESSION_FLAG.test(String(command))) findings.push(found(LINT_SUPPRESSION_FILE, file, `${file} script ${name} manages lint suppressions (${String(command).slice(0, 80)}); delete the script and fix the findings in the code`));
+      }
+    }
+  }
+  return findings;
+}

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

@@ -0,0 +1,51 @@
+// pipeline.mjs - HFS_CI_MISSING_CANON (R13): CI runs the pinned `hfs check`; pre-push runs typecheck and lint.
+//   .github/workflows/ci.yml   a `run:` step that runs `hfs check` as a whole (not `--fast`): `npx hfs check`, `npx @starci/hfs[@<version>]
+//                              check`, or `npm run <script>` of the root package.json whose command is `hfs check`; a version named in
+//                              the step is the @starci/hfs pin of canon-pins.yaml (an installed one is pinned by the pin check, R15)
+//   .husky/pre-push            `npm run typecheck` and `npm run lint:check`, each on a line of its own
+// 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).
+import { found, readJson, readText } from './read.mjs';
+
+export const CI_MISSING_CANON = 'HFS_CI_MISSING_CANON';
+export const CI_FILE = '.github/workflows/ci.yml';
+export const PRE_PUSH_FILE = '.husky/pre-push';
+export const hfsPackage = '@starci/hfs';
+const RUN_LINE = /^\s*(?:-\s+)?run:\s*(.+?)\s*$/;
+const HFS_CHECK = /^(?:npx\s+(?:--no-install\s+|-y\s+)?)?(?:@starci\/hfs|hfs)(?:@(\S+))?\s+check(\s.*)?$/;
+const NPM_RUN = /^npm run ([\w:.-]+)(?:\s+--\s+(.*))?$/;
+const FAST = /(^|\s)--fast(\s|$)/;
+
+const commandsOf = (text) => text.split(/\r?\n/).map((line) => RUN_LINE.exec(line)?.[1]).filter(Boolean).map((command) => command.replace(/^["']|["']$/g, ''));
+
+/** `npm run <script> -- <args>` spelled out as the root package.json script it runs; any other command is itself. */
+function expanded(command, scripts) {
+  const run = NPM_RUN.exec(command);
+  return run && typeof scripts[run[1]] === 'string' ? `${scripts[run[1]]}${run[2] ? ` ${run[2]}` : ''}` : command;
+}
+
+const runsStep = (lines, step) => lines.some((line) => new RegExp(`^npm run ${step}(\\s|$)`).test(line));
+
+/** The findings of R13 over the repository at `repoRoot`; `pins` is the parsed canon-pins.yaml pin map. */
+export function pipelineFindings({ repoRoot, files, pins }) {
+  const findings = [];
+  const pinned = pins?.[hfsPackage]?.version;
+  const ci = files.includes(CI_FILE) ? readText(repoRoot, CI_FILE) : null;
+  if (ci !== null) {
+    const scripts = readJson(repoRoot, 'package.json')?.scripts ?? {};
+    const checks = commandsOf(ci).map((command) => HFS_CHECK.exec(expanded(command, scripts))).filter(Boolean);
+    const whole = checks.filter((match) => !FAST.test(match[2] ?? ''));
+    if (!whole.length) findings.push(found(CI_MISSING_CANON, CI_FILE, `${CI_FILE} has no step that runs \`hfs check\` (\`npx hfs check\`, or an npm script that is exactly that); CI must run the whole pinned hfs check, not --fast`, { step: 'hfs check' }));
+    else if (pinned && !whole.some((match) => match[1] === undefined || match[1] === pinned)) {
+      findings.push(found(CI_MISSING_CANON, CI_FILE, `${CI_FILE} runs hfs check at ${whole[0][1]}, but ${hfsPackage} is pinned at ${pinned}; run the pinned version`, { step: 'hfs check', pinned }));
+    }
+  }
+  const prePush = files.includes(PRE_PUSH_FILE) ? readText(repoRoot, PRE_PUSH_FILE) : null;
+  if (prePush !== null) {
+    const lines = prePush.split(/\r?\n/).map((line) => line.trim()).filter((line) => line && !line.startsWith('#'));
+    for (const step of ['typecheck', 'lint:check']) {
+      if (!runsStep(lines, step)) findings.push(found(CI_MISSING_CANON, PRE_PUSH_FILE, `${PRE_PUSH_FILE} does not run \`npm run ${step}\`; pre-push runs typecheck and lint`, { step }));
+    }
+  }
+  return findings;
+}

package/runtime/scripts/lib/hfs-rules/proof-commands.mjs

@@ -0,0 +1,64 @@
+// proof-commands.mjs - HFS_PROOF_COMMAND_FILE_MISSING (R105): a proof command a `.starciwork` record names runs files that exist.
+// A record's `requiresProof.<kind>.command` is "the exact command that satisfies this kind, runnable as written" (work-implementation
+// schema); a command that names a spec, a script or a config the repository does not hold cannot be run as written, and a record that
+// keeps one goes quietly false (nivo-backend, 2026-09-30: `node --test scripts/provision-keycloak.spec.mjs` after the script was deleted).
+// Every argument of the command that is a repository-relative file path (an extension, no glob, no variable, not absolute, not a `..`
+// path into another repository) must be a tracked file or an existing one; a path an ignored slot owns (dist/, coverage/) is a build
+// product and is not judged. One finding per record, kind and missing path. A back end's `.starciwork` also holds the records of the
+// implementations that live in another repository (`repository: nivo-fe`); their commands run there, so only a record of this repository
+// (its `repository` names it, or names none) is judged.
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseYaml } from '../../../engine/yaml.mjs';
+import { repositoryName } from '../repo-identity.mjs';
+import { found, readText } from './read.mjs';
+
+export const PROOF_COMMAND_FILE_MISSING = 'HFS_PROOF_COMMAND_FILE_MISSING';
+const RECORD = /^\.starciwork\/.+\.ya?ml$/;
+const FILE_ARGUMENT = /^(?:\.\/)?[\w@][\w@.\-[\]()]*(?:\/[\w@.\-[\]()]+)*\.[A-Za-z][A-Za-z0-9]{0,7}$/;
+const PATH_SEPARATOR = /\//;
+
+/** The arguments of a shell command line that name a repository file, in order, without duplicates. */
+export function commandFiles(command) {
+  const words = String(command).split(/[\s&|;()<>]+/).filter(Boolean).map((word) => word.replace(/^['"]|['"]$/g, ''));
+  const files = [];
+  for (const word of words) {
+    if (word.startsWith('-') || word.startsWith('..') || path.isAbsolute(word) || /^[A-Za-z]:/.test(word) || /^[a-z]+:\/\//.test(word)) continue;
+    if (!PATH_SEPARATOR.test(word) || /[*$`{}~=]/.test(word)) continue;
+    if (!FILE_ARGUMENT.test(word)) continue;
+    const clean = word.replace(/^\.\//, '');
+    if (!files.includes(clean)) files.push(clean);
+  }
+  return files;
+}
+
+/** Every `requiresProof.<kind>.command` of a parsed record: [{ kind, command }]. */
+function proofCommands(record) {
+  const demands = record && typeof record === 'object' ? record.requiresProof : null;
+  if (!demands || typeof demands !== 'object') return [];
+  return Object.entries(demands).flatMap(([kind, demand]) => (typeof demand?.command === 'string' ? [{ kind, command: demand.command }] : []));
+}
+
+/** The findings of R105 over the tracked paths `files` of the repository at `repoRoot`; `resolver` names the ignored slots. */
+export function proofCommandFindings({ repoRoot, files, resolver }) {
+  const findings = [];
+  const tracked = new Set(files);
+  const own = repositoryName(repoRoot);
+  for (const file of files) {
+    if (!RECORD.test(file)) continue;
+    const text = readText(repoRoot, file);
+    if (text === null || !text.includes('requiresProof')) continue;
+    let record;
+    try { record = parseYaml(text); } catch { continue; }
+    if (typeof record?.repository === 'string' && record.repository !== own) continue;
+    for (const { kind, command } of proofCommands(record)) {
+      for (const target of commandFiles(command)) {
+        if (tracked.has(target) || fs.existsSync(path.join(repoRoot, target))) continue;
+        const classified = resolver.classifyPath(target);
+        if (classified.status === 'owned' && classified.tracking === 'ignored') continue;
+        findings.push(found(PROOF_COMMAND_FILE_MISSING, file, `${file} requiresProof.${kind}.command runs ${target}, which the repository does not hold; a proof command is runnable as written: create the file or rewrite the proof plan`, { kind, missing: target }));
+      }
+    }
+  }
+  return findings;
+}

package/runtime/scripts/lib/hfs-rules/read.mjs

@@ -0,0 +1,28 @@
+// read.mjs - what the tree checks of hfs-check.mjs share: one bounded text read and the shape of a finding.
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Files above this size are not read by a tree check (a tracked binary or a generated dump is no source of these laws). */
+export const MAX_READ_BYTES = 1024 * 1024;
+
+/** The text of `rel` under `repoRoot`, or null when it is absent, unreadable, over MAX_READ_BYTES or binary. */
+export function readText(repoRoot, rel) {
+  try {
+    const target = path.join(repoRoot, rel);
+    if (fs.statSync(target).size > MAX_READ_BYTES) return null;
+    const text = fs.readFileSync(target, 'utf8');
+    return text.includes('\0') ? null : text;
+  } catch {
+    return null;
+  }
+}
+
+/** The JSON of `rel`, or null when it is absent or not JSON. */
+export function readJson(repoRoot, rel) {
+  const text = readText(repoRoot, rel);
+  if (text === null) return null;
+  try { return JSON.parse(text); } catch { return null; }
+}
+
+/** One error finding of `code` on `file`; `extra` carries the finding's own fields. */
+export const found = (code, file, message, extra = {}) => ({ code, level: 'error', path: file, ...extra, message });

package/runtime/scripts/lib/hfs-rules/repo-local-checks.mjs

@@ -0,0 +1,32 @@
+// repo-local-checks.mjs - HFS_REPO_LOCAL_CHECK (R103): a repository carries no check, lint rule or lint plugin of its own. Every check
+// lives in the .claude runtime or in a canon package (`@starci/eslint-canon-*`), so a repository has none to keep in step.
+//   - a file or folder named `eslint-local-rules*`, `eslint-plugin*` or `eslint-local-plugin*`, or one below an `eslint-rules/` or `lint-rules/` folder;
+//   - a `check-*` file in a `scripts/` or `tools/` folder (a check under another name is the reviewer's, not a name test's);
+//   - a package.json script that runs a `check-*` file of `scripts/` or `tools/`.
+// The check reads the tracked tree and the manifests. `scripts/` may keep operational scripts (repo.scripts); it keeps no check.
+// Not judged here, because another rule already is: a file that defines an ESLint rule or a stylelint plugin by its content, and a script that
+// swaps the configuration (HFS_TOOL_CONFIG_LOCAL, R16), and an eslint.config that differs from the render, a relative import of a local plugin
+// included (HFS_RULE_OFF_WITHOUT_REPLACEMENT, R17). This rule adds the forbidden roles by name: what a check or a rule file is called.
+import { found, readJson } from './read.mjs';
+
+export const REPO_LOCAL_CHECK = 'HFS_REPO_LOCAL_CHECK';
+const LOCAL_RULE_FILE = /(?:^|\/)(?:eslint-local-rules|eslint-plugin|eslint-local-plugin)[^/]*(?:\/|$)|(?:^|\/)(?:eslint-rules|lint-rules)\//;
+const CHECK_SCRIPT = /(?:^|\/)(?:scripts|tools)\/check-[^/]+$/;
+const RUNS_CHECK = /(?:^|[\s&|;(])(?:\.\/)?(?:scripts|tools)\/check-[^\s&|;)]+/;
+
+/** The findings of R103 over the tracked paths `files` of the repository at `repoRoot`. */
+export function repoLocalCheckFindings({ repoRoot, files }) {
+  const findings = [];
+  for (const file of files) {
+    if (file.includes('node_modules/')) continue;
+    if (LOCAL_RULE_FILE.test(file)) findings.push(found(REPO_LOCAL_CHECK, file, `${file} is a local lint rule or plugin; a repository keeps no rule of its own: the rule is proposed to the canon (@starci/eslint-canon-*) in the .claude runtime`));
+    else if (CHECK_SCRIPT.test(file)) findings.push(found(REPO_LOCAL_CHECK, file, `${file} is a check kept in the repository; every check lives in the .claude runtime (hfs check, the canons), so a repository has none to keep`));
+    else if (file === 'package.json' || file.endsWith('/package.json')) {
+      const pkg = readJson(repoRoot, file);
+      for (const [name, command] of Object.entries(pkg?.scripts ?? {})) {
+        if (RUNS_CHECK.test(String(command))) findings.push(found(REPO_LOCAL_CHECK, file, `${file} script ${name} runs a repository-local check (${String(command).slice(0, 80)}); delete the script, the check belongs to the .claude runtime`));
+      }
+    }
+  }
+  return findings;
+}

package/runtime/scripts/lib/hfs-rules/secrets.mjs

@@ -0,0 +1,54 @@
+// secrets.mjs - HFS_PLAINTEXT_SECRET (R06): secrets exist only as `.starcistacks/<env>/secrets/<slug>.enc` sops envelopes.
+// It judges the tracked tree with the one list of secret shapes the push scan refuses (scripts/lib/secret-patterns.mjs):
+//   - a tracked file that is a secret by being (an env file, a key file, a credentials file, a plaintext member of a
+//     secrets directory), and every path a forbidden `external` slot names HFS_PLAINTEXT_SECRET for (the slot manifest);
+//   - a tracked `.enc` that is not a sops envelope (an encrypted-looking file that holds plaintext);
+//   - a line of any other tracked text file that matches a secret pattern.
+// A finding names the file, the line and the pattern, never the value.
+import { FORBIDDEN_FILES, secretHits } from '../secret-patterns.mjs';
+import { isSopsEnvelope } from '../test-secrets.mjs';
+import { found, readText } from './read.mjs';
+
+export const PLAINTEXT_SECRET = 'HFS_PLAINTEXT_SECRET';
+/** Files whose lines are not secrets: a lockfile carries integrity hashes, never a credential. */
+const NOT_SCANNED = /(^|\/)package-lock\.json$/;
+
+/** True when the slot `id` of the manifest reports HFS_PLAINTEXT_SECRET for the paths it forbids. */
+export const slotOwnsSecrets = (slot) => slot?.rules?.includes(PLAINTEXT_SECRET) === true;
+
+/**
+ * The findings of R06 for one tracked file that no forbidden slot claims: a secret by being (an env file, a key file), an `.enc` that is
+ * no sops envelope, or a line that matches a secret pattern. `text` is the file's text, or null when it cannot be read (binary, too
+ * large, absent). The whole-tree check reads the work tree and the commit hook (`hfs work-hygiene`) reads the staged blob: one judgement.
+ */
+export function secretFileFindings({ file, text }) {
+  const being = FORBIDDEN_FILES.find((rule) => rule.test(file));
+  if (being) return [found(PLAINTEXT_SECRET, file, `${file} is a plaintext secret by being (${being.name}); a secret is committed only as a sops envelope at .starcistacks/<env>/secrets/<slug>.enc`, { pattern: being.name })];
+  if (text === null || text === undefined || NOT_SCANNED.test(file)) return [];
+  if (file.endsWith('.enc')) return isSopsEnvelope(text) ? [] : [found(PLAINTEXT_SECRET, file, `${file} is named like a sealed secret but is not a sops envelope; encrypt the value with sops and commit only the envelope`, { pattern: 'sops-not-envelope' })];
+  const findings = [];
+  const lines = text.split(/\r?\n/);
+  const seen = new Set();
+  for (let index = 0; index < lines.length; index += 1) {
+    for (const pattern of secretHits(file, lines[index])) {
+      if (seen.has(pattern)) continue;
+      seen.add(pattern);
+      findings.push(found(PLAINTEXT_SECRET, file, `${file}:${index + 1} holds a plaintext secret (${pattern}); seal it with sops at .starcistacks/<env>/secrets/<slug>.enc and read it by *_FILE`, { line: index + 1, pattern }));
+    }
+  }
+  return findings;
+}
+
+/** The findings of R06 over `files` (tracked paths) of `repoRoot`; `resolver` names the slots. */
+export function secretFindings({ repoRoot, files, resolver }) {
+  const findings = [];
+  for (const file of files) {
+    const slot = resolver.classifyPath(file);
+    if (slot.status === 'forbidden' && slotOwnsSecrets(resolver.slot(slot.slot))) {
+      findings.push(found(PLAINTEXT_SECRET, file, `${file} is a plaintext secret file tracked in ${slot.slot}${slot.goesTo ? `; it belongs at ${slot.goesTo}` : ''}`, { slot: slot.slot, goesTo: slot.goesTo }));
+      continue;
+    }
+    findings.push(...secretFileFindings({ file, text: readText(repoRoot, file) }));
+  }
+  return findings;
+}

package/runtime/scripts/lib/hfs-rules/spec-placement.mjs

@@ -0,0 +1,31 @@
+// spec-placement.mjs - BE_SPEC_PLACEMENT (R102): a back-end spec or test file lives in one of the four test layers and nowhere else.
+//   - a unit spec is `<name>.service.spec.ts` beside its service, in a slot whose `tests` is `unit-beside` (the slot and the lint rule
+//     `unit-test-colocated` judge the name);
+//   - integration, e2e and contract specs are `src/tests/{integration,e2e,contract}/...`, the slots whose `tests` is `e2e`;
+//   - an app's own folder (`apps/<app>/src/`, the slots that name an `appKind`) holds the app's composition spec, which the architecture
+//     machine's app-composition check judges.
+// Every other tracked `*.spec.*`, `*.test.*` or `*-spec.*` file is a finding, `scripts/` and `tools/` included: an operational script
+// carries no spec, and a spec that guards one moves into a layer or goes. A file no slot owns (`tools/x.spec.ts`) is judged too, so the
+// finding names the rule rather than only the missing slot. Which folder is a layer is read from the slot manifest, never spelled here.
+import { found } from './read.mjs';
+
+export const SPEC_PLACEMENT = 'BE_SPEC_PLACEMENT';
+const SPEC_FILE = /(?:\.(?:spec|test)|-spec)\.[cm]?[jt]sx?$/;
+const TEST_SLOT_TESTS = new Set(['unit-beside', 'e2e']);
+
+/** True for a file name that is a spec or a test. */
+export const isSpecFile = (file) => SPEC_FILE.test(file);
+
+/** The findings of R102 over the tracked paths `files` of a back-end repository; `resolver` names the slots. */
+export function specPlacementFindings({ files, resolver }) {
+  const findings = [];
+  for (const file of files) {
+    if (!isSpecFile(file) || file.includes('node_modules/')) continue;
+    const classified = resolver.classifyPath(file);
+    const slot = classified.status === 'owned' ? resolver.slot(classified.slot) : null;
+    if (slot && (TEST_SLOT_TESTS.has(slot.tests) || slot.appKind !== undefined)) continue;
+    const where = slot ? `slot ${slot.id}` : 'no slot';
+    findings.push(found(SPEC_PLACEMENT, file, `${file} is a spec outside the test layers (${where}); a unit spec is <name>.service.spec.ts beside its service and an integration, e2e or contract spec sits under src/tests/{integration,e2e,contract}; an operational script or a tool carries no spec`));
+  }
+  return findings;
+}

package/runtime/scripts/lib/hfs-rules/stacks.mjs

@@ -0,0 +1,54 @@
+// stacks.mjs - HFS_STACKS_SHAPE (R10): `.starcistacks` has the standard shape and the host Sonar owner.
+//   - every tracked path under `.starcistacks/` is one the be.starcistacks slot allows (its `allows` list is the shape:
+//     application-stacks.yaml and <env>/{README.md, environment.json, infra/{compose,k8s,terraform}, runtime/{config,env},
+//     secrets/<slug>.enc, seeds}); a `.enc` outside <env>/secrets/ is never allowed, `runtime/files/`, a root `DESIGN.md`,
+//     `deployment.json` and `k8s/` are not in the list, so they fall out of it;
+//   - the declaration (read by scripts/lib/stack-declaration.mjs, the one reader of it) states a sonar service, a local
+//     Sonar is owned by the host (`stack.owner: host`, root `.claude/ext/sonar`), and no service still points at `.stacks`.
+// The declaration's services contract (custody, CI wiring, project keys) stays check-starcistacks's; this file judges shape only.
+import { braceVariants, globExpression } from '../glob.mjs';
+import { declaredStack, findStackDeclaration, STACK_ROOT, text } from '../stack-declaration.mjs';
+import { found } from './read.mjs';
+
+export const STACKS_SHAPE = 'HFS_STACKS_SHAPE';
+export const STACKS_SLOT = 'be.starcistacks';
+export const HOST_SONAR_ROOT = '.claude/ext/sonar';
+const SEALED = /\.enc$/;
+const INSIDE_SECRETS = /^[^/]+\/secrets\/[^/]+\.enc$/;
+const RETIRED_ROOT = /^\.?stacks(?:\/|$)/;
+
+/** The anchored expressions of a slot's `allows` entries: `<name>` is one path segment, braces alternate. */
+const allowedExpressions = (allows) => allows.flatMap((entry) => braceVariants(entry.replace(/<[a-z][a-z0-9-]*>/g, '*'))).map((variant) => globExpression(variant.endsWith('/') ? `${variant}**` : variant));
+
+const shapeFinding = (file, message, extra) => found(STACKS_SHAPE, file, message, extra);
+
+/** The shape findings of the `.starcistacks` tree of a back-end repository. */
+export function stacksFindings({ repoRoot, files, resolver }) {
+  const slot = resolver.slot(STACKS_SLOT);
+  if (!slot) return [];
+  const findings = [];
+  const allowed = allowedExpressions(slot.allows ?? []);
+  const prefix = `${STACK_ROOT}/`;
+  for (const file of files.filter((f) => f.startsWith(prefix))) {
+    const rel = file.slice(prefix.length);
+    if (SEALED.test(rel) && !INSIDE_SECRETS.test(rel)) findings.push(shapeFinding(file, `${file} is a sealed secret outside <env>/secrets/<slug>.enc; move it to .starcistacks/<env>/secrets/`));
+    else if (!allowed.some((expression) => expression.test(rel))) findings.push(shapeFinding(file, `${file} is not part of the standard .starcistacks shape (application-stacks.yaml and <env>/{README.md, environment.json, infra, runtime/{config,env}, secrets/<slug>.enc, seeds}); move or delete it`));
+  }
+  if (!files.some((f) => f === `${prefix}application-stacks.yaml`)) return findings;
+  const declaration = findStackDeclaration(repoRoot);
+  const declared = `${prefix}application-stacks.yaml`;
+  if (declaration.error) return [...findings, shapeFinding(declared, `${declared} cannot be read: ${declaration.error}`)];
+  const services = declaration.doc?.services;
+  if (services === undefined || typeof services.sonar !== 'object' || services.sonar === null) {
+    findings.push(shapeFinding(declared, `${declared} declares no sonar service; every repository states its Sonar owner (a local one is owned by the host: stack.owner host, root ${HOST_SONAR_ROOT})`));
+    return findings;
+  }
+  for (const [id, entry] of Object.entries(services)) {
+    const stack = declaredStack(entry);
+    if (stack?.root && RETIRED_ROOT.test(stack.root)) findings.push(shapeFinding(declared, `${declared} services.${id}.stack.root ${stack.root} still points at the retired .stacks root; the stack root is ${STACK_ROOT}`));
+    if (id === 'sonar' && text(entry?.mode) === 'local' && !(stack?.hostOwned && stack.root === HOST_SONAR_ROOT)) {
+      findings.push(shapeFinding(declared, `${declared} services.sonar is a local Sonar but is not owned by the host; declare stack.owner host with root ${HOST_SONAR_ROOT}`));
+    }
+  }
+  return findings;
+}

package/runtime/scripts/lib/hfs-rules/test-topology.mjs

@@ -0,0 +1,31 @@
+// test-topology.mjs - BE_TEST_TOPOLOGY (R47), the tree half of BE-CONVENTION 1.16: four test kinds by folder, one jest configuration.
+//   - a unit spec is `<name>.spec.ts`: a tracked `*.test.*` file is refused;
+//   - there is no `testing/` folder: doubles and builders live in `src/tests/fixtures/`, next to the subject as `*.spec.ts`;
+//   - one `jest.config.js` at the root: a second jest config (`jest.config.<x>.js`, `jest.<x>.config.*`, one per app) and a
+//     `jest` key in a package.json are refused.
+// `int-spec`, `harness-spec`, the retired test folders and the per-lane configs under src/tests are the architecture machine's
+// (HFS_TEST_KIND_RETIRED, a sub-code of this rule); that jest.config.js is the rendered one (projects `unit`, `integration`, `e2e` and
+// `contract`, diagnostics off) is the managed-file check's (HFS_MANAGED_FILE_DRIFT); a spec whose suffix disagrees with its src/tests folder has no slot (HFS_SLOT_UNDECLARED).
+import { found, readJson } from './read.mjs';
+
+export const TEST_TOPOLOGY = 'BE_TEST_TOPOLOGY';
+const DOT_TEST = /\.test\.[cm]?[jt]sx?$/;
+const JEST_CONFIG = /(?:^|\/)jest(?:\.[^/]+)*\.config(?:\.[^/]+)*\.(?:[cm]?[jt]s|json)$|(?:^|\/)jest\.config\.[^/]+$/;
+const ROOT_JEST_CONFIG = 'jest.config.js';
+
+/** The findings of R47 over the tracked paths `files` of a back-end repository at `repoRoot`. */
+export function testTopologyFindings({ repoRoot, files }) {
+  const findings = [];
+  for (const file of files) {
+    const segments = file.split('/');
+    if (DOT_TEST.test(file)) findings.push(found(TEST_TOPOLOGY, file, `${file} is a \`.test\` file; a unit spec is <name>.spec.ts beside its subject and an integration, e2e or contract spec is *.integration-spec.ts, *.e2e-spec.ts or *.contract-spec.ts under its own src/tests folder`));
+    else if (segments.slice(0, -1).includes('testing')) findings.push(found(TEST_TOPOLOGY, file, `${file} sits in a testing/ folder; doubles and builders live in src/tests/fixtures/ and specs sit beside their subject`));
+    else if (JEST_CONFIG.test(file) && file !== ROOT_JEST_CONFIG) findings.push(found(TEST_TOPOLOGY, file, `${file} is a second jest configuration; the one root ${ROOT_JEST_CONFIG} declares the projects unit, integration, e2e and contract`));
+    if (file === 'package.json' || file.endsWith('/package.json')) {
+      if (file.includes('node_modules/')) continue;
+      const pkg = readJson(repoRoot, file);
+      if (pkg && Object.hasOwn(pkg, 'jest')) findings.push(found(TEST_TOPOLOGY, file, `${file} carries a jest key; jest is configured only by the root ${ROOT_JEST_CONFIG}`));
+    }
+  }
+  return findings;
+}