@starci/hfs 2.0.2 → 4.0.0

package/runtime/scripts/lib/hfs-check.mjs

@@ -1,9 +1,9 @@
-// hfs-check.mjs - the HFS repository check, behind `hfs check | init | explain` (packages/hfs) and reusable by any
-// runtime check. It reads three things and nothing else: the repository's hfs.json, the slot manifest
+// hfs-check.mjs - the HFS app check, behind `hfs 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/lib/hfs-slots.mjs) and the pins (knowledge/hfs/canon-pins.yaml). It never
 // writes to the repository it inspects.
 //
-// checkRepo() answers, for the tracked paths of one repository (git ls-files):
+// checkRepo() answers, for the tracked paths of one app (git ls-files), per scope (the app root and each side folder):
 //   HFS_SLOT_UNDECLARED              a tracked path no slot owns (the nearest slot is named)
 //   HFS_SLOT_NOT_ENABLED          a tracked path in an opt-in slot the repository did not declare
 //   HFS_SLOT_AMBIGUOUS            two slots of equal specificity own the path (a manifest gap, reported not guessed)
@@ -26,6 +26,7 @@
 //   HFS_REPO_LOCAL_CHECK          (R103, hfs-rules/repo-local-checks.mjs) a local eslint rule or plugin, a `check-*` script, a relative import in eslint.config
 //   HFS_LINT_SUPPRESSION_FILE     (R104, hfs-rules/lint-suppression.mjs) an eslint suppressions file, script or option
 //   HFS_PROOF_COMMAND_FILE_MISSING (R105, hfs-rules/proof-commands.mjs) a .starciwork proof command that runs a file the repository does not hold
+//   HFS_PEER_INTEGRATION_MISSING  (R111, hfs-rules/peer-integrations.mjs) the app root package.json lacks the runtime peer a driver integration needs
 //   FE_WIRE_GENERATED, FE_I18N_PLACEMENT, FE_I18N_CATALOG   (R52, R59, R60, hfs-rules/frontend.mjs) the front-end tree of each app
 //   HFS_GITIGNORE_BLOCK_DRIFT, HFS_SONAR_CONFIG   (R04, R11) produced by packages/hfs/sync/managed.mjs, which renders the templates
 //   HFS_FORMAT                    (R19) produced by packages/hfs/sync/format.mjs, which runs the repository's own prettier
@@ -45,22 +46,24 @@ import path from 'node:path';
 import { skillRoot } from '../../engine/runtime-root.mjs';
 import { ARCHITECTURE_RULE_IDS, checkArchitecture } from '../checks/architecture/index.mjs';
 import { parseYaml } from '../../engine/yaml.mjs';
-import { HFS_DECLARATION_FILE, HfsSlotsError, createSlotResolver, loadSlotManifest, readRepoDeclaration, resolveRepoDeclaration } from './hfs-slots.mjs';
+import { APP_SCOPE, HFS_DECLARATION_FILE, appRelativeMessages, HfsSlotsError, SIDES, createSlotResolver, loadSlotManifest, readRepoDeclaration, resolveRepoDeclaration } from './hfs-slots.mjs';
 import { allowsFile } from './hfs-allows.mjs';
-import { isDir } from './fs-kind.mjs';
 import { gitOutput } from './git.mjs';
 import { posixPath } from './path-key.mjs';
 import { readTree, treeFacts, untrackedEntries } from './hfs-tree.mjs';
 import { contractFindings } from './hfs-rules/contract.mjs';
 import { depFindings } from './hfs-rules/deps.mjs';
-import { frontendFindings } from './hfs-rules/frontend.mjs';
+import { appFrontendFindings, frontendFindings } from './hfs-rules/frontend.mjs';
 import { lintSuppressionFindings } from './hfs-rules/lint-suppression.mjs';
+import { peerIntegrationFindings } from './hfs-rules/peer-integrations.mjs';
 import { pipelineFindings } from './hfs-rules/pipeline.mjs';
 import { proofCommandFindings } from './hfs-rules/proof-commands.mjs';
 import { repoLocalCheckFindings } from './hfs-rules/repo-local-checks.mjs';
 import { readJson } from './hfs-rules/read.mjs';
-import { secretFindings, slotOwnsSecrets } from './hfs-rules/secrets.mjs';
-import { specPlacementFindings } from './hfs-rules/spec-placement.mjs';
+import { secretFindings } from './hfs-rules/secrets.mjs';
+import { pathFindings } from './hfs-path-findings.mjs';
+import { onLintSurface } from '../checks/architecture/surface.mjs';
+import { checkAppRoot, trackedTreeView } from '../checks/architecture/hfs.mjs';
 import { stacksFindings } from './hfs-rules/stacks.mjs';
 import { testTopologyFindings } from './hfs-rules/test-topology.mjs';
 import { feNoTestsFindings, isFeTestPath } from './hfs-rules/fe-no-tests.mjs';
@@ -68,11 +71,11 @@ import { feNoTestsFindings, isFeTestPath } from './hfs-rules/fe-no-tests.mjs';
 export const CANON_PINS_FILE = 'knowledge/hfs/canon-pins.yaml';
 export const FAILURE_CODES_FILE = 'modules/kernel/failure-codes.yaml';
 /**
- * The codes `hfs check` and `hfs init` report when they cannot judge (an unreadable repository, a refused declaration or
- * manifest, an init that cannot proceed): infrastructure refusals, never obligations, so no rule of knowledge/hfs/rules.yaml owns them.
+ * The codes `hfs check` reports when it cannot judge (an unreadable repository, a refused declaration or manifest, a missing
+ * formatter): infrastructure refusals, never obligations, so no rule of knowledge/hfs/rules.yaml owns them.
  */
 export const REFUSAL_CODES = Object.freeze([
-  'HFS_INIT_EXISTS', 'HFS_INIT_UNDETECTED', 'HFS_REPO_UNREADABLE',
+  'HFS_REPO_UNREADABLE',
   'HFS_DECLARATION_INVALID', 'HFS_MANIFEST_MAJOR_MISMATCH', 'HFS_MANIFEST_INVALID', 'HFS_FORMAT_TOOL_MISSING',
 ]);
 /** 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. */
@@ -81,7 +84,7 @@ export const CHECK_CODES = Object.freeze([
   'HFS_SLOT_REQUIRED_MISSING', 'HFS_MIN_INSTANCES', 'HFS_CANON_PIN_DRIFT', 'HFS_SIZE_SOFT_BACKLOG', 'BE_SOURCE_FORM',
   'HFS_MANAGED_FILE_DRIFT', 'HFS_TOOL_CONFIG_LOCAL', 'HFS_RULE_OFF_WITHOUT_REPLACEMENT', 'HFS_TS_STRICT',
   'HFS_PLAINTEXT_SECRET', 'HFS_STACKS_SHAPE', 'HFS_CI_MISSING_CANON', 'HFS_DEP_VERSION_SKEW', 'HFS_CONTRACT_SNAPSHOT_DRIFT',
-  'BE_TEST_TOPOLOGY', 'BE_SPEC_PLACEMENT', 'HFS_REPO_LOCAL_CHECK', 'HFS_LINT_SUPPRESSION_FILE', 'HFS_PROOF_COMMAND_FILE_MISSING', 'FE_NO_TESTS', 'FE_WIRE_GENERATED', 'FE_I18N_PLACEMENT', 'FE_I18N_CATALOG',
+  'BE_TEST_TOPOLOGY', 'BE_SPEC_PLACEMENT', 'HFS_REPO_LOCAL_CHECK', 'HFS_LINT_SUPPRESSION_FILE', 'HFS_PROOF_COMMAND_FILE_MISSING', 'HFS_PEER_INTEGRATION_MISSING', 'FE_NO_TESTS', 'FE_WIRE_GENERATED', 'FE_I18N_PLACEMENT', 'FE_I18N_CATALOG',
   'HFS_GITIGNORE_BLOCK_DRIFT', 'HFS_SONAR_CONFIG', 'HFS_FORMAT',
   'HFS_EMPTY_DIR', 'HFS_GHOST_TREE', 'HFS_UNTRACKED_ROOT_ENTRY',
   ...REFUSAL_CODES,
@@ -136,7 +139,8 @@ function pinFindings({ repoRoot, files, profile, pins, only }) {
     let pkg;
     try { pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, file), 'utf8')); } catch { continue; }
     for (const [name, pin] of Object.entries(pins)) {
-      if (pin.side !== 'both' && pin.side !== profile) continue;
+      // The app root's one package.json carries the pins of both sides.
+      if (profile !== APP_SCOPE && pin.side !== 'both' && pin.side !== profile) continue;
       for (const section of DEP_SECTIONS) {
         const spec = pkg[section]?.[name];
         if (spec === undefined) continue;
@@ -148,53 +152,6 @@ function pinFindings({ repoRoot, files, profile, pins, only }) {
   return findings;
 }
 
-const KEBAB = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-const SOURCE_ROOT = /^(?:src|apps)\//;
-const FREE_NAMES = new Set(['index.ts', 'main.ts']);
-const PLAIN_ENTRY = /^<[a-z][a-z0-9-]*>.ts$/;
-
-/**
- * BE_SOURCE_FORM (R89): every tracked src/ or apps/ TypeScript file of a back end is index.ts, main.ts, a migration of
- * be.persistence, or <kebab-name>.<suffix>.ts with <suffix> in the closed vocabulary ruleParams.be.suffixes (a name such
- * as api.composition.spec.ts keeps its inner words kebab-case). A suffix of ruleParams.be.bannedSuffixes anywhere in the
- * name is refused by name. Paths no slot owns are HFS_SLOT_UNDECLARED's, not this code's.
- */
-function sourceFormFindings({ files, resolver }) {
-  const { suffixes, bannedSuffixes } = resolver.ruleParams();
-  // A suffix a slot names in its own file pattern (`*.builder.ts` of be.tests.fixtures.builders) is that slot's role: a file with it
-  // anywhere else is refused, so a builder cannot live beside a service or in the fixtures root.
-  const boundSuffixes = new Map();
-  for (const slot of resolver.slots()) {
-    const bound = /\*\.([a-z0-9-]+)\.ts$/.exec(slot.path ?? '')?.[1];
-    if (bound && suffixes.includes(bound)) boundSuffixes.set(bound, slot);
-  }
-  const findings = [];
-  for (const file of files) {
-    if (!file.endsWith('.ts') || !SOURCE_ROOT.test(file)) continue;
-    const c = resolver.classifyPath(file);
-    if (c.status !== 'owned' || c.tracking === 'ignored') continue;
-    const base = path.posix.basename(file);
-    if (FREE_NAMES.has(base)) continue;
-    // A literal file name the owning slot itself requires or allows (persistence/connection.ts, world/global-setup.ts) is its role.
-    const slot = resolver.slot(c.slot);
-    if ([...(slot?.requires ?? []), ...(slot?.allows ?? [])].some((entry) => entry === base)) continue;
-    // A slot whose `allows` holds a bare <name>.ts entry (be.tests.world.kit) names its files plainly, as platform/primitives does: kebab-case is the whole form.
-    const admitted = allowsFile(resolver, file);
-    if (admitted?.allowed && PLAIN_ENTRY.test(admitted.entry ?? '') && KEBAB.test(base.slice(0, -'.ts'.length))) continue;
-    if (c.slot === 'be.persistence' && path.posix.basename(path.posix.dirname(file)) === 'migrations') continue;
-    const parts = base.slice(0, -'.ts'.length).split('.');
-    const banned = parts.slice(1).find((part) => bannedSuffixes.includes(part));
-    if (banned) {
-      findings.push({ code: 'BE_SOURCE_FORM', level: 'error', path: file, suffix: banned, message: `${file}: the suffix .${banned} is banned; use a role from the closed suffix list (${suffixes.join(', ')})` });
-    } else if (boundSuffixes.has(parts.at(-1)) && parts.length >= 2 && boundSuffixes.get(parts.at(-1)).id !== c.slot) {
-      findings.push({ code: 'BE_SOURCE_FORM', level: 'error', path: file, suffix: parts.at(-1), message: `${file}: the suffix .${parts.at(-1)}.ts belongs to ${boundSuffixes.get(parts.at(-1)).path} only; move the file there` });
-    } else if (parts.length < 2 || !parts.every((part) => KEBAB.test(part)) || !suffixes.includes(parts.at(-1))) {
-      findings.push({ code: 'BE_SOURCE_FORM', level: 'error', path: file, message: `${file}: the name must be <kebab-name>.<suffix>.ts with a suffix from the closed list (${suffixes.join(', ')}), or index.ts, main.ts or a migration` });
-    }
-  }
-  return findings;
-}
-
 /** 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();
@@ -257,53 +214,24 @@ function treeFindings({ repoRoot, resolver }) {
   return findings;
 }
 
+/** A side-relative path (or null) as an app-relative one. */
+const onSide = (side, p) => (p ? path.posix.normalize(`${side}/${p}`) : p);
+
 /**
- * The check of one repository. `declaration` overrides hfs.json (a dry run over a repository that has none); `files`
- * overrides git ls-files (specs). `only` (a list of 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, untracked); they also do not run
- * over `files`, which is a dry run. `extraFindings` are findings another emitter produced for the same repository (the
- * managed files), judged and counted with this module's own. Returns {ok, profile, apps, manifest, tracked, findings,
- * counts}; a missing or invalid hfs.json is one HFS_DECLARATION_INVALID / HFS_MANIFEST_MAJOR_MISMATCH error finding, never
- * an exception.
+ * The findings of one scope: the app root (profile app; its own files, and the rules of the files only the root holds: the one
+ * package.json and lockfile, CI, hooks, .starciwork) or one side (profile be or fe; the side folder is `repoRoot` and every path is
+ * 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).
  */
-export function checkRepo({ repoRoot, root = skillRoot, declaration, files, only, extraFindings = [], tree = files === undefined, manifest = loadSlotManifest({ root }) }) {
-  const why = readWhy(root);
-  let repo;
-  try {
-    repo = declaration === undefined ? readRepoDeclaration(manifest, repoRoot) : resolveRepoDeclaration(manifest, declaration);
-  } catch (error) {
-    if (!(error instanceof HfsSlotsError) || !['HFS_DECLARATION_INVALID', 'HFS_MANIFEST_MAJOR_MISMATCH'].includes(error.code)) throw error;
-    const findings = withWhy([{ code: error.code, level: 'error', path: HFS_DECLARATION_FILE, message: error.message.replace(/^[A-Z_]+: /, ''), problems: error.details.problems }], why);
-    return { ok: false, repoRoot, manifest: manifest.version, profile: null, apps: [], tracked: 0, findings, counts: summarize(findings) };
-  }
-  const resolver = createSlotResolver(manifest, repo);
-  const tracked = files ?? trackedFiles(repoRoot);
-  const trackedSet = new Set(tracked);
-  const present = (p) => (p.endsWith('/') ? tracked.some((f) => f.startsWith(p)) : trackedSet.has(p));
-  const findings = [];
-  const scoped = only ? new Set(only) : null;
+function scopeFindings({ repoRoot, root, repo, resolver, files, all = files, scoped }) {
   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);
+  const present = (p) => (p.endsWith('/') ? all.some((f) => f.startsWith(p)) : trackedSet.has(p));
+  const findings = [];
+  const isRoot = repo.profile === APP_SCOPE;
 
-  for (const file of tracked) {
-    if (!inScope(file)) continue;
-    if (repo.profile === 'fe' && isFeTestPath(file)) continue;   // a test path of a front end is FE_NO_TESTS's, the one finding of that file
-    const c = resolver.classifyPath(file);
-    if (c.status === 'no-slot') {
-      findings.push({ code: 'HFS_SLOT_UNDECLARED', level: 'error', path: file, nearest: c.nearest, message: `${file} matches no slot${c.nearest ? `; nearest slot ${c.nearest.slot} (${c.nearest.pattern}), matched ${c.nearest.matchedPrefix || '.'} then expected ${c.nearest.expectedNext ?? 'nothing'}` : ''}` });
-    } else if (c.status === 'ambiguous') {
-      findings.push({ code: 'HFS_SLOT_AMBIGUOUS', level: 'error', path: file, candidates: c.candidates, message: `${file} is owned equally by ${c.candidates.map((x) => x.slot ?? x).join(', ')}` });
-    } else if (c.status === 'not-enabled') {
-      findings.push({ code: 'HFS_SLOT_NOT_ENABLED', level: 'error', path: file, slot: c.slot, message: `${file} belongs to ${c.slot}, an opt-in slot hfs.json neither lists in optionalSlots nor implies through an app kind` });
-    } else if (c.status === 'forbidden') {
-      const slot = resolver.slot(c.slot);
-      if (slotOwnsSecrets(slot)) continue;   // the secret scan reports the file (R06): one finding per file
-      const own = slot.rules?.includes('HFS_TOOL_CONFIG_LOCAL') ? 'HFS_TOOL_CONFIG_LOCAL' : 'HFS_FORBIDDEN_PRESENT';
-      findings.push({ code: own, level: 'error', path: file, slot: c.slot, goesTo: c.goesTo, message: `${file} is tracked but ${c.slot} is forbidden in the tree${c.goesTo ? `; it belongs at ${c.goesTo}` : ''}` });
-    } else if (c.tracking === 'ignored') {
-      findings.push({ code: 'HFS_TRACKED_MUST_BE_IGNORED', level: 'error', path: file, slot: c.slot, message: `${file} is tracked but ${c.slot} must be gitignored` });
-    }
-  }
+  findings.push(...pathFindings({ files: files.filter(inScope), resolver, profile: repo.profile }));
 
   const required = resolver.requiredPaths();
   const missing = new Set();
@@ -314,46 +242,104 @@ export function checkRepo({ repoRoot, root = skillRoot, declaration, files, only
     const app = appOf(p);
     findings.push({ code: 'HFS_SLOT_REQUIRED_MISSING', level: 'error', path: p, slot, via, ...(app ? { app } : {}), message: `${slot} requires ${p}${app ? ` (app ${app})` : ''}, which is not tracked` });
   };
-  for (const entry of required.paths) missingFile(entry.slot, entry.path, entry.via);
-  const instances = instancesOf(resolver, tracked);
+  // The app's own required paths; each side reports its own (the resolver of the app lists them too, with their side).
+  for (const entry of required.paths) if (!entry.side) missingFile(entry.slot, entry.path, entry.via);
+  const instances = instancesOf(resolver, files);
   for (const instance of instances) for (const p of requiredOf(resolver.slot(instance.slot), instance)) missingFile(instance.slot, p, 'requires');
-  for (const { slot, min, appKind } of required.minimums) {
-    if (appKind !== undefined) continue;     // an app-kind minimum is checked by requiredPaths (one path set per declared app)
+  for (const { slot, min, appKind, side } of required.minimums) {
+    if (appKind !== undefined || side) continue;     // an app-kind minimum is checked by requiredPaths (one path set per declared app)
     const count = instances.filter((i) => i.slot === slot).length;
     if (count < min) findings.push({ code: 'HFS_MIN_INSTANCES', level: 'error', path: resolver.slot(slot).path, slot, min, count, message: `${slot} needs at least ${min} instance${min === 1 ? '' : 's'} (${resolver.slot(slot).path}), found ${count}` });
   }
 
   const pins = readPins(root);
-  findings.push(...pinFindings({ repoRoot, files: tracked, profile: repo.profile, pins, only: scoped }));
+  findings.push(...pinFindings({ repoRoot, files, profile: repo.profile, pins, only: scoped }));
 
-  // The tree checks of the rules that read file content or configuration (hfs-rules/*): whole-repository, cheap, no tool run.
-  const secrets = secretFindings({ repoRoot, files: tracked.filter(inScope), resolver });
-  const declared = declaration === undefined ? readJson(repoRoot, 'hfs.json') : declaration;
-  if (repo.profile === 'be') findings.push(...sourceFormFindings({ files: tracked.filter(inScope), resolver }));
+  // The tree checks of the rules that read file content or configuration (hfs-rules/*): whole-scope, cheap, no tool run.
   findings.push(
-    ...secrets,
-    ...depFindings({ repoRoot, files: tracked }),
-    ...pipelineFindings({ repoRoot, files: tracked, pins }),
-    ...contractFindings({ repoRoot, files: tracked, repo, resolver, stacks: declared?.stacks }),
-    ...repoLocalCheckFindings({ repoRoot, files: tracked }),
-    ...lintSuppressionFindings({ repoRoot, files: tracked }),
-    ...(repo.profile === 'be' ? [...stacksFindings({ repoRoot, files: tracked, resolver }), ...testTopologyFindings({ repoRoot, files: tracked }), ...specPlacementFindings({ files: tracked, resolver }), ...proofCommandFindings({ repoRoot, files: tracked, resolver })] : [...frontendFindings({ repoRoot, files: tracked, repo }), ...feNoTestsFindings({ repoRoot, files: tracked.filter(inScope) })]),
-    ...extraFindings,
+    ...secretFindings({ repoRoot, files: files.filter(inScope), resolver }),
+    ...repoLocalCheckFindings({ repoRoot, files }),
+    ...lintSuppressionFindings({ repoRoot, files }),
   );
+  if (isRoot) {
+    findings.push(
+      ...depFindings({ repoRoot, files: all }),
+      ...peerIntegrationFindings({ repoRoot, files: all }),
+      ...pipelineFindings({ repoRoot, files, pins }),
+      ...testTopologyFindings({ repoRoot, files }),
+      ...proofCommandFindings({ repoRoot, files: all, resolver, sides: Object.keys(repo.sides ?? {}) }),
+      ...appFrontendFindings({ repoRoot, files: all, repo }),
+      // The tree check of the app root the machine runs per side for a side folder: README, root entries, automatic gates, hooks path.
+      ...checkAppRoot({ root: repoRoot, resolver, tree: trackedTreeView(all) }).violations.map((item) => ({ code: item.ruleId, level: 'error', path: item.path, line: item.line, column: item.column, source: 'machine', message: `${item.path}: ${item.message}` })),
+    );
+  } else if (repo.profile === 'be') {
+    findings.push(...contractFindings({ files, repo, resolver }), ...stacksFindings({ repoRoot, files, resolver }), ...testTopologyFindings({ repoRoot, files }));
+  } else {
+    findings.push(...frontendFindings({ repoRoot, files, repo }), ...feNoTestsFindings({ repoRoot, files: files.filter(inScope) }));
+  }
 
-  const soft = resolver.ruleParams().fileLines.soft;
-  for (const file of tracked) {
-    if (!inScope(file) || !SOURCE_EXT.test(file) || resolver.classifyPath(file).status !== 'owned') continue;
-    let lines;
-    try { lines = fs.readFileSync(path.join(repoRoot, file), 'utf8').split('\n').length; } catch { continue; }
-    if (lines > soft) findings.push({ code: 'HFS_SIZE_SOFT_BACKLOG', level: 'info', path: file, lines, soft, message: `${file} has ${lines} lines, above the soft size ${soft}; report only` });
+  if (!isRoot) {
+    const soft = resolver.ruleParams().fileLines.soft;
+    for (const file of files) {
+      if (!inScope(file) || !SOURCE_EXT.test(file) || resolver.classifyPath(file).status !== 'owned') continue;
+      let lines;
+      try { lines = fs.readFileSync(path.join(repoRoot, file), 'utf8').split('\n').length; } catch { continue; }
+      if (lines > soft) findings.push({ code: 'HFS_SIZE_SOFT_BACKLOG', level: 'info', path: file, lines, soft, message: `${file} has ${lines} lines, above the soft size ${soft}; report only` });
+    }
   }
+  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
+ * (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,
+ * untracked); they also do not run over `files`, which is a dry run. `extraFindings` are findings another emitter produced for the
+ * same app (the managed files, the formatter, the contract emit), app-relative, judged and counted with this module's own.
+ * The root scope and each side run their own rules over their own files (hfs checks per side, the side folder as the old repository
+ * root, plus the root checks); every finding path is app-relative. Returns {ok, profile, apps, manifest, tracked, findings, counts};
+ * a missing or invalid hfs.json is one HFS_DECLARATION_INVALID / HFS_MANIFEST_MAJOR_MISMATCH error finding, never an exception.
+ */
+export function checkRepo({ repoRoot, root = skillRoot, declaration, files, only, extraFindings = [], tree = files === undefined, manifest = loadSlotManifest({ root }), surface = 'all' }) {
+  const why = readWhy(root);
+  let repo;
+  try {
+    repo = declaration === undefined ? readRepoDeclaration(manifest, repoRoot) : resolveRepoDeclaration(manifest, declaration);
+  } catch (error) {
+    if (!(error instanceof HfsSlotsError) || !['HFS_DECLARATION_INVALID', 'HFS_MANIFEST_MAJOR_MISMATCH'].includes(error.code)) throw error;
+    const findings = withWhy([{ code: error.code, level: 'error', path: HFS_DECLARATION_FILE, message: error.message.replace(/^[A-Z_]+: /, ''), problems: error.details.problems }], why);
+    return { ok: false, repoRoot, manifest: manifest.version, profile: null, apps: [], tracked: 0, findings, counts: summarize(findings) };
+  }
+  const resolver = createSlotResolver(manifest, repo);
+  const tracked = files ?? trackedFiles(repoRoot);
+  const scoped = only ? new Set(only) : null;
+  const findings = [];
+  // `hfs check` leaves to the lint canon the per-path findings that sit on an existing TypeScript file (hfs-path-findings.mjs).
+  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 }), 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 });
+      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 }), repoRoot));
+  }
+  findings.push(...extraFindings);
   if (tree) findings.push(...treeFindings({ repoRoot, resolver }));
 
-  const finished = withWhy(findings, why);
+  // The app-root tree check reports machine codes: their why is read with the check's own.
+  const finished = withWhy(findings, { ...why, ...readWhy(root, [...new Set(findings.map((f) => f.code).filter((code) => !why[code]))]) });
   const counts = summarize(finished);
-  return { ok: counts.error === 0, repoRoot, manifest: manifest.version, profile: repo.profile, apps: repo.apps, tracked: tracked.length, findings: finished, counts };
+  const apps = repo.profile === APP_SCOPE ? SIDES.flatMap((side) => repo.sides[side].apps.map((app) => ({ ...app, side }))) : repo.apps;
+  return { ok: counts.error === 0, repoRoot, manifest: manifest.version, profile: repo.profile, apps, tracked: tracked.length, findings: finished, counts };
 }
 
 // ------------------------------------------------------------------------------------------ the whole check
@@ -390,45 +376,66 @@ function machineFindings(report) {
 }
 
 /**
- * The whole `hfs check` of one repository: checkRepo() (slots, pins, size, tree) and then the architecture machine over the
- * same work tree, its violations and errors merged in as findings with the Vietnamese why of their codes. `fast` judges
- * only what changed since the merge-base (`base` names another ref): the per-path slot and pin checks on the changed
- * paths, the machine on the owners of the changed source files without clones and dead exports, and no file-system tree
- * checks. `extraFindings` are the findings of the emitters that render templates or run the repository's 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.
+ * The whole `hfs check` of one app: checkRepo() (the root and both sides: slots, pins, size, tree) and then the architecture machine
+ * over each side folder (the side as the repository root it judges), its violations and errors merged in as findings with the
+ * Vietnamese why of their codes and the side prefixed onto their paths. `fast` judges only what changed since the merge-base (`base`
+ * names another ref): the per-path slot and pin checks on the changed paths, the machine on the owners of the changed source files
+ * without clones and dead exports, and no file-system tree checks. `extraFindings` are the findings of the emitters that render
+ * 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 }) {
   const changed = fast ? changedSince(repoRoot, base) : null;
-  const baseSha = changed ? changed.base : (base ? (mergeBaseOf(repoRoot, base) ?? refuse('HFS_REPO_UNREADABLE', `--base ${base} has no merge-base with HEAD`, { repoRoot, base })) : undefined);
-  const slotResult = checkRepo({ repoRoot, root, manifest, extraFindings, ...(changed ? { only: changed.files, tree: false } : {}) });
+  const slotResult = checkRepo({ repoRoot, root, 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' } };
-
-  let paths;
-  if (changed) {
-    const resolver = createSlotResolver(manifest, readRepoDeclaration(manifest, repoRoot));
-    paths = [...new Set(changed.files.filter((f) => SOURCE_EXT.test(f) || resolver.ownerOf(f)).map((f) => resolver.ownerOf(f)?.root ?? f))].sort();
-    if (!paths.length) return { ...slotResult, machine: { status: 'skipped', reason: 'no changed source file', base: changed.base }, fast: { base: changed.base, changed: changed.files.length } };
-  }
-  let report;
-  try {
-    report = machine({ repositoryRoot: repoRoot, base: baseSha, ...(changed ? { paths, fast: true } : {}) });
-  } catch (error) {
-    report = { ok: false, files: 0, kinds: [], violations: [], errors: [{ ruleId: 'ARCH_EXECUTION_UNAVAILABLE', message: String(error?.message ?? error) }] };
+  const repo = readRepoDeclaration(manifest, repoRoot);
+  const scopes = repo.profile === APP_SCOPE
+    ? SIDES.map((side) => ({ side, repoRoot: path.join(repoRoot, side), prefix: `${side}/` }))
+    : [{ side: null, repoRoot, prefix: '' }];
+  const runs = [];
+  const found = [];
+  for (const scope of scopes) {
+    const run = machineOver({ scope, manifest, machine, changed });
+    runs.push(run.info);
+    found.push(...run.findings);
   }
-  const found = machineFindings(report);
   const why = readWhy(root, [...new Set(found.map((f) => f.code))]);
   const findings = [...slotResult.findings, ...withWhy(found, why)];
   const counts = summarize(findings);
+  const ran = runs.filter((info) => info.status === 'ran');
   return {
     ...slotResult,
     ok: counts.error === 0,
     findings,
     counts,
-    machine: { status: 'ran', files: report.files, kinds: report.kinds, ...(changed ? { paths, base: changed.base } : {}) },
+    machine: ran.length
+      ? { status: 'ran', files: ran.reduce((sum, info) => sum + info.files, 0), kinds: [...new Set(ran.flatMap((info) => info.kinds ?? []))], sides: runs, ...(changed ? { paths: ran.flatMap((info) => info.paths ?? []), base: changed.base } : {}) }
+      : { status: 'skipped', reason: runs.map((info) => info.reason).join('; '), sides: runs, ...(changed ? { base: changed.base } : {}) },
     ...(changed ? { fast: { base: changed.base, changed: changed.files.length } } : {}),
   };
 }
 
+/** The architecture machine over one scope (a side folder): `{ info, findings }`, finding paths app-relative. */
+function machineOver({ scope, manifest, machine, changed }) {
+  const { side, prefix } = scope;
+  const label = side ?? 'repository';
+  let paths;
+  if (changed) {
+    const resolver = createSlotResolver(manifest, readRepoDeclaration(manifest, scope.repoRoot));
+    const mine = changed.files.filter((f) => f.startsWith(prefix)).map((f) => f.slice(prefix.length));
+    paths = [...new Set(mine.filter((f) => SOURCE_EXT.test(f) || resolver.ownerOf(f)).map((f) => resolver.ownerOf(f)?.root ?? f))].sort();
+    if (!paths.length) return { info: { side, status: 'skipped', reason: `no changed source file in ${label}` }, findings: [] };
+  }
+  let report;
+  try {
+    report = machine({ repositoryRoot: scope.repoRoot, base: changed?.base, surface: 'check', ...(changed ? { paths, fast: true } : {}) });
+  } catch (error) {
+    report = { ok: false, files: 0, kinds: [], violations: [], errors: [{ ruleId: 'ARCH_EXECUTION_UNAVAILABLE', message: String(error?.message ?? error) }] };
+  }
+  const message = side ? appRelativeMessages(side, scope.repoRoot) : null;
+  const findings = machineFindings(report).map((finding) => (side ? { ...finding, side, message: message(finding.message), ...(finding.path ? { path: onSide(side, finding.path) } : {}) } : finding));
+  return { info: { side, status: 'ran', files: report.files, kinds: report.kinds, ...(paths ? { paths: paths.map((p) => `${prefix}${p}`) } : {}) }, findings };
+}
 // --------------------------------------------------------------------------------------------------- explain
 
 const TEST_KIND = {
@@ -450,7 +457,9 @@ export function explainPath({ repoRoot, input, root = skillRoot, declaration, ma
   const slot = resolver.slot(c.slot);
   const tier = resolver.tierOf(c.path);
   const owner = resolver.ownerOf(c.path);
-  const mayImport = tier && tier !== 'none' ? resolver.allowedImports(tier) : null;
+  // A path of a side imports by its side's direction matrix; the app root has none of its own.
+  const scope = c.side ? resolver.sides[c.side] : resolver;
+  const mayImport = tier && tier !== 'none' ? scope.allowedImports(tier) : null;
   return {
     path: c.path,
     status: c.status,
@@ -471,61 +480,3 @@ export function explainPath({ repoRoot, input, root = skillRoot, declaration, ma
     ...(c.status === 'not-enabled' ? { code: 'HFS_SLOT_NOT_ENABLED', titleVi: why.HFS_SLOT_NOT_ENABLED.titleVi, whyVi: why.HFS_SLOT_NOT_ENABLED.whyVi } : {}),
   };
 }
-
-// ------------------------------------------------------------------------------------------------- init
-
-const SLUG_SUFFIX = /-(backend|be|frontend|fe|api|web|app)$/;
-const exists = (p) => fs.existsSync(p);
-const readPackage = (dir) => { try { return JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')); } catch { return null; } };
-const depsOf = (pkg) => ({ ...pkg?.devDependencies, ...pkg?.dependencies });
-
-/**
- * A starter hfs.json by detection: profile from the dependencies (next -> fe, @nestjs/core -> be, over the root and
- * every apps/<name>), apps from the apps/<name> directories (fe: kind next; be: worker/migrate/cli by name, else api).
- * optionalSlots are the opt-in slots (not implied by an app kind) that tracked files already occupy. Connections are not guessed; a repository that keeps a database declares them by hand and gains the migrate app.
- * A repository the detection cannot classify is HFS_INIT_UNDETECTED, never a guess.
- */
-export function detectDeclaration({ repoRoot, manifest }) {
-  const appsDir = path.join(repoRoot, 'apps');
-  const names = isDir(appsDir) ? fs.readdirSync(appsDir, { withFileTypes: true }).filter((e) => e.isDirectory() && e.name !== 'node_modules').map((e) => e.name).sort() : [];
-  const rootPkg = readPackage(repoRoot);
-  const all = { ...depsOf(rootPkg) };
-  for (const name of names) Object.assign(all, depsOf(readPackage(path.join(appsDir, name))));
-  const isFe = 'next' in all || names.some((n) => ['next.config.ts', 'next.config.js', 'next.config.mjs'].some((f) => exists(path.join(appsDir, n, f))));
-  const isBe = '@nestjs/core' in all || exists(path.join(repoRoot, 'nest-cli.json'));
-  if (isFe === isBe) refuse('HFS_INIT_UNDETECTED', `cannot tell the profile of ${repoRoot}: ${isFe ? 'both next and Nest are present' : 'neither next nor @nestjs/core is declared'}`, { repoRoot });
-  const profile = isFe ? 'fe' : 'be';
-  const apps = names.map((name) => {
-    if (profile === 'fe') return { name, kind: 'next' };
-    if (!isDir(path.join(appsDir, name, 'src'))) return null;
-    const kind = /migrat/.test(name) ? 'migrate' : (/worker/.test(name) ? 'worker' : (/(^|-)cli($|-)/.test(name) ? 'cli' : 'api'));
-    return { name, kind };
-  }).filter(Boolean).filter((a) => manifest.appKinds[profile].includes(a.kind));
-  if (!apps.length) refuse('HFS_INIT_UNDETECTED', `${repoRoot} has no apps/<name> ${profile === 'fe' ? 'Next application' : 'Nest application with a src directory'} to declare`, { repoRoot, profile });
-  const project = String(rootPkg?.name ?? path.basename(repoRoot)).replace(/^@[^/]+\//, '').toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').replace(SLUG_SUFFIX, '');
-  const declaration = { hfs: manifest.major, profile, project: /^[a-z]/.test(project) ? project : `p-${project}`, apps };
-  const optionalSlots = occupiedOptInSlots({ repoRoot, manifest, declaration });
-  return optionalSlots.length ? { ...declaration, optionalSlots } : declaration;
-}
-
-/** The opt-in slots (not enabled by an app kind) that at least one tracked file falls in, found by enabling them all for a look. */
-function occupiedOptInSlots({ repoRoot, manifest, declaration }) {
-  let files;
-  try { files = trackedFiles(repoRoot); } catch (error) { if (error.code === 'HFS_REPO_UNREADABLE') return []; throw error; }
-  const optIn = manifest.slots.filter((s) => s.profiles.includes(declaration.profile) && s.presence === 'opt-in' && s.appKind === undefined).map((s) => s.id);
-  const everything = createSlotResolver(manifest, resolveRepoDeclaration(manifest, { ...declaration, optionalSlots: optIn }));
-  const used = new Set();
-  for (const file of files) { const c = everything.classifyPath(file); if (c.status === 'owned' && optIn.includes(c.slot)) used.add(c.slot); }
-  return optIn.filter((id) => used.has(id));
-}
-
-/** Write hfs.json unless one exists (HFS_INIT_EXISTS); `write: false` returns the text only. */
-export function initRepo({ repoRoot, root = skillRoot, write = true, manifest = loadSlotManifest({ root }) }) {
-  const file = path.join(repoRoot, HFS_DECLARATION_FILE);
-  if (write && exists(file)) refuse('HFS_INIT_EXISTS', `${file} already exists; init never rewrites a declaration`, { file });
-  const declaration = detectDeclaration({ repoRoot, manifest });
-  resolveRepoDeclaration(manifest, declaration);
-  const text = `${JSON.stringify(declaration, null, 2)}\n`;
-  if (write) fs.writeFileSync(file, text);
-  return { file, declaration, text, written: write };
-}

package/runtime/scripts/lib/hfs-path-findings.mjs

@@ -0,0 +1,95 @@
+// hfs-path-findings.mjs - the per-path judgements of the slot manifest: what a tracked path is. One function, two surfaces: `hfs check`
+// (checkRepo) runs it over the tracked tree and keeps the findings that have no TypeScript file to sit on; the lint canon's project graph
+// (scripts/lib/project-graph.mjs) runs it over the same tree and serves the findings on a TypeScript file as ESLint reports.
+//   HFS_SLOT_UNDECLARED / HFS_SLOT_AMBIGUOUS / HFS_SLOT_NOT_ENABLED / HFS_FORBIDDEN_PRESENT / HFS_TOOL_CONFIG_LOCAL / HFS_TRACKED_MUST_BE_IGNORED (R01, R16)
+//   BE_SOURCE_FORM (R89, the file name), BE_SPEC_PLACEMENT (R102)
+import path from 'node:path';
+import { allowsFile } from './hfs-allows.mjs';
+import { isFeTestPath } from './hfs-rules/fe-no-tests.mjs';
+import { slotOwnsSecrets } from './hfs-rules/secrets.mjs';
+import { specPlacementFindings } from './hfs-rules/spec-placement.mjs';
+import { APP_SCOPE } from './hfs-slots.mjs';
+
+const KEBAB = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const SOURCE_ROOT = /^(?:src|apps)\//;
+const FREE_NAMES = new Set(['index.ts', 'main.ts']);
+const PLAIN_ENTRY = /^<[a-z][a-z0-9-]*>.ts$/;
+/**
+ * Where the work of a banned data-access suffix goes. The suffix is banned by the manifest (ruleParams.be.bannedSuffixes);
+ * this only adds the convention's home to the finding, so a file that is a repository or a store is told what replaces it.
+ */
+const DATA_ACCESS_HOME = 'SQL text is a constant in <name>.sql.ts of the capability persistence/ folder, and data access is the capability *.service.ts (or the application *.handler.ts) calling the shared EntityManager through its Inject<Conn>EntityManager()';
+const BANNED_SUFFIX_HOME = Object.freeze({ repository: DATA_ACCESS_HOME, store: DATA_ACCESS_HOME });
+
+/**
+ * BE_SOURCE_FORM (R89): every tracked src/ or apps/ TypeScript file of a back end is index.ts, main.ts, a migration of
+ * be.persistence, or <kebab-name>.<suffix>.ts with <suffix> in the closed vocabulary ruleParams.be.suffixes (a name such
+ * as order.service.spec.ts keeps its inner words kebab-case). A suffix of ruleParams.be.bannedSuffixes anywhere in the
+ * name is refused by name. Paths no slot owns are HFS_SLOT_UNDECLARED's, not this code's.
+ */
+function sourceFormFindings({ files, resolver }) {
+  const { suffixes, bannedSuffixes } = resolver.ruleParams();
+  // A suffix a slot names in its own file pattern (`*.builder.ts` of be.tests.fixtures.builders) is that slot's role: a file with it
+  // anywhere else is refused, so a builder cannot live beside a service or in the fixtures root.
+  const boundSuffixes = new Map();
+  for (const slot of resolver.slots()) {
+    const bound = /\*\.([a-z0-9-]+)\.ts$/.exec(slot.path ?? '')?.[1];
+    if (bound && suffixes.includes(bound)) boundSuffixes.set(bound, slot);
+  }
+  const findings = [];
+  for (const file of files) {
+    if (!file.endsWith('.ts') || !SOURCE_ROOT.test(file)) continue;
+    const c = resolver.classifyPath(file);
+    if (c.status !== 'owned' || c.tracking === 'ignored') continue;
+    const base = path.posix.basename(file);
+    if (FREE_NAMES.has(base)) continue;
+    // A literal file name the owning slot itself requires or allows (persistence/connection.ts, world/global-setup.ts) is its role.
+    const slot = resolver.slot(c.slot);
+    if ([...(slot?.requires ?? []), ...(slot?.allows ?? [])].some((entry) => entry === base)) continue;
+    // So is an allows entry below the slot root whose last segment is that literal name (be.tests.world fakes/<provider>/server.ts).
+    const admitted = allowsFile(resolver, file);
+    if (admitted?.allowed && admitted.entry?.includes('/') && path.posix.basename(admitted.entry) === base) continue;
+    // A slot whose `allows` holds a bare <name>.ts entry (be.tests.world.kit) names its files plainly, as platform/primitives does: kebab-case is the whole form.
+    if (admitted?.allowed && PLAIN_ENTRY.test(admitted.entry ?? '') && KEBAB.test(base.slice(0, -'.ts'.length))) continue;
+    if (c.slot === 'be.persistence' && path.posix.basename(path.posix.dirname(file)) === 'migrations') continue;
+    const parts = base.slice(0, -'.ts'.length).split('.');
+    const banned = parts.slice(1).find((part) => bannedSuffixes.includes(part));
+    if (banned) {
+      findings.push({ code: 'BE_SOURCE_FORM', level: 'error', path: file, suffix: banned, message: `${file}: the suffix .${banned} is banned; use a role from the closed suffix list (${suffixes.join(', ')})${BANNED_SUFFIX_HOME[banned] ? `. ${BANNED_SUFFIX_HOME[banned]}` : ''}` });
+    } else if (boundSuffixes.has(parts.at(-1)) && parts.length >= 2 && boundSuffixes.get(parts.at(-1)).id !== c.slot) {
+      findings.push({ code: 'BE_SOURCE_FORM', level: 'error', path: file, suffix: parts.at(-1), message: `${file}: the suffix .${parts.at(-1)}.ts belongs to ${boundSuffixes.get(parts.at(-1)).path} only; move the file there` });
+    } else if (parts.length < 2 || !parts.every((part) => KEBAB.test(part)) || !suffixes.includes(parts.at(-1))) {
+      findings.push({ code: 'BE_SOURCE_FORM', level: 'error', path: file, message: `${file}: the name must be <kebab-name>.<suffix>.ts with a suffix from the closed list (${suffixes.join(', ')}), or index.ts, main.ts or a migration` });
+    }
+  }
+  return findings;
+}
+
+/** The findings of the slot manifest over `files` (repository-relative tracked paths) of a repository of `profile`. */
+export function pathFindings({ files, resolver, profile }) {
+  const findings = [];
+  for (const file of files) {
+    if (profile === 'fe' && isFeTestPath(file)) continue;   // a test path of a front end is FE_NO_TESTS's, the one finding of that file
+    const c = resolver.classifyPath(file);
+    if (c.status === 'no-slot') {
+      findings.push({ code: 'HFS_SLOT_UNDECLARED', level: 'error', path: file, nearest: c.nearest, message: `${file} matches no slot${c.nearest ? `; nearest slot ${c.nearest.slot} (${c.nearest.pattern}), matched ${c.nearest.matchedPrefix || '.'} then expected ${c.nearest.expectedNext ?? 'nothing'}` : ''}` });
+    } else if (c.status === 'ambiguous') {
+      findings.push({ code: 'HFS_SLOT_AMBIGUOUS', level: 'error', path: file, candidates: c.candidates, message: `${file} is owned equally by ${c.candidates.map((x) => x.slot ?? x).join(', ')}` });
+    } else if (c.status === 'not-enabled') {
+      findings.push({ code: 'HFS_SLOT_NOT_ENABLED', level: 'error', path: file, slot: c.slot, message: `${file} belongs to ${c.slot}, an opt-in slot hfs.json neither lists in optionalSlots nor implies through an app kind` });
+    } else if (c.status === 'forbidden') {
+      const slot = resolver.slot(c.slot);
+      if (slotOwnsSecrets(slot)) continue;   // the secret scan reports the file (R06): one finding per file
+      const own = slot.rules?.includes('HFS_TOOL_CONFIG_LOCAL') ? 'HFS_TOOL_CONFIG_LOCAL' : 'HFS_FORBIDDEN_PRESENT';
+      findings.push({ code: own, level: 'error', path: file, slot: c.slot, goesTo: c.goesTo, message: `${file} is tracked but ${c.slot} is forbidden in the tree${c.goesTo ? `; it belongs at ${c.goesTo}` : ''}` });
+    } else if (c.tracking === 'ignored') {
+      findings.push({ code: 'HFS_TRACKED_MUST_BE_IGNORED', level: 'error', path: file, slot: c.slot, message: `${file} is tracked but ${c.slot} must be gitignored` });
+    }
+  }
+
+  if (profile === 'be') findings.push(...sourceFormFindings({ files, resolver }), ...specPlacementFindings({ files, resolver }));
+  // The app root (scripts/, CI, hooks) holds no test layer: a spec there is the same finding as a spec of an operational script.
+  else if (profile === APP_SCOPE) findings.push(...specPlacementFindings({ files, resolver }));
+  // The lint canon's project graph serves these findings on a TypeScript file; the origin keeps them apart from the machine's.
+  return findings.map((finding) => ({ ...finding, origin: 'repo' }));
+}