@starci/hfs 4.3.0 → 4.4.0

package/runtime/scripts/hfs/rules/fe-contract-documents.mjs

@@ -1,18 +1,90 @@
 // fe-contract-documents.mjs - FE_GRAPHQL_CONTRACT (R113): every GraphQL document a front end sends is one its back end
 // serves. An app keeps the contract of each GraphQL service it runs as a snapshot, `be/contracts/<service>/schema.graphql`
 // (`starci app emit`, HFS_CONTRACT_SNAPSHOT_DRIFT keeps it current), and its front end keeps every operation it sends
-// in a `.graphql` file under `fe/`. Each operation is judged against the contract of the service that serves its first
+// in a `.graphql` file or a `gql` template under `fe/`. Each operation is judged against the contract of the service that serves its first
 // root field (the one snapshot whose root type declares it): a root field no contract declares, a field, argument or input
 // field the contract does not declare, a required argument left out, a variable of another type, a leaf with a selection or
 // an object without one is a finding on the document. The finding names the service and every problem.
 import { operationProblems, parseDocument, parseSchema, rootFieldsOf } from '../../lib/graphql-contract.mjs';
 import { found, readText } from './read.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
+import { fileURLToPath } from 'node:url';
+import { loadTypescript } from '../../lib/package-at.mjs';
+import { isConstVariable, sourceLocation } from '../../lib/ts-ast.mjs';
 
 export const FE_GRAPHQL_CONTRACT = 'FE_GRAPHQL_CONTRACT';
 
 const CONTRACT = /^be\/contracts\/([^/]+)\/schema\.graphql$/;
-const isDocument = (file) => file.startsWith('fe/') && file.endsWith('.graphql') && !file.includes('/__generated__/') && !file.includes('/node_modules/');
+const isFrontend = (file) => file.startsWith('fe/') && !file.includes('/__generated__/') && !file.includes('/node_modules/');
+const isDocument = (file) => isFrontend(file) && file.endsWith('.graphql');
+const isSource = (file) => isFrontend(file) && /\.[cm]?[jt]sx?$/.test(file) && !file.endsWith('.d.ts');
+const HERE = fileURLToPath(new URL('.', import.meta.url));
+
+/** Local names of gql imports (including a graphql-tag default import), alongside the canonical gql spelling. */
+function addGqlImportNames(ts, statement, names) {
+  if (!ts.isImportDeclaration(statement)) return;
+  const clause = statement.importClause;
+  if (statement.moduleSpecifier.text === 'graphql-tag' && clause?.name) names.add(clause.name.text);
+  const bindings = clause?.namedBindings;
+  if (!bindings || !ts.isNamedImports(bindings)) return;
+  for (const entry of bindings.elements) {
+    if ((entry.propertyName ?? entry.name).text === 'gql') names.add(entry.name.text);
+  }
+}
+
+function gqlNames(ts, source) {
+  const names = new Set(['gql']);
+  for (const statement of source.statements) addGqlImportNames(ts, statement, names);
+  return names;
+}
+
+const isGqlTag = (ts, tag, names) => (ts.isIdentifier(tag) && names.has(tag.text)) || (ts.isPropertyAccessExpression(tag) && tag.name.text === 'gql');
+
+/** Resolve literal fragment substitutions without evaluating source code. Unknown or cyclic values cannot be judged. */
+function templateText(ts, node, checker, names, visiting = new Set()) {
+  if (ts.isStringLiteralLike(node)) return node.text;
+  if (ts.isIdentifier(node)) {
+    const symbol = checker.getSymbolAtLocation(node);
+    const declaration = symbol?.valueDeclaration;
+    if (symbol?.declarations?.length !== 1 || !declaration || !ts.isVariableDeclaration(declaration)
+      || !ts.isIdentifier(declaration.name) || !isConstVariable(ts, declaration) || !declaration.initializer || visiting.has(declaration)) return null;
+    return templateText(ts, declaration.initializer, checker, names, new Set([...visiting, declaration]));
+  }
+  if (ts.isTaggedTemplateExpression(node) && isGqlTag(ts, node.tag, names)) return templateText(ts, node.template, checker, names, visiting);
+  if (!ts.isTemplateExpression(node)) return null;
+  let text = node.head.text;
+  for (const span of node.templateSpans) {
+    const value = templateText(ts, span.expression, checker, names, visiting);
+    if (value === null) return null;
+    text += value + span.literal.text;
+  }
+  return text;
+}
+
+/** Bind this file in isolation: the compiler resolves lexical names, but imports and library files are never loaded. */
+function lexicalChecker(ts, source) {
+  const options = { noLib: true, noResolve: true, allowJs: true };
+  const host = ts.createCompilerHost(options);
+  host.getSourceFile = (file) => file === source.fileName ? source : undefined;
+  host.fileExists = () => false;
+  host.readFile = () => undefined;
+  return ts.createProgram([source.fileName], options, host).getTypeChecker();
+}
+
+/** Actual tagged-template AST nodes: comments, quoted examples and other template tags are not operations. */
+function gqlDocuments(ts, file, text) {
+  const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true);
+  const names = gqlNames(ts, source);
+  const templates = [];
+  const visit = (node) => {
+    if (ts.isTaggedTemplateExpression(node) && isGqlTag(ts, node.tag, names)) templates.push(node);
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  if (templates.length === 0) return [];
+  const checker = lexicalChecker(ts, source);
+  return templates.map((node) => ({ text: templateText(ts, node.template, checker, names), ...sourceLocation(source, node) }));
+}
 
 /** The parsed contracts of the app: [{ service, path, schema }], or a finding for a snapshot that does not parse. */
 function contractsOf(repoRoot, files, findings) {
@@ -45,23 +117,51 @@ function operationFindings(file, document, operation, contracts) {
   return [];
 }
 
+function documentFindings(file, text, contracts) {
+  let document;
+  try {
+    document = parseDocument(text);
+  } catch (error) {
+    return [found(FE_GRAPHQL_CONTRACT, file, `${file} is not a GraphQL document: ${error.message}.`)];
+  }
+  return document.operations.flatMap((operation) => operationFindings(file, document, operation, contracts));
+}
+
+function sourceDocuments(ts, file, text, findings) {
+  if (!ts) {
+    findings.push(found(FE_GRAPHQL_CONTRACT, file, `${file} gql templates cannot be judged: no TypeScript resolves from the app; install the app's dependencies.`));
+    return [];
+  }
+  const documents = [];
+  for (const template of gqlDocuments(ts, file, text)) {
+    if (template.text === null) findings.push(found(FE_GRAPHQL_CONTRACT, file, `${file}:${template.line} gql template has a substitution that cannot be resolved to static GraphQL text.`, { line: template.line, column: template.column }));
+    else documents.push({ file, ...template });
+  }
+  return documents;
+}
+
+function documentsOf(repoRoot, files, findings) {
+  const candidates = files.filter((file) => isDocument(file) || isSource(file)).sort(byCodeUnit);
+  const ts = candidates.some(isSource) ? loadTypescript(repoRoot, HERE) : null;
+  const documents = [];
+  for (const file of candidates) {
+    const text = readText(repoRoot, file);
+    if (text === null) continue;
+    if (isDocument(file)) documents.push({ file, text });
+    else documents.push(...sourceDocuments(ts, file, text, findings));
+  }
+  return documents;
+}
+
 /** The findings of R113 over the tracked paths `files` of the app at `repoRoot`. */
 export function feContractFindings({ repoRoot, files }) {
-  const documents = files.filter(isDocument).sort(byCodeUnit);
-  if (documents.length === 0) return [];
   const findings = [];
+  const documents = documentsOf(repoRoot, files, findings);
+  if (documents.length === 0) return findings;
   const contracts = contractsOf(repoRoot, files, findings);
-  for (const file of documents) {
-    const text = readText(repoRoot, file);
-    if (text === null) continue;
-    let document;
-    try {
-      document = parseDocument(text);
-    } catch (error) {
-      findings.push(found(FE_GRAPHQL_CONTRACT, file, `${file} is not a GraphQL document: ${error.message}.`));
-      continue;
-    }
-    for (const operation of document.operations) findings.push(...operationFindings(file, document, operation, contracts));
+  for (const { file, text, line, column } of documents) {
+    const entries = documentFindings(file, text, contracts);
+    findings.push(...entries.map((entry) => line ? { ...entry, line, column } : entry));
   }
   return findings;
 }

package/runtime/scripts/hfs/rules/fe-stack.mjs

@@ -13,6 +13,8 @@ import { DEPENDENCY_SECTIONS } from './fe-no-tests.mjs';
 import { editionRuleParams } from '../edition-slots.mjs';
 
 export const FE_STACK_FORBIDDEN = 'FE_STACK_FORBIDDEN';
+export const FE_STACK_UNLISTED = 'FE_STACK_UNLISTED';
+export const FE_STACK_CORE_MISSING = 'FE_STACK_CORE_MISSING';
 const CATALOG_FILE = new URL('../../../knowledge/hfs/fe-stack.yaml', import.meta.url);
 const PACKAGE_JSON = /(?:^|\/)package\.json$/;
 const APP_ROOT_MANIFEST = 'package.json';
@@ -69,3 +71,58 @@ export function feStackFindings({ repoRoot, files, repo, manifest }) {
   const manifests = files.filter((file) => !file.includes('node_modules/') && (atRoot ? file === APP_ROOT_MANIFEST : PACKAGE_JSON.test(file)));
   return manifests.flatMap((rel) => manifestFindings(repoRoot, rel, skip));
 }
+
+/** R288 uses the same catalog as the scaffold, including tools installed once at the app root. */
+function stackCatalog() {
+  const catalog = parseYaml(fs.readFileSync(CATALOG_FILE, 'utf8'));
+  const allowed = new Set();
+  const core = new Map();
+  for (const concern of catalog.concerns) {
+    const rootTool = ['codegen', 'lint'].includes(concern.id);
+    for (const name of concern.packages ?? []) {
+      allowed.add(name);
+      if (concern.tier === 'core') core.set(name, { concern: concern.id, rootTool: rootTool || ['typescript', 'tailwindcss'].includes(name) });
+    }
+  }
+  return { allowed, core };
+}
+
+const dependenciesOf = pkg => new Set(DEPENDENCY_SECTIONS.flatMap(section => Object.keys(pkg?.[section] ?? {})));
+
+function extraPackages(declaration) {
+  const entries = declaration?.sides?.fe?.extraPackages ?? declaration?.extraPackages ?? declaration?.fe?.extraPackages ?? [];
+  return new Set((Array.isArray(entries) ? entries : []).filter(entry => typeof entry?.name === 'string'
+    && typeof entry.reason === 'string' && entry.reason.trim()).map(entry => entry.name));
+}
+
+function unlistedFindings(rel, pkg, allowed, extras, workspaces) {
+  const findings = [];
+  for (const section of DEPENDENCY_SECTIONS) for (const name of Object.keys(pkg?.[section] ?? {})) {
+    if (allowed.has(name) || extras.has(name) || workspaces.has(name) || forbiddenPackages().has(name)) continue;
+    findings.push(found(FE_STACK_UNLISTED, rel, `${rel} ${section} declares ${name}, absent from knowledge/hfs/fe-stack.yaml; add a canonical concern or declare sides.fe.extraPackages with its name and a nonempty reason in hfs.json`, { section, dependency: name }));
+  }
+  return findings;
+}
+
+/** Closed FE catalog and core presence over the front-end side (the mixed root also holds BE tools). */
+export function feStackAllowlistFindings({ repoRoot, files, all = files, repo, inScope = () => true }) {
+  if (repo.profile !== 'fe' || repo.kind === 'runtime') return [];
+  const declaration = readJson(repoRoot, '../hfs.json') ?? repo;
+  const manifests = all.filter(file => PACKAGE_JSON.test(file) && !file.includes('node_modules/'));
+  const packages = new Map(manifests.map(file => [file, readJson(repoRoot, file)]));
+  const workspaces = new Set([...packages].filter(([file]) => file.startsWith('packages/')).map(([, pkg]) => pkg?.name).filter(Boolean));
+  const { allowed, core } = stackCatalog();
+  const extras = extraPackages(declaration);
+  const findings = [...packages].filter(([file]) => inScope(file)).flatMap(([file, pkg]) => unlistedFindings(file, pkg, allowed, extras, workspaces));
+  const rootTools = dependenciesOf(readJson(repoRoot, '../package.json'));
+  for (const app of repo.apps ?? []) {
+    if (app.kind !== 'next' || app.name === 'landing') continue;
+    const rel = `apps/${app.name}/package.json`;
+    const installed = dependenciesOf(packages.get(rel));
+    for (const [name, entry] of core) {
+      if (installed.has(name) || (entry.rootTool && rootTools.has(name))) continue;
+      findings.push(found(FE_STACK_CORE_MISSING, rel, `${rel} lacks core package ${name} for ${entry.concern} in knowledge/hfs/fe-stack.yaml; declare it ${entry.rootTool ? 'in the app root devDependencies or this workspace' : 'in this product workspace'}`, { dependency: name, concern: entry.concern }));
+    }
+  }
+  return findings;
+}

package/runtime/scripts/hfs/rules/feature-files.mjs

@@ -0,0 +1,28 @@
+// feature-files.mjs - R292: a feature stays within ruleParams.featureFiles tracked files, in lite and full.
+import { posixPath } from '../../lib/path-key.mjs';
+import { found } from './read.mjs';
+
+export const HFS_FEATURE_FILE_BUDGET = 'HFS_FEATURE_FILE_BUDGET';
+
+/** Feature owners come from the slot manifest: BE trigger roots (including cli) and FE feature owners. */
+const isFeature = (slot) => slot?.owner === true && slot.tier === 'feature' && (slot.trigger !== undefined || slot.id === 'fe.feature');
+
+/** Count the complete tracked tree, even when a per-file check is scoped to only part of a feature. */
+export function featureFileFindings({ files, all = files, repo, resolver, isRoot = repo.profile === 'app' }) {
+  // The app check invokes this again for each side, with that side's paths and edition-aware parameters.
+  if (isRoot || !['be', 'fe'].includes(repo.profile)) return [];
+  const max = resolver.ruleParams().featureFiles ?? 250;
+  const counts = new Map();
+  for (const file of new Set(all.map(posixPath))) {
+    if (!file || file.endsWith('/')) continue;
+    const owner = resolver.ownerOf(file);
+    if (!owner || !isFeature(resolver.slot(owner.slot))) continue;
+    counts.set(owner.root, (counts.get(owner.root) ?? 0) + 1);
+  }
+  return [...counts].filter(([, count]) => count > max).map(([root, count]) => found(
+    HFS_FEATURE_FILE_BUDGET,
+    root,
+    `${root} has ${count} tracked files, over the feature budget of ${max}; split it by product capability`,
+    { files: count, max },
+  ));
+}

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

@@ -6,13 +6,14 @@
 // Over the whole app (the root scope, app-relative paths: the one package.json and the be contract snapshots sit outside the fe side):
 //   FE_WIRE_GENERATED (R52)     wire types come from the be contract snapshots the fe side reads in place (its declared reads,
 //                               `be/contracts/`): the root package.json declares the `codegen` script, and each fe app's generated
-//                               types on disk (`modules/api/__generated__/`, never tracked) are not older than any snapshot
+//                               types on disk (`modules/api/graphql/__generated__/`, never tracked) record the schema digest
 //   FE_I18N_PLACEMENT (R59)     `next-intl` is a dependency of an fe workspace (an fe app manifest, or a shared i18n package under fe/packages/)
 // 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';
+import { createHash } from 'node:crypto';
+import { found, readJson, readText } from './read.mjs';
 import { byCodeUnit } from '../../lib/list.mjs';
 
 const WIRE_GENERATED = 'FE_WIRE_GENERATED';
@@ -21,7 +22,7 @@ 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;
+export const WIRE_SCHEMA_STAMP = '.schema-sha256';
 
 /** Every leaf key of a parsed catalog as a dotted path. */
 function catalogKeys(value, prefix = '') {
@@ -30,40 +31,58 @@ function catalogKeys(value, prefix = '') {
   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;
+/** Digest protocol for codegen: sorted app-relative schema path, NUL, LF-normalized source, NUL. */
+export function wireSchemaDigest(repoRoot, snapshots) {
+  const hash = createHash('sha256');
+  for (const snapshot of [...snapshots].sort(byCodeUnit)) {
+    let source;
+    try { source = fs.readFileSync(path.join(repoRoot, snapshot), 'utf8'); } catch { return null; }
+    hash.update(`${snapshot}\0${source.replace(/\r\n/g, '\n')}\0`);
+  }
+  return hash.digest('hex');
+}
+
+/** Generated output is untracked, so inspect disk; the digest sidecar alone is not generated wire types. */
+function hasGeneratedTypes(directory) {
+  let entries;
+  try { entries = fs.readdirSync(directory, { withFileTypes: true }); } catch { return false; }
+  return entries.some((entry) => entry.isDirectory() ? hasGeneratedTypes(path.join(directory, entry.name)) : entry.isFile() && entry.name.endsWith('.ts'));
 }
 
 const scriptsOf = (repoRoot, file) => readJson(repoRoot, file)?.scripts ?? {};
 
-/** R52 over the app: the codegen script of the root and the age of each fe app's generated types against the be snapshots. */
-function wireFindings({ repoRoot, files, apps, reads }) {
-  const snapshots = files.filter((file) => reads.some((read) => file.startsWith(read)));
+function wireDigestProblem(digest, stamped) {
+  if (digest === null) return 'cannot be verified against unreadable contract snapshots';
+  if (!/^[0-9a-f]{64}$/.test(stamped ?? '')) return 'has no valid schema digest recorded by codegen';
+  if (stamped !== digest) return 'records a different schema digest from the contract snapshots';
+  return null;
+}
+
+function appWireFindings({ repoRoot, files, app, snapshots, digest }) {
+  const graphql = `fe/apps/${app}/src/modules/api/graphql/`;
+  const generated = `${graphql}__generated__`;
+  if (!hasGeneratedTypes(path.join(repoRoot, generated))) {
+    const operations = files.some((file) => file.startsWith(graphql) && /^(?:(?:queries|mutations)\/[^/]+\.ts|(?!(?:__generated__|node_modules)\/).*\.graphql)$/.test(file.slice(graphql.length)));
+    if (operations) return [found(WIRE_GENERATED, generated, `${app} keeps GraphQL operations but ${generated} has no generated wire types; run \`npm run codegen\``, { app })];
+    return [];
+  }
   if (!snapshots.length) return [];
+  const stamped = readText(repoRoot, `${generated}/${WIRE_SCHEMA_STAMP}`)?.trim();
+  const problem = wireDigestProblem(digest, stamped);
+  if (problem === null) return [];
+  return [found(WIRE_GENERATED, generated, `${generated} ${problem}; run \`npm run codegen\` so its wire types and ${WIRE_SCHEMA_STAMP} match the schema`, { app, snapshots })];
+}
+
+/** R52's tracked-source obligations, plus generated local artifacts in the workspace phase. */
+function wireFindings({ repoRoot, files, apps, reads, phase }) {
+  const snapshots = files.filter((file) => file.endsWith('/schema.graphql') && reads.some((read) => file.startsWith(read)));
   const findings = [];
-  if (typeof scriptsOf(repoRoot, 'package.json').codegen !== 'string') findings.push(found(WIRE_GENERATED, 'package.json', `the app keeps contract snapshots (${reads.join(', ')}) but its package.json declares no \`codegen\` script; wire types are generated from the snapshots, never typed by hand`));
-  for (const app of apps) {
-    const generated = `fe/apps/${app}/src/modules/api/__generated__`;
-    const built = newestBelow(path.join(repoRoot, generated));
-    if (built === null) continue;
-    for (const snapshot of snapshots) {
-      let changed;
-      try { changed = fs.statSync(path.join(repoRoot, snapshot)).mtimeMs; } catch { continue; }
-      if (built + STALE_MS < changed) findings.push(found(WIRE_GENERATED, generated, `${generated} is older than ${snapshot}; run \`npm run codegen\` so the wire types match the contract snapshot`, { app, snapshot }));
-    }
-  }
+  if (snapshots.length && typeof scriptsOf(repoRoot, 'package.json').codegen !== 'string') findings.push(found(WIRE_GENERATED, 'package.json', `the app keeps contract snapshots (${reads.join(', ')}) but its package.json declares no \`codegen\` script; wire types are generated from the snapshots, never typed by hand`));
+  // A clean checkout has no ignored build artifacts. The runtime's source-render check judges their tracked inputs;
+  // the ordinary app check/lint judges the generated output after the app's codegen step (also required by L4).
+  if (phase === 'source') return findings;
+  const digest = snapshots.length ? wireSchemaDigest(repoRoot, snapshots) : null;
+  findings.push(...apps.flatMap((app) => appWireFindings({ repoRoot, files, app, snapshots, digest })));
   return findings;
 }
 
@@ -74,7 +93,7 @@ function intlDependencyFindings({ repoRoot, files }) {
   return workspaces.some(declares) ? [] : [found(I18N_PLACEMENT, 'package.json', 'no fe workspace depends on next-intl (an fe app or a shared fe package declares it); every fe app uses next-intl with the [locale] segment')];
 }
 
-function placementFindings({ repoRoot, app, tracked }) {
+function placementFindings({ app, tracked }) {
   const base = `apps/${app}`;
   const findings = [];
   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 }));
@@ -118,9 +137,9 @@ export function frontendFindings({ repoRoot, files, repo }) {
   return repo.apps.filter((a) => a.kind === 'next').flatMap((a) => [placementFindings, catalogFindings].flatMap((check) => check({ repoRoot, app: a.name, tracked: files })));
 }
 
-/** The app's front-end findings that read the root (R52, R59's dependency); `repoRoot` is the app root, `files` app-relative. */
-export function appFrontendFindings({ repoRoot, files, repo }) {
+/** The app's front-end findings that read the root; workspace checks include R52's ignored local artifacts. */
+export function appFrontendFindings({ repoRoot, files, repo, phase = 'workspace' }) {
   const apps = repo.sides.fe.apps.filter((a) => a.kind === 'next').map((a) => a.name);
   // The snapshots are the paths the fe side declares it reads of the be side (hfs.json sides.fe.reads: be/contracts/).
-  return [...wireFindings({ repoRoot, files, apps, reads: repo.sides.fe.reads }), ...intlDependencyFindings({ repoRoot, files })];
+  return [...wireFindings({ repoRoot, files, apps, reads: repo.sides.fe.reads, phase }), ...intlDependencyFindings({ repoRoot, files })];
 }

package/runtime/scripts/hfs/rules/integration-specs.mjs

@@ -225,8 +225,9 @@ const MISSING_PARTS = Object.freeze({
   outage: 'drive an outage through the world: world.infra.<service>, world.fake.<name>.failNext(...), world.apps.<peer>.during(...) or world.interruptDatabase(...)',
 });
 
-/** The findings of R112 over the tracked paths `files` of the app at `repoRoot`. */
-export function integrationSpecFindings({ repoRoot, files }) {
+/** The full-edition test-world proofs of R112; lite owns its integration lane through R284. */
+export function integrationSpecFindings({ repoRoot, files, repo }) {
+  if (repo?.edition === 'lite') return [];
   const integrations = files.map((file) => CONFIG_FILE.exec(file)).filter(Boolean).map(([, side, provider]) => ({ side, provider, folder: `${side}src/modules/integrations/${provider}` }));
   if (integrations.length === 0) return [];
   const ts = typescriptFor(repoRoot);

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

@@ -0,0 +1,62 @@
+// R283: the product's removed vocabulary is declared once in hfs.json lexicon.removed.
+// Source, identifiers, comments and docs obey it in both editions; the declaration itself is not a use.
+import path from 'node:path';
+import { escapeRegExp } from '../../lib/regex.mjs';
+import { found, readJson, readText } from './read.mjs';
+
+export const HFS_APP_LEXICON = 'HFS_APP_LEXICON';
+const SOURCE_OR_DOC = /\.(?:[cm]?[jt]sx?|css|scss|sass|vue|svelte|gql|graphql|sql|sh|md|mdx|rst|adoc|txt)$/i;
+const SOURCE_JSON = /(?:^|\/)(?:src|messages|locales)\/.*\.json$/i;
+const OUTSIDE = /(?:^|\/)(?:node_modules|\.git|dist|build|secrets)\/|(?:^|\/)(?:secrets?|secret\.env)(?:\.|$)/i;
+const LETTER_OR_NUMBER = /[\p{L}\p{N}]/u;
+const LOWER = /\p{Ll}/u;
+const UPPER = /\p{Lu}/u;
+
+// A whole word also forms one segment of camelCase/PascalCase, a kebab name or a SCREAMING_SNAKE identifier.
+function boundary(text, at) {
+  const left = text[at - 1];
+  const right = text[at];
+  return !left || !right || !LETTER_OR_NUMBER.test(left) || !LETTER_OR_NUMBER.test(right)
+    || (LOWER.test(left) && UPPER.test(right))
+    || (UPPER.test(left) && UPPER.test(right) && LOWER.test(text[at + 1] ?? ''));
+}
+
+function removedWords(repoRoot, repo) {
+  if (typeof repoRoot !== 'string') return [];
+  // Resolved side declarations contain the edition and slots, so read product metadata from the root declaration.
+  const root = repo.profile === 'be' || repo.profile === 'fe' ? path.dirname(repoRoot) : repoRoot;
+  const lexicon = repo.lexicon ?? readJson(root, 'hfs.json')?.lexicon;
+  return Array.isArray(lexicon?.removed) ? [...new Set(lexicon.removed.filter((word) => typeof word === 'string' && word.trim()).map((word) => word.trim()))] : [];
+}
+
+function wordFindings(file, text, word) {
+  const matches = text.matchAll(new RegExp(escapeRegExp(word), 'giu'));
+  const findings = [];
+  const reported = new Set();
+  for (const match of matches) {
+    const start = match.index;
+    const end = start + match[0].length;
+    if (!boundary(text, start) || !boundary(text, end)) continue;
+    const line = text.slice(0, start).split('\n').length;
+    if (reported.has(line)) continue;
+    reported.add(line);
+    const column = start - text.lastIndexOf('\n', start - 1);
+    findings.push(found(HFS_APP_LEXICON, file, `${file}:${line} uses removed product word ${JSON.stringify(word)}; replace it with the current product vocabulary`, { line, column, word }));
+  }
+  return findings;
+}
+
+/** Removed product words in the tracked source and docs of this root/side scope, once per word and line. */
+export function lexiconFindings({ repoRoot, files, repo, inScope = () => true }) {
+  if (repo.kind === 'runtime' || !['lite', 'full'].includes(repo.edition ?? 'full')) return [];
+  const words = removedWords(repoRoot, repo);
+  if (!words.length) return [];
+  const findings = [];
+  for (const file of files) {
+    if (!inScope(file) || OUTSIDE.test(file) || !(SOURCE_OR_DOC.test(file) || SOURCE_JSON.test(file))) continue;
+    const text = readText(repoRoot, file);
+    if (text === null) continue;
+    for (const word of words) findings.push(...wordFindings(file, text, word));
+  }
+  return findings;
+}

package/runtime/scripts/hfs/rules/lite-proof-lane.mjs

@@ -0,0 +1,89 @@
+// lite-proof-lane.mjs - R284: declared patterns in lite prove their scenarios in integration specs.
+// Full keeps its existing e2e/integration proof checks. R155 owns BE_PATTERN_SPEC_MISSING in both editions.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadSlotManifest, ruleParams } from '../slots.mjs';
+import { loadTypescript } from '../../lib/package-at.mjs';
+import { literalText } from '../../lib/ts-ast.mjs';
+import { found, readText } from './read.mjs';
+
+const LITE_PROOF_LANE_MISSING = 'BE_LITE_PROOF_LANE_MISSING';
+const PATTERN_SPEC_MISSING = 'BE_PATTERN_SPEC_MISSING';
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const INTEGRATION_SPEC = /^be\/src\/tests\/integration\/.+\.integration-spec\.ts$/;
+const PATTERNS = new Set(['event-bus', 'queue', 'webhooks', 'realtime', 'fenced-job', 'projection', 'saga']);
+// Fallback saga scenarios until the shared manifest provides its scenario table.
+const SAGA_SCENARIOS = ['compensation-on-failure', 'step-order', 'state-version-fences', 'consumer-dedupes'];
+
+/** A disabled test/suite must not contribute its own title or any nested test titles. */
+function disabledCall(ts, node) {
+  let callee = node.expression;
+  let disabled = false;
+  while (ts.isPropertyAccessExpression(callee) || ts.isCallExpression(callee)) {
+    if (ts.isPropertyAccessExpression(callee) && ['skip', 'todo'].includes(callee.name.text)) disabled = true;
+    callee = callee.expression;
+  }
+  return ts.isIdentifier(callee) && (callee.text === 'xdescribe'
+    || (disabled && ['it', 'test', 'describe'].includes(callee.text)));
+}
+
+/** A test callback is an inline function or a reference to one, rather than a missing/placeholder value. */
+function hasCallback(ts, node) {
+  const callback = node.arguments[1];
+  return callback && (ts.isArrowFunction(callback) || ts.isFunctionExpression(callback)
+    || (ts.isIdentifier(callback) && callback.text !== 'undefined') || ts.isPropertyAccessExpression(callback));
+}
+
+/** Add scenario ids from literal it/test titles with callbacks; disabled suites and source text provide no proof. */
+function addScenarios(ts, source, proven) {
+  const visit = (node) => {
+    if (ts.isCallExpression(node) && disabledCall(ts, node)) return;
+    if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)
+      && ['it', 'test'].includes(node.expression.text) && hasCallback(ts, node)) {
+      const title = literalText(ts, node.arguments[0]);
+      const colon = title?.indexOf(':') ?? -1;
+      if (colon > 0) proven.add(title.slice(0, colon));
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+}
+
+/** Only tracked, readable integration specs belong to lite's proof lane. */
+function integrationProof(ts, repoRoot, files) {
+  const proven = new Set();
+  const specs = [];
+  for (const file of files) {
+    if (!INTEGRATION_SPEC.test(file)) continue;
+    const text = readText(repoRoot, file);
+    if (text === null) continue;
+    specs.push(file);
+    if (ts) addScenarios(ts, ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true), proven);
+  }
+  return { specs, proven };
+}
+
+/** Findings of R284 and R155 at the app root; side passes must not duplicate them. */
+export function liteProofLaneFindings({ repoRoot, files, all = files, repo, manifest }) {
+  if (repo.edition !== 'lite' || !repo.sides?.be) return [];
+  const patterns = [...new Set(repo.sides.be.patterns ?? [])].filter((pattern) => PATTERNS.has(pattern));
+  if (patterns.length === 0) return [];
+  const scenarios = ruleParams(manifest ?? loadSlotManifest(), 'be', 'lite').patternScenarios ?? {};
+  const ts = loadTypescript(repoRoot, HERE);
+  const { specs, proven } = integrationProof(ts, repoRoot, all);
+  const findings = [];
+  if (specs.length === 0) {
+    const declared = patterns.map((pattern) => `\`${pattern}\``).join(', ');
+    findings.push(found(LITE_PROOF_LANE_MISSING, 'hfs.json',
+      `Lite declares ${declared} but has no tracked integration spec in be/src/tests/integration; add *.integration-spec.ts with the declared patterns' scenario titles.`, { patterns }));
+  }
+  for (const pattern of patterns) {
+    const required = scenarios[pattern] ?? (pattern === 'saga' ? SAGA_SCENARIOS : []);
+    for (const scenario of required) {
+      const id = `${pattern}/${scenario}`;
+      if (!proven.has(id)) findings.push(found(PATTERN_SPEC_MISSING, 'hfs.json',
+        `The lite pattern \`${pattern}\` is declared but no integration spec in be/src/tests/integration holds a test titled \`${id}: ...\`; prove this scenario in the lite integration lane.`, { pattern, scenario: id }));
+    }
+  }
+  return findings;
+}

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

@@ -183,10 +183,23 @@ function workspaceMissingDependencies(repoRoot, files, folder, names, ts) {
   const pkg = readJson(repoRoot, manifest);
   if (!pkg) return [];
   const missing = undeclaredImports(repoRoot, files, folder, pkg, declaredIn(pkg), ts);
-  return [...missing].sort(byCodeUnit).map(([name, file]) => {
+  const findings = [...missing].sort(byCodeUnit).map(([name, file]) => {
     const declaration = names.get(name) ? `declare the workspace package ${name} as "*"` : `declare ${name} in the dependencies of ${manifest} (one version across the workspace, R14)`;
     return found(MONO_WORKSPACE_DEP, manifest, `${file} imports ${name}, which ${manifest} does not declare; ${declaration}.`, { dependency: name, importedBy: file });
   });
+  return [...findings, ...workspaceVersionFindings(manifest, pkg, names)];
+}
+
+/** Every declaration of a sibling workspace uses npm's local workspace version, in every dependency section. */
+function workspaceVersionFindings(manifest, pkg, names) {
+  const findings = [];
+  for (const section of DEP_SECTIONS) {
+    for (const [name, version] of Object.entries(pkg[section] ?? {})) {
+      if (!names.has(name) || name === pkg.name || version === '*') continue;
+      findings.push(found(MONO_WORKSPACE_DEP, manifest, `${manifest} declares sibling workspace ${name} as ${JSON.stringify(version)} in ${section}; declare the workspace package as "*".`, { dependency: name, section, version }));
+    }
+  }
+  return findings;
 }
 
 /** R146: what each fe workspace imports, it declares; the root declares no workspace package. */

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

@@ -7,6 +7,7 @@
 // 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';
+import { isRuntimeExampleApp } from '../../lib/runtime-example.mjs';
 
 const CI_MISSING_CANON = 'HFS_CI_MISSING_CANON';
 const CI_FILE = '.github/workflows/ci.yml';
@@ -15,6 +16,7 @@ const RUN_PREFIX = /^\s*(?:-\s+)?run:/;
 const NPX_PREFIX = /^npx\s+(?:(?:--no-install|-y)\s+)?/;
 const LINT_COMMAND = /^(?:@starci\/cli(?:@(\S+))?|starci)\s+app\s+lint/;
 const NPM_RUN_PREFIX = 'npm run ';
+const EXAMPLE_RUN_PREFIX = 'node node_modules/@starci/hfs/runtime/scripts/hfs/example-secrets.mjs --run . -- ';
 const SCRIPT_NAME = /^[\w:.-]+/;
 const ARGS_SEPARATOR = /^\s+--\s+/;
 const LINE_TERMINATOR = /[\n\r\u2028\u2029]/;
@@ -72,6 +74,9 @@ function expanded(command, scripts) {
   return run.args ? `${scripts[run.script]} ${run.args}` : scripts[run.script];
 }
 
+/** 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. */
 export function pipelineFindings({ repoRoot, files, pins }) {
   const findings = [];
@@ -79,7 +84,9 @@ export function pipelineFindings({ repoRoot, files, pins }) {
   const ci = files.includes(CI_FILE) ? readText(repoRoot, CI_FILE) : null;
   if (ci !== null) {
     const scripts = readJson(repoRoot, 'package.json')?.scripts ?? {};
-    const lints = commandsOf(ci).flatMap((command) => chainedCommands(expanded(command, scripts))).map(lintCommandOf).filter(Boolean);
+    const commands = commandsOf(ci);
+    const selected = isRuntimeExampleApp(repoRoot) ? commands.map(exampleCommandOf) : commands;
+    const lints = selected.flatMap((command) => chainedCommands(expanded(command, scripts))).map(lintCommandOf).filter(Boolean);
     if (!lints.length) findings.push(found(CI_MISSING_CANON, CI_FILE, `${CI_FILE} has no step that runs \`starci app lint\` (directly or through \`npm run lint\`); CI runs the one lint entry, which includes the repository check`, { step: 'starci app lint' }));
     else if (pinned && !lints.some((match) => match.version === undefined || match.version === pinned)) {
       findings.push(found(CI_MISSING_CANON, CI_FILE, `${CI_FILE} runs starci app lint at ${lints[0].version}, but ${hfsPackage} is pinned at ${pinned}; run the pinned version`, { step: 'starci app lint', pinned }));