@starci/hfs 4.11.22 → 4.12.2

package/runtime/scripts/hfs/check.mjs

@@ -1,4 +1,4 @@
-// hfs-check.mjs - the HFS app check, behind `starci app check | explain` (packages/hfs) and reusable by any
+// hfs-check.mjs - the HFS app check, behind `starci app check | slot` (packages/hfs) and reusable by any
 // runtime check. It reads three things and nothing else: the app's hfs.json, the slot manifest
 // (knowledge/hfs/slots.yaml through scripts/hfs/slots.mjs) and the pins (canon-pins.mjs: the bundled knowledge/hfs/canon-pins.yaml
 // and the version of the starci-harness that runs the check). It never
@@ -101,389 +101,369 @@ import { REFUSAL_CODES } from './refusal-codes.mjs';
 export { REFUSAL_CODES } from './refusal-codes.mjs';
 // The database rules (R213-R216) read SQL through a WASM parser, so they are async: `starci app check` calls them beside the other emitters and passes the findings in as `extraFindings`.
 export { checkDatabase } from './rules/database.mjs';
-
 export const FAILURE_CODES_FILE = 'modules/kernel/failure-codes.yaml';
 /** The codes this module emits that are not the slot loader's own: the why bundle of packages/hfs ships exactly these plus the loader's. */
 export const CHECK_CODES = Object.freeze([
-  'HFS_SLOT_UNDECLARED', 'HFS_SLOT_NOT_ENABLED', 'HFS_SLOT_AMBIGUOUS', 'HFS_TRACKED_MUST_BE_IGNORED', 'HFS_FORBIDDEN_PRESENT',
-  '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', 'HFS_MCP_TOOLS_SNAPSHOT',
-  'BE_TEST_TOPOLOGY', 'BE_SPEC_PLACEMENT', 'HFS_REPO_LOCAL_CHECK', 'HFS_LINT_SUPPRESSION_FILE', 'HFS_BYPASS_MARKER', 'HFS_PROOF_COMMAND_FILE_MISSING', 'HFS_PEER_INTEGRATION_MISSING', 'BE_INTEGRATION_SPEC_MISSING', 'FE_GRAPHQL_CONTRACT', 'FE_NO_TESTS', 'HFS_MONO_WORKSPACES', 'HFS_MONO_FE_WORKSPACE', 'HFS_MONO_NEST_PROJECTS', 'HFS_MONO_WORKSPACE_DEP', 'BE_CLI_REQUIRED', 'FE_WIRE_GENERATED', 'FE_I18N_PLACEMENT', 'FE_I18N_CATALOG', 'HFS_SERVICE_PLACEMENT', 'HFS_IMAGE_UNPINNED', 'HFS_SERVICE_STACK_DECLARATION', 'HFS_EVENT_CONTRACT', 'BE_ASYNC_SPEC_MISSING', 'BE_SAGA_STEP_COMPENSATION', 'BE_SAGA_STATE_VERSIONED', 'BE_SAGA_EVENT_CONTRACT', 'BE_SAGA_CONSUMER_DEDUPE', 'BE_EVENT_CLASS_CONTRACT', 'BE_PATTERN_SPEC_MISSING', 'BE_CONTRACT_BREAKING', 'BE_KIND_DECLARATION', 'BE_KIND_EMPTY', 'HFS_DOCKER_BUILD_CONTEXT', 'HFS_DOCKER_STAGES', 'HFS_DOCKER_ENTRY', 'HFS_DOCKER_BASE_PIN', 'HFS_DOCKER_SECRETS', 'BE_SAGA_E2E_MISSING',
-  'FE_STACK_FORBIDDEN', 'HFS_EDITION_FORBIDDEN_PRESENT', 'HFS_BACKING_UNDECLARED', 'HFS_BACKING_UNUSED', 'HFS_LITE_SECRET_CUSTODY', 'HFS_STARCIWORK_LITE_FORBIDDEN',
-  'DB_MIGRATION_SHAPE', 'DB_RLS_REQUIRED', 'DB_DYNAMIC_DDL', 'DB_POLICY_SHAPE', 'DB_DEFINER_SAFE', 'DB_STORAGE_POLICY', 'LITE_DB_MIGRATION',
-  'HFS_DOCKER_HEALTHCHECK_FAKE', 'DB_APP_ROLE', 'DB_FORCE_RLS_DEFAULT',
-  'DB_POLICY_TAUTOLOGY', 'DB_VIEW_UNSAFE', 'DB_STORAGE_PREFIX', 'DB_DEFINER_REVOKE',
-  'HFS_GITIGNORE_BLOCK_DRIFT', 'HFS_SONAR_CONFIG', 'HFS_COVERAGE_SCOPE_DRIFT', 'HFS_FORMAT',
-  'HFS_EMPTY_DIR', 'HFS_GHOST_TREE', 'HFS_UNTRACKED_ROOT_ENTRY',
-  ...A15_CODES,
-  ...REFUSAL_CODES,
+    'HFS_SLOT_UNDECLARED', 'HFS_SLOT_NOT_ENABLED', 'HFS_SLOT_AMBIGUOUS', 'HFS_TRACKED_MUST_BE_IGNORED', 'HFS_FORBIDDEN_PRESENT',
+    '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', 'HFS_MCP_TOOLS_SNAPSHOT',
+    'BE_TEST_TOPOLOGY', 'BE_SPEC_PLACEMENT', 'HFS_REPO_LOCAL_CHECK', 'HFS_LINT_SUPPRESSION_FILE', 'HFS_BYPASS_MARKER', 'HFS_PROOF_COMMAND_FILE_MISSING', 'HFS_PEER_INTEGRATION_MISSING', 'BE_INTEGRATION_SPEC_MISSING', 'FE_GRAPHQL_CONTRACT', 'FE_NO_TESTS', 'HFS_MONO_WORKSPACES', 'HFS_MONO_FE_WORKSPACE', 'HFS_MONO_NEST_PROJECTS', 'HFS_MONO_WORKSPACE_DEP', 'BE_CLI_REQUIRED', 'FE_WIRE_GENERATED', 'FE_I18N_PLACEMENT', 'FE_I18N_CATALOG', 'HFS_SERVICE_PLACEMENT', 'HFS_IMAGE_UNPINNED', 'HFS_SERVICE_STACK_DECLARATION', 'HFS_EVENT_CONTRACT', 'BE_ASYNC_SPEC_MISSING', 'BE_SAGA_STEP_COMPENSATION', 'BE_SAGA_STATE_VERSIONED', 'BE_SAGA_EVENT_CONTRACT', 'BE_SAGA_CONSUMER_DEDUPE', 'BE_EVENT_CLASS_CONTRACT', 'BE_PATTERN_SPEC_MISSING', 'BE_CONTRACT_BREAKING', 'BE_KIND_DECLARATION', 'BE_KIND_EMPTY', 'HFS_DOCKER_BUILD_CONTEXT', 'HFS_DOCKER_STAGES', 'HFS_DOCKER_ENTRY', 'HFS_DOCKER_BASE_PIN', 'HFS_DOCKER_SECRETS', 'BE_SAGA_E2E_MISSING',
+    'FE_STACK_FORBIDDEN', 'HFS_EDITION_FORBIDDEN_PRESENT', 'HFS_BACKING_UNDECLARED', 'HFS_BACKING_UNUSED', 'HFS_LITE_SECRET_CUSTODY', 'HFS_STARCIWORK_LITE_FORBIDDEN',
+    'DB_MIGRATION_SHAPE', 'DB_RLS_REQUIRED', 'DB_DYNAMIC_DDL', 'DB_POLICY_SHAPE', 'DB_DEFINER_SAFE', 'DB_STORAGE_POLICY', 'LITE_DB_MIGRATION',
+    'HFS_DOCKER_HEALTHCHECK_FAKE', 'DB_APP_ROLE', 'DB_FORCE_RLS_DEFAULT',
+    'DB_POLICY_TAUTOLOGY', 'DB_VIEW_UNSAFE', 'DB_STORAGE_PREFIX', 'DB_DEFINER_REVOKE',
+    'HFS_GITIGNORE_BLOCK_DRIFT', 'HFS_SONAR_CONFIG', 'HFS_COVERAGE_SCOPE_DRIFT', 'HFS_FORMAT',
+    'HFS_EMPTY_DIR', 'HFS_GHOST_TREE', 'HFS_UNTRACKED_ROOT_ENTRY',
+    ...A15_CODES,
+    ...REFUSAL_CODES,
 ]);
 /** Every code `starci app check` can report: its own and every code the architecture machine can emit (derived from the machine's rule id lists). */
 export const ALL_CHECK_CODES = Object.freeze([...new Set([...CHECK_CODES, ...ARCHITECTURE_RULE_IDS])].sort(byCodeUnit));
 const SOURCE_EXT = /\.(?:[cm]?[jt]sx?)$/;
 const VAR = /<([a-z][a-z0-9-]*)>/g;
-
 const refuse = (code, message, details = {}) => { throw new HfsSlotsError(code, message, details); };
-
 /** {code: {title, title_vi, meaning_vi, nextStep_vi}} for the codes asked for, read from the failure-code catalog under `root`. */
 export function readWhy(root = skillRoot, codes = CHECK_CODES) {
-  const catalog = readCatalogOnce(path.join(root, FAILURE_CODES_FILE));
-  const why = {};
-  for (const code of codes) {
-    const entry = catalog?.[code];
-    if (!entry) refuse('HFS_MANIFEST_INVALID', `${FAILURE_CODES_FILE} has no entry for ${code}`, { code });
-    why[code] = { title: entry.title, titleVi: entry.title_vi, whyVi: entry.meaning_vi, nextStepVi: entry.nextStep_vi };
-  }
-  return why;
+    const catalog = readCatalogOnce(path.join(root, FAILURE_CODES_FILE));
+    const why = {};
+    for (const code of codes) {
+        const entry = catalog?.[code];
+        if (!entry)
+            refuse('HFS_MANIFEST_INVALID', `${FAILURE_CODES_FILE} has no entry for ${code}`, { code });
+        why[code] = { title: entry.title, titleVi: entry.title_vi, whyVi: entry.meaning_vi, nextStepVi: entry.nextStep_vi };
+    }
+    return why;
 }
-
 /** Repository-relative tracked paths (git ls-files, posix separators; what the index holds, whatever the work tree shows). A directory that is not a Git work tree is a refusal. */
 export function trackedFiles(repoRoot) {
-  let out;
-  try {
-    out = gitOutputOf(lsFiles(['-z', '--cached', '--exclude-standard'], { dir: repoRoot, maxBuffer: 256 * 1024 * 1024 }), 'git ls-files');
-  } catch (error) {
-    refuse('HFS_REPO_UNREADABLE', `${repoRoot} is not a readable Git work tree (${String(error?.stderr ?? error?.message ?? error).trim().split('\n')[0]})`, { repoRoot });
-  }
-  return out.split('\0').filter(Boolean).map(posixPath);
+    let out;
+    try {
+        out = gitOutputOf(lsFiles(['-z', '--cached', '--exclude-standard'], { dir: repoRoot, maxBuffer: 256 * 1024 * 1024 }), 'git ls-files');
+    }
+    catch (error) {
+        refuse('HFS_REPO_UNREADABLE', `${repoRoot} is not a readable Git work tree (${String(error?.stderr ?? error?.message ?? error).trim().split('\n')[0]})`, { repoRoot });
+    }
+    return out.split('\0').filter(Boolean).map(posixPath);
 }
-
 const fill = (text, bindings) => String(text).replace(VAR, (whole, name) => bindings[name] ?? whole);
-
 /** 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();
-  const note = (slotId, root, bindings) => {
-    const slot = resolver.slot(slotId);
-    if (!slot || !(slot.requires?.length || slot.minInstances)) return;
-    const key = `${slotId}|${root}`;
-    if (!found.has(key)) found.set(key, { slot: slotId, root, bindings });
-  };
-  for (const file of files) {
-    const c = resolver.classifyPath(file);
-    if (c.status === 'owned') note(c.slot, c.root, c.bindings);
-    const owner = c.status === 'owned' ? resolver.ownerOf(file) : null;
-    if (owner) note(owner.slot, owner.root, owner.bindings);
-  }
-  return [...found.values()];
+    const found = new Map();
+    const note = (slotId, root, bindings) => {
+        const slot = resolver.slot(slotId);
+        if (!slot || !(slot.requires?.length || slot.minInstances))
+            return;
+        const key = `${slotId}|${root}`;
+        if (!found.has(key))
+            found.set(key, { slot: slotId, root, bindings });
+    };
+    for (const file of files) {
+        const c = resolver.classifyPath(file);
+        if (c.status === 'owned')
+            note(c.slot, c.root, c.bindings);
+        const owner = c.status === 'owned' ? resolver.ownerOf(file) : null;
+        if (owner)
+            note(owner.slot, owner.root, owner.bindings);
+    }
+    return [...found.values()];
 }
-
 const requiredOf = (slot, instance) => (slot.requires ?? []).map((entry) => {
-  const rooted = entry.startsWith('/');
-  const filled = fill(rooted ? entry.slice(1) : entry, instance.bindings);
-  return rooted || !instance.root ? filled : `${instance.root}/${filled}`;
+    const rooted = entry.startsWith('/');
+    const filled = fill(rooted ? entry.slice(1) : entry, instance.bindings);
+    return rooted || !instance.root ? filled : `${instance.root}/${filled}`;
 });
-
 const appOf = (p) => /^apps\/([^/]+)\//.exec(p)?.[1];
-
 /** A side-relative path (or null) as an app-relative one. */
 const onSide = (side, p) => (p ? path.posix.normalize(`${side}/${p}`) : p);
-
 function appendRequiredPathFindings(findings, resolver, files, required, present) {
-  const missing = new Set();
-  const missingFile = (slot, p, via) => {
-    const key = `${slot}|${p}`;
-    if (missing.has(key) || present(p) || !requiredFileApplies(slot, p, files)) return;
-    missing.add(key);
-    const app = appOf(p);
-    const appNote = app ? ` (app ${app})` : '';
-    findings.push({ code: 'HFS_SLOT_REQUIRED_MISSING', level: 'error', path: p, slot, via, ...(app ? { app } : {}), message: `${slot} requires ${p}${appNote}, which is not tracked` });
-  };
-  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');
-  return instances;
+    const missing = new Set();
+    const missingFile = (slot, p, via) => {
+        const key = `${slot}|${p}`;
+        if (missing.has(key) || present(p) || !requiredFileApplies(slot, p, files))
+            return;
+        missing.add(key);
+        const app = appOf(p);
+        const appNote = app ? ` (app ${app})` : '';
+        findings.push({ code: 'HFS_SLOT_REQUIRED_MISSING', level: 'error', path: p, slot, via, ...(app ? { app } : {}), message: `${slot} requires ${p}${appNote}, which is not tracked` });
+    };
+    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');
+    return instances;
 }
-
 function minimumInstanceFindings(resolver, required, instances) {
-  const findings = [];
-  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((instance) => instance.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}` });
-  }
-  return findings;
+    const findings = [];
+    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((instance) => instance.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}` });
+    }
+    return findings;
 }
-
 function contentRuleFindings({ repoRoot, repo, resolver, files, all, scoped, pins, inScope, isRoot, appSide, editionDeclaration, manifest, phase }) {
-  const findings = [
-    ...pinFindings({ repoRoot, files, profile: repo.profile, pins, only: scoped }),
-    ...liteSecretFindings({ repoRoot, files: files.filter((file) => inScope(file)), resolver, repo }),
-    ...editionFindings({ repoRoot, files: files.filter((file) => inScope(file)), repo, resolver, manifest, withDeclaration: editionDeclaration }),
-    ...feStackFindings({ repoRoot, files: files.filter((file) => inScope(file)), repo, manifest }),
-    ...repoLocalCheckFindings({ repoRoot, files }),
-    ...lintSuppressionFindings({ repoRoot, files }),
-    ...bypassMarkerFindings({ repoRoot, files: files.filter((file) => inScope(file)) }),
-    ...a15Findings({ repoRoot, files, all, repo, resolver, manifest, isRoot, appSide, inScope }),
-  ];
-  findings.push(...trackedStacksGateFindings({ repoRoot, files, all, repo, resolver, manifest, isRoot, inScope, existingFindings: findings }));
-  if (isRoot) {
-    findings.push(
-      ...appRootFindings({ repoRoot, files, all, repo, resolver, pins, phase }),
-      ...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({ repoRoot, files, repo, resolver }), ...mcpToolsSnapshotFindings({ repoRoot, files, repo }), ...testTopologyFindings({ repoRoot, files }));
-  } else {
-    findings.push(...frontendFindings({ repoRoot, files, repo }), ...feNoTestsFindings({ repoRoot, files: files.filter((file) => inScope(file)) }));
-  }
-  return findings;
+    const findings = [
+        ...pinFindings({ repoRoot, files, profile: repo.profile, pins, only: scoped }),
+        ...liteSecretFindings({ repoRoot, files: files.filter((file) => inScope(file)), resolver, repo }),
+        ...editionFindings({ repoRoot, files: files.filter((file) => inScope(file)), repo, resolver, manifest, withDeclaration: editionDeclaration }),
+        ...feStackFindings({ repoRoot, files: files.filter((file) => inScope(file)), repo, manifest }),
+        ...repoLocalCheckFindings({ repoRoot, files }),
+        ...lintSuppressionFindings({ repoRoot, files }),
+        ...bypassMarkerFindings({ repoRoot, files: files.filter((file) => inScope(file)) }),
+        ...a15Findings({ repoRoot, files, all, repo, resolver, manifest, isRoot, appSide, inScope }),
+    ];
+    findings.push(...trackedStacksGateFindings({ repoRoot, files, all, repo, resolver, manifest, isRoot, inScope, existingFindings: findings }));
+    if (isRoot) {
+        findings.push(...appRootFindings({ repoRoot, files, all, repo, resolver, pins, phase }), ...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({ repoRoot, files, repo, resolver }), ...mcpToolsSnapshotFindings({ repoRoot, files, repo }), ...testTopologyFindings({ repoRoot, files }));
+    }
+    else {
+        findings.push(...frontendFindings({ repoRoot, files, repo }), ...feNoTestsFindings({ repoRoot, files: files.filter((file) => inScope(file)) }));
+    }
+    return findings;
 }
-
 function sizeSoftFindings({ repoRoot, resolver, files, inScope }) {
-  const findings = [];
-  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;
+    const findings = [];
+    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 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, .starcistacks) 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).
- */
 function scopeFindings({ repoRoot, root, harness, repo, resolver, files, all = files, scoped, manifest, appSide = false, editionDeclaration = true, phase }) {
-  const inScope = (file) => !scoped || scoped.has(file);
-  // A required directory of the root (be/, fe/) is present through the files below it, which are the sides' own.
-  const trackedSet = new Set(all);
-  const present = (p) => (p.endsWith('/') ? all.some((f) => f.startsWith(p)) : trackedSet.has(p));
-  const isRoot = repo.profile === APP_SCOPE;
-  const findings = pathFindings({ files: files.filter(inScope), resolver, profile: repo.profile });
-  const required = resolver.requiredPaths();
-  const instances = appendRequiredPathFindings(findings, resolver, files, required, present);
-  findings.push(...minimumInstanceFindings(resolver, required, instances));
-  // The runtime repository (kind runtime) is judged here by its tree law only; its own rules run in scripts/hfs/runtime-check.mjs.
-  if (repo.kind === RUNTIME_KIND) return findings;
-
-  const pins = canonPins({ root, harness });
-  findings.push(...contentRuleFindings({ repoRoot, repo, resolver, files, all, scoped, pins, inScope, isRoot, appSide, editionDeclaration, manifest, phase }));
-  if (!isRoot) findings.push(...sizeSoftFindings({ repoRoot, resolver, files, inScope }));
-  return findings;
+    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 isRoot = repo.profile === APP_SCOPE;
+    const findings = pathFindings({ files: files.filter(inScope), resolver, profile: repo.profile });
+    const required = resolver.requiredPaths();
+    const instances = appendRequiredPathFindings(findings, resolver, files, required, present);
+    findings.push(...minimumInstanceFindings(resolver, required, instances));
+    // The runtime repository (kind runtime) is judged here by its tree law only; its own rules run in scripts/hfs/runtime-check.mjs.
+    if (repo.kind === RUNTIME_KIND)
+        return findings;
+    const pins = canonPins({ root, ...(harness ? { harness } : {}) });
+    findings.push(...contentRuleFindings({ repoRoot, repo, resolver, files, all, scoped, pins, inScope, isRoot, appSide, editionDeclaration, manifest, phase }));
+    if (!isRoot)
+        findings.push(...sizeSoftFindings({ repoRoot, resolver, files, inScope }));
+    return findings;
 }
-
-/**
- * The check of one app. `repoRoot` is the app root (a side folder is checked as that side alone). `harness` ({ version }) is the CLI
- * that runs the check, whose version is the app's starci-harness pin (canon-pins.mjs). `declaration` overrides hfs.json
- * (a dry run over an app that has none); `files` overrides git ls-files (specs), app-relative. `only` (a list of app-relative paths)
- * limits the per-path checks (slot, pin, size) to those paths; the checks of the tree as a whole (required files, minimum instances,
- * empty directories, untracked entries) are not per-path. `tree: false` skips the file-system checks (empty directories, ghosts,
- * 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.
- * `phase: 'source'` is the runtime's no-install example-render pass: tracked obligations still run, while ignored generated
- * artifact presence/freshness belongs to the default `workspace` phase after codegen. Ordinary app check/lint always use it.
- */
 export function checkRepo({ repoRoot, root = skillRoot, harness, declaration, files, only, extraFindings = [], tree = files === undefined, manifest = loadSlotManifest({ root }), surface = 'all', phase = 'workspace' }) {
-  if (!['source', 'workspace'].includes(phase)) throw new Error(`unknown HFS inspection phase ${phase}`);
-  const why = readWhy(root);
-  let repo;
-  try {
-    repo = declaration === undefined ? readRepoDeclaration(manifest, repoRoot) : resolveRepoDeclaration(manifest, declaration);
-  } catch (error) {
-    if (!(error instanceof HfsSlotsError) || !['HFS_DECLARATION_INVALID', 'HFS_MANIFEST_MAJOR_MISMATCH', 'HFS_EDITION_INVALID'].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 = [];
-  // `starci app 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, harness, repo, resolver, files: own, all: tracked, scoped, manifest, phase }), repoRoot));
-    for (const side of SIDES) {
-      const prefix = `${side}/`;
-      const sideRoot = path.join(repoRoot, side);
-      const sideFiles = tracked.filter((file) => file.startsWith(prefix)).map((file) => file.slice(prefix.length));
-      const sideScoped = scoped ? new Set([...scoped].filter((file) => file.startsWith(prefix)).map((file) => file.slice(prefix.length))) : null;
-      const sideFindings = scopeFindings({ repoRoot: sideRoot, root, harness, repo: repo.sides[side], resolver: resolver.sides[side], files: sideFiles, scoped: sideScoped, manifest, appSide: true, editionDeclaration: false, phase });
-      const message = appRelativeMessages(side, sideRoot);
-      findings.push(...keep(sideFindings, sideRoot).map((finding) => ({ ...finding, side, path: onSide(side, finding.path), message: message(finding.message) })));
+    if (!['source', 'workspace'].includes(phase))
+        throw new Error(`unknown HFS inspection phase ${phase}`);
+    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', 'HFS_EDITION_INVALID'].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) };
     }
-  } else {
-    findings.push(...keep(scopeFindings({ repoRoot, root, harness, repo, resolver, files: tracked, scoped, manifest, phase }), repoRoot));
-  }
-  findings.push(...extraFindings);
-  const untrackedSecrets = untrackedSecretFindings({ repoRoot, files: tracked, repo });
-  findings.push(...untrackedSecrets);
-  if (tree) findings.push(...treeFindings({ repoRoot, resolver, tracked, reportedUntracked: new Set(untrackedSecrets.map((finding) => finding.path)) }));
-
-  // The app-root tree check reports machine codes: their why is read with the check's own.
-  const judged = judgedFindings(findings, repo.edition ?? 'full', root);
-  const finished = withWhy(judged, { ...why, ...readWhy(root, [...new Set(judged.map((f) => f.code).filter((code) => !why[code]))]) });
-  const counts = summarize(finished);
-  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 };
+    const resolver = createSlotResolver(manifest, repo);
+    const tracked = files ?? trackedFiles(repoRoot);
+    const scoped = only ? new Set(only) : null;
+    const findings = [];
+    // `starci app 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, harness, repo, resolver, files: own, all: tracked, scoped, manifest, phase }), repoRoot));
+        for (const side of SIDES) {
+            const prefix = `${side}/`;
+            const sideRoot = path.join(repoRoot, side);
+            const sideFiles = tracked.filter((file) => file.startsWith(prefix)).map((file) => file.slice(prefix.length));
+            const sideScoped = scoped ? new Set([...scoped].filter((file) => file.startsWith(prefix)).map((file) => file.slice(prefix.length))) : null;
+            const sideFindings = scopeFindings({ repoRoot: sideRoot, root, harness, repo: repo.sides[side], resolver: resolver.sides[side], files: sideFiles, scoped: sideScoped, manifest, appSide: true, editionDeclaration: false, phase });
+            const message = appRelativeMessages(side, sideRoot);
+            findings.push(...keep(sideFindings, sideRoot).map((finding) => ({ ...finding, side, path: onSide(side, finding.path), message: message(finding.message) })));
+        }
+    }
+    else {
+        findings.push(...keep(scopeFindings({ repoRoot, root, harness, repo, resolver, files: tracked, scoped, manifest, phase }), repoRoot));
+    }
+    findings.push(...extraFindings);
+    const untrackedSecrets = untrackedSecretFindings({ repoRoot, files: tracked, repo });
+    findings.push(...untrackedSecrets);
+    if (tree)
+        findings.push(...treeFindings({ repoRoot, resolver, tracked, reportedUntracked: new Set(untrackedSecrets.map((finding) => finding.path)) }));
+    // The app-root tree check reports machine codes: their why is read with the check's own.
+    const judged = judgedFindings(findings, repo.edition ?? 'full', root);
+    const finished = withWhy(judged, { ...why, ...readWhy(root, [...new Set(judged.map((f) => f.code).filter((code) => !why[code]))]) });
+    const counts = summarize(finished);
+    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
-
 /** The merge-base of HEAD with `base`, else with origin/main, else with main; null when none resolves. */
 function mergeBaseOf(repoRoot, base) {
-  for (const ref of base ? [base] : ['origin/main', 'main']) {
-    const sha = mergeBase(repoRoot, 'HEAD', ref); // null: this ref has no merge-base with HEAD; try the next
-    if (sha) return sha;
-  }
-  return null;
+    for (const ref of base ? [base] : ['origin/main', 'main']) {
+        const sha = mergeBase(repoRoot, 'HEAD', ref); // null: this ref has no merge-base with HEAD; try the next
+        if (sha)
+            return sha;
+    }
+    return null;
 }
-
 /** Tracked paths that differ from the merge-base (commits, staged and unstaged edits; deletions are not paths to judge). */
 export function changedSince(repoRoot, base) {
-  const sha = mergeBaseOf(repoRoot, base);
-  if (!sha) {
-    throw new Error(base
-      ? `--base ${base} has no merge-base with HEAD; pass a ref this branch descends from`
-      : '--fast needs a merge-base with origin/main or main and found none; run `git fetch origin main` or pass --base <ref>');
-  }
-  const files = gitOutputOf(gitDiff(['--name-only', '--diff-filter=ACMRT', '-z', sha], { dir: repoRoot, maxBuffer: 256 * 1024 * 1024 }), 'git diff').split('\0').filter(Boolean).map(posixPath);
-  return { base: sha, files };
+    const sha = mergeBaseOf(repoRoot, base);
+    if (!sha) {
+        throw new Error(base
+            ? `--base ${base} has no merge-base with HEAD; pass a ref this branch descends from`
+            : '--fast needs a merge-base with origin/main or main and found none; run `git fetch origin main` or pass --base <ref>');
+    }
+    const files = gitOutputOf(gitDiff(['--name-only', '--diff-filter=ACMRT', '-z', sha], { dir: repoRoot, maxBuffer: 256 * 1024 * 1024 }), 'git diff').split('\0').filter(Boolean).map(posixPath);
+    return { base: sha, files };
 }
-
 /** The machine's violations and errors as findings: each keeps the machine's rule id as its code. */
 function machineFindings(report) {
-  const of = (item) => ({ code: item.ruleId, level: 'error', ...(item.path ? { path: item.path } : {}), ...(item.line ? { line: item.line, column: item.column } : {}), source: 'machine', message: ((item.path && item.path + (item.line && ':' + item.line || '') + ': ') || '') + item.message });
-  return [...report.errors.map(of), ...report.violations.map(of)];
+    const of = (item) => ({ code: item.ruleId, level: 'error', ...(item.path ? { path: item.path } : {}), ...(item.line ? { line: item.line, column: item.column } : {}), source: 'machine', message: ((item.path && item.path + (item.line && ':' + item.line || '') + ': ') || '') + item.message });
+    return [...report.errors.map(of), ...report.violations.map(of)];
 }
-
-/**
- * The whole `starci app 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, harness, fast = false, base, extraFindings = [], manifest = loadSlotManifest({ root }), machine = checkArchitecture, wiring = false, coverageFrom }) {
-  const changed = fast ? changedSince(repoRoot, base) : null;
-  const slotResult = checkRepo({ repoRoot, root, harness, manifest, extraFindings, surface: 'check', ...(changed ? { only: changed.files, tree: false } : {}) });
-  if (slotResult.profile === null) return { ...slotResult, machine: { status: 'skipped', reason: 'hfs.json is not valid' } };
-  const repo = readRepoDeclaration(manifest, repoRoot);
-  const scopes = repo.profile === APP_SCOPE
-    ? 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 why = readWhy(root, [...new Set(found.map((f) => f.code))]);
-  const findings = [...slotResult.findings, ...withWhy(judgedFindings(found, repo.edition ?? 'full', root), why)];
-  const counts = summarize(findings);
-  const ran = runs.filter((info) => info.status === 'ran');
-  const result = {
-    ...slotResult,
-    ok: counts.error === 0,
-    findings,
-    counts,
-    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 } } : {}),
-  };
-  return withCheckProofs(result, { repoRoot, root, manifest, wiring, coverageFrom });
+    const changed = fast ? changedSince(repoRoot, base) : null;
+    const slotResult = checkRepo({ repoRoot, root, harness, manifest, extraFindings, surface: 'check', ...(changed ? { only: changed.files, tree: false } : {}) });
+    if (slotResult.profile === null)
+        return { ...slotResult, machine: { status: 'skipped', reason: 'hfs.json is not valid' } };
+    const repo = readRepoDeclaration(manifest, repoRoot);
+    const scopes = repo.profile === APP_SCOPE
+        ? 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 why = readWhy(root, [...new Set(found.map((f) => f.code))]);
+    const findings = [...slotResult.findings, ...withWhy(judgedFindings(found, repo.edition ?? 'full', root), why)];
+    const counts = summarize(findings);
+    const ran = runs.filter((info) => info.status === 'ran');
+    const result = {
+        ...slotResult,
+        ok: counts.error === 0,
+        findings,
+        counts,
+        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 } } : {}),
+    };
+    return withCheckProofs(result, { repoRoot, root, manifest, wiring, coverageFrom });
 }
-
-/** Optional CLI proofs run over the whole tracked tree. */
-export function withCheckProofs(result, { repoRoot, root = skillRoot, manifest = loadSlotManifest({ root }), wiring = false, coverageFrom, edition } = {}) {
-  if ((!wiring && coverageFrom === undefined) || result.profile === null) return result;
-  const declared = readRepoDeclaration(manifest, repoRoot);
-  const repo = { ...declared, edition: edition ?? declared.edition };
-  if (repo.sides) repo.sides = Object.fromEntries(Object.entries(repo.sides).map(([side, declaration]) => [side, { ...declaration, edition: repo.edition }]));
-  const context = { repoRoot, repo, manifest, files: trackedFiles(repoRoot) };
-  const reports = {};
-  if (wiring) reports.wiring = appWiring(context);
-  if (coverageFrom !== undefined) reports.coverage = coverageFromReport({ ...context, coverageFrom });
-  const proofFindings = Object.values(reports).flatMap(report => report.findings);
-  const why = readWhy(root, [...new Set(proofFindings.map(finding => finding.code))]);
-  // The explicit whole-tree wiring proof supersedes the ordinary finder's scoped result.
-  const previous = result.findings.filter(finding => !wiring || (finding.code !== BOOT_PROOF_CODE && finding.code !== BOOT_PROOF_TIMEOUT));
-  const findings = [...previous, ...withWhy(judgedFindings(proofFindings, repo.edition ?? 'full', root), why)];
-  const counts = summarize(findings);
-  return { ...result, ...reports, findings, counts, ok: counts.error === 0 };
+export function withCheckProofs(result, { repoRoot, root = skillRoot, manifest = loadSlotManifest({ root }), wiring = false, coverageFrom, edition }) {
+    if ((!wiring && coverageFrom === undefined) || result.profile === null)
+        return result;
+    const declared = readRepoDeclaration(manifest, repoRoot);
+    const repo = { ...declared, edition: edition ?? declared.edition };
+    // reason: the entries of the declared sides are exactly the keys of Side, so the rebuilt map keeps the Record<Side, RepoView> shape.
+    if (repo.sides)
+        repo.sides = Object.fromEntries(Object.entries(repo.sides).map(([side, declaration]) => [side, { ...declaration, edition: repo.edition }]));
+    const context = { repoRoot, repo, manifest, files: trackedFiles(repoRoot) };
+    // reason: the wiring and coverage reports are produced by the proof modules; only their findings are read here.
+    const reports = {};
+    if (wiring)
+        reports.wiring = appWiring(context);
+    if (coverageFrom !== undefined)
+        reports.coverage = coverageFromReport({ ...context, coverageFrom });
+    const proofFindings = Object.values(reports).flatMap((report) => report.findings);
+    const why = readWhy(root, [...new Set(proofFindings.map((finding) => finding.code))]);
+    // The explicit whole-tree wiring proof supersedes the ordinary finder's scoped result.
+    const previous = result.findings.filter((finding) => !wiring || (finding.code !== BOOT_PROOF_CODE && finding.code !== BOOT_PROOF_TIMEOUT));
+    const findings = [...previous, ...withWhy(judgedFindings(proofFindings, repo.edition ?? 'full', root), why)];
+    const counts = summarize(findings);
+    return { ...result, ...reports, findings, counts, ok: counts.error === 0 };
 }
-
-/** 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(byCodeUnit);
-    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 };
+    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(byCodeUnit);
+        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 = {
-  'unit-beside': 'a <name>.service.spec.ts beside each <name>.service.ts in this slot (only services are unit-tested; a webhook or realtime door has its own spec beside it)',
-  e2e: 'an integration, e2e or contract spec covering the flow; no unit spec is required',
-  none: 'no test is required for files in this slot',
+    'unit-beside': 'a <name>.service.spec.ts beside each <name>.service.ts in this slot (only services are unit-tested; a webhook or realtime door has its own spec beside it)',
+    e2e: 'an integration, e2e or contract spec covering the flow; no unit spec is required',
+    none: 'no test is required for files in this slot',
 };
-
 /** What owns `input` and what that means: slot, tier, allowed imports, required tests, required files. */
 export function explainPath({ repoRoot, input, root = skillRoot, declaration, manifest = loadSlotManifest({ root }) }) {
-  const repo = declaration === undefined ? readRepoDeclaration(manifest, repoRoot) : resolveRepoDeclaration(manifest, declaration);
-  const resolver = createSlotResolver(manifest, repo);
-  const why = readWhy(root);
-  const c = resolver.classifyPath(input);
-  const dir = /[\\/]$/.test(input) || (repoRoot && fs.existsSync(path.join(repoRoot, c.path)) && fs.statSync(path.join(repoRoot, c.path)).isDirectory());
-  const liteWork = liteStarciworkFinding(c.path, resolver, { dir });
-  if (liteWork) {
-    const entry = why[liteWork.code];
-    return { ...c, ...liteWork, status: 'forbidden', titleVi: entry.titleVi, whyVi: entry.whyVi };
-  }
-  if (c.status === 'no-slot') {
-    return { path: c.path, status: 'no-slot', code: 'HFS_SLOT_UNDECLARED', nearest: c.nearest, titleVi: why.HFS_SLOT_UNDECLARED.titleVi, whyVi: why.HFS_SLOT_UNDECLARED.whyVi };
-  }
-  if (c.status === 'ambiguous') return { path: c.path, status: 'ambiguous', code: 'HFS_SLOT_AMBIGUOUS', candidates: c.candidates, titleVi: why.HFS_SLOT_AMBIGUOUS.titleVi, whyVi: why.HFS_SLOT_AMBIGUOUS.whyVi };
-  const slot = resolver.slot(c.slot);
-  const tier = resolver.tierOf(c.path);
-  const owner = resolver.ownerOf(c.path);
-  // 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,
-    slot: slot.id,
-    pattern: slot.path,
-    presence: slot.presence,
-    tracking: slot.tracked,
-    tier: tier ?? 'none',
-    owner: owner ? { slot: owner.slot, root: owner.root } : null,
-    allowedImports: mayImport,
-    importRule: mayImport ? manifest.crossOwner : (tier === 'none' && 'the slot takes no part in import checks' || null),
-    tests: slot.tests,
-    testsMeaning: TEST_KIND[slot.tests],
-    requiredFiles: resolver.requiredFiles(c.path),
-    ...(slot.goesTo ? { goesTo: slot.goesTo } : {}),
-    ...(slot.rules ? { rules: slot.rules } : {}),
-    ...(c.status === 'forbidden' ? { code: 'HFS_FORBIDDEN_PRESENT', titleVi: why.HFS_FORBIDDEN_PRESENT.titleVi, whyVi: why.HFS_FORBIDDEN_PRESENT.whyVi } : {}),
-    ...(c.status === 'not-enabled' ? { code: 'HFS_SLOT_NOT_ENABLED', titleVi: why.HFS_SLOT_NOT_ENABLED.titleVi, whyVi: why.HFS_SLOT_NOT_ENABLED.whyVi } : {}),
-  };
+    const repo = (declaration === undefined ? readRepoDeclaration(manifest, repoRoot) : resolveRepoDeclaration(manifest, declaration));
+    const resolver = createSlotResolver(manifest, repo);
+    const why = readWhy(root);
+    const c = resolver.classifyPath(input);
+    const dir = /[\\/]$/.test(input) || (repoRoot && fs.existsSync(path.join(repoRoot, c.path)) && fs.statSync(path.join(repoRoot, c.path)).isDirectory());
+    const liteWork = liteStarciworkFinding(c.path, resolver, { dir });
+    if (liteWork) {
+        const entry = why[liteWork.code];
+        return { ...c, ...liteWork, status: 'forbidden', titleVi: entry.titleVi, whyVi: entry.whyVi };
+    }
+    if (c.status === 'no-slot') {
+        return { path: c.path, status: 'no-slot', code: 'HFS_SLOT_UNDECLARED', nearest: c.nearest, titleVi: why.HFS_SLOT_UNDECLARED.titleVi, whyVi: why.HFS_SLOT_UNDECLARED.whyVi };
+    }
+    if (c.status === 'ambiguous')
+        return { path: c.path, status: 'ambiguous', code: 'HFS_SLOT_AMBIGUOUS', candidates: c.candidates, titleVi: why.HFS_SLOT_AMBIGUOUS.titleVi, whyVi: why.HFS_SLOT_AMBIGUOUS.whyVi };
+    const slot = resolver.slot(c.slot);
+    const tier = resolver.tierOf(c.path);
+    const owner = resolver.ownerOf(c.path);
+    // 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,
+        slot: slot.id,
+        pattern: slot.path,
+        presence: slot.presence,
+        tracking: slot.tracked,
+        tier: tier ?? 'none',
+        owner: owner ? { slot: owner.slot, root: owner.root } : null,
+        allowedImports: mayImport,
+        importRule: mayImport ? manifest.crossOwner : (tier === 'none' && 'the slot takes no part in import checks' || null),
+        tests: slot.tests,
+        testsMeaning: TEST_KIND[slot.tests],
+        requiredFiles: resolver.requiredFiles(c.path),
+        ...(slot.goesTo ? { goesTo: slot.goesTo } : {}),
+        ...(slot.rules ? { rules: slot.rules } : {}),
+        ...(c.status === 'forbidden' ? { code: 'HFS_FORBIDDEN_PRESENT', titleVi: why.HFS_FORBIDDEN_PRESENT.titleVi, whyVi: why.HFS_FORBIDDEN_PRESENT.whyVi } : {}),
+        ...(c.status === 'not-enabled' ? { code: 'HFS_SLOT_NOT_ENABLED', titleVi: why.HFS_SLOT_NOT_ENABLED.titleVi, whyVi: why.HFS_SLOT_NOT_ENABLED.whyVi } : {}),
+    };
 }