@starci/hfs 4.7.26 → 4.7.28

package/runtime/scripts/hfs/rule-catalog.mjs

@@ -17,7 +17,13 @@ const RULE_KINDS = Object.freeze(['codemod', 'lint', 'check', 'design']);
 const FINDING_CODE = /^[A-Z][A-Z0-9]*(_[A-Z0-9]+)+$/;
 const ENFORCER_ID = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 const FILE_ENFORCERS = new Set(['machine', 'hfs', 'work-validate', 'sonar', 'runtime']);
-const RULE_KEYS = new Set(['id', 'code', 'law', 'scope', 'kinds', 'gates', 'failureCodes', 'editions', 'codeEditions', 'enforcers', 'cases', 'docs', 'exemplifiedBy', 'proves', 'witness', 'editionWhy', 'amendedBy', 'templateNa', 'specNa', 'exampleNa']);
+/**
+ * The enforcer kinds that run only inside the StarCi runtime repository (`starci runtime check`, `starci work`): no published package carries
+ * them, so no package spec can hold them (owner ruling no-runtime-specs: the runtime has no specs of its own; the package clean-test and the
+ * scaffold e2e are its tests), and no example app is a product they judge. A rule is runtime-judged when every enforcer it has is of these kinds.
+ */
+export const RUNTIME_ONLY_ENFORCERS = Object.freeze(['work-validate', 'runtime']);
+const RULE_KEYS = new Set(['id', 'code', 'law', 'scope', 'kinds', 'gates', 'failureCodes', 'editions', 'codeEditions', 'enforcers', 'cases', 'docs', 'exemplifiedBy', 'proves', 'witness', 'editionWhy', 'amendedBy', 'templateNa']);
 const CASE_KEYS = new Set(['id', 'date', 'source', 'ruling', 'quote', 'supersedes', 'status', 'staleWhen', 'amendedBy']);
 const CASE_DATE = /^\d{4}-\d{2}-\d{2}$/;
 const ENFORCER_KEYS = new Set(['kind', 'id', 'status', 'at', 'editions', 'editionWhy']);
@@ -116,13 +122,6 @@ function witnessProblems(rule, label, bad) {
   const value = rule.witness;
   if (value === undefined) return;
   const at = `${label}.witness`;
-  if (isPlainObject(value)) {
-    unknownKeys(value, new Set(['status', 'reason', 'date']), at, bad);
-    if (value.status !== 'unreachable') bad.push(`${at}.status must be unreachable`);
-    textProblem(value.reason, `${at}.reason`, bad);
-    dateProblem(value.date, `${at}.date`, bad);
-    return;
-  }
   if (!nonEmptyList(value, at, bad)) return;
   value.forEach((item, index) => witnessEntryProblems(item, `${at}[${index}]`, bad));
 }
@@ -283,8 +282,6 @@ function checkRule(rule, index, catalog, codeOwner, bad) {
   if (rule.amendedBy !== undefined) caseReferenceProblems(rule.amendedBy, `${label}.amendedBy`, bad);
   optionalText(rule, 'editionWhy', label, bad);
   optionalText(rule, 'templateNa', label, bad);
-  optionalText(rule, 'specNa', label, bad);
-  optionalText(rule, 'exampleNa', label, bad);
   for (const key of ['docs', 'exemplifiedBy', 'proves']) evidenceProblems(rule, key, label, bad);
   witnessProblems(rule, label, bad);
   enumListProblems(rule, label, 'kinds', RULE_KINDS, bad);

package/runtime/scripts/hfs/rules/a15-findings.mjs

@@ -49,7 +49,7 @@ export const A15_CODES = [
   // codes-end
 ];
 
-const FINDERS = [
+export const FINDERS = [
   // finders-begin
   feBuildArgsFindings,
   workflowContextsFindings,

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

@@ -8,7 +8,7 @@ import { found } from './read.mjs';
 
 export const HFS_ASSET_OVERSIZE = 'HFS_ASSET_OVERSIZE';
 export const HFS_ASSET_KIND = 'HFS_ASSET_KIND';
-const DEFAULT_ASSET_BYTES = 512000;
+export const DEFAULT_ASSET_BYTES = 512000;
 const BUILD_EXTENSIONS = ['.ttf', '.otf', '.woff', '.woff2', '.eot', '.png', '.svg', '.webp', '.jpg', '.jpeg', '.gif', '.ico', '.avif', '.bmp', '.tif', '.tiff'];
 const MEDIA_EXTENSIONS = new Set(['.mp3', '.mp4', '.wav', '.ogg', '.oga', '.opus', '.flac', '.aac', '.m4a', '.wma', '.aiff', '.aif', '.mid', '.midi', '.mov', '.m4v', '.webm', '.avi', '.mkv', '.mpeg', '.mpg', '.wmv', '.flv', '.3gp']);
 const IMAGE_EXTENSIONS = new Set(BUILD_EXTENSIONS.filter((ext) => !['.ttf', '.otf', '.woff', '.woff2', '.eot'].includes(ext)));

package/runtime/scripts/hfs/rules/bypass-markers.mjs

@@ -0,0 +1,24 @@
+// bypass-markers.mjs - HFS_BYPASS_MARKER (R303): a product repository holds no bypass of a check. Whatever makes a check pass without
+// satisfying it is refused wherever it is written (owner ruling loosening-always-red: a bypass is always red):
+//   - an inline disable of any tool (eslint, stylelint, tslint, prettier, biome), a type-check escape (the ts-ignore, ts-expect-error and
+//     ts-nocheck directives), a Sonar exclusion comment, an istanbul / c8 / v8 coverage ignore;
+//   - a skipped, focused or todo test, or a skip option (a front end has no specs, but its source is still judged for the inline disables);
+//   - a failure swallowed in a hook, a script or a workflow: `|| true`, `continue-on-error`, `set +e`, `HUSKY=0`, `--no-verify`,
+//     `fail_ci_if_error: false`.
+// The text is read from the tracked tree here, and from the index by `starci app hygiene` (the pre-commit hook), which uses the same table
+// (scripts/lib/bypass-markers.mjs). A managed config edited to loosen is the managed-file drift's (HFS_MANAGED_FILE_DRIFT).
+import { found, readText } from './read.mjs';
+import { bypassesIn } from '../../lib/bypass-markers.mjs';
+
+export const HFS_BYPASS_MARKER = 'HFS_BYPASS_MARKER';
+
+/** The finding message of one marker of `file`. */
+export const bypassMessage = (file, hit) => `${file}:${hit.line} spells ${hit.label} (${hit.text.slice(0, 80)}); a check is satisfied, never bypassed: fix the cause and delete the marker`;
+
+/** The findings of R303 over the tracked paths `files` of the repository at `repoRoot`. */
+export function bypassMarkerFindings({ repoRoot, files }) {
+  return files.flatMap((file) => {
+    const text = readText(repoRoot, file);
+    return text === null ? [] : bypassesIn(file, text).map((hit) => found(HFS_BYPASS_MARKER, file, bypassMessage(file, hit), { line: hit.line }));
+  });
+}

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

@@ -22,7 +22,7 @@ const I18N_CATALOG = 'FE_I18N_CATALOG';
 export const DEFAULT_LOCALE = 'vi';
 const ROUTE_FILE = /\/(?:page|layout|template|loading|error|not-found)\.[jt]sx?$/;
 const LOCALE = /^[a-z]{2,3}(?:-[A-Za-z0-9]+)*$/;
-const WIRE_SCHEMA_STAMP = '.schema-sha256';
+export const WIRE_SCHEMA_STAMP = '.schema-sha256';
 
 /** Every leaf key of a parsed catalog as a dotted path. */
 function catalogKeys(value, prefix = '') {
@@ -32,7 +32,7 @@ function catalogKeys(value, prefix = '') {
 }
 
 /** Digest protocol for codegen: sorted app-relative schema path, NUL, LF-normalized source, NUL. */
-function wireSchemaDigest(repoRoot, snapshots) {
+export function wireSchemaDigest(repoRoot, snapshots) {
   const hash = createHash('sha256');
   for (const snapshot of [...snapshots].sort(byCodeUnit)) {
     let source;

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

@@ -77,7 +77,7 @@ function providerSecretFindings(repoRoot, file, repo, findings) {
 }
 
 /** Raw L17 findings. The catalog-driven findings filter decides which editions judge them. */
-function liteSecretCustodyFindings({ repoRoot, files, repo }) {
+export function liteSecretCustodyFindings({ repoRoot, files, repo }) {
   const findings = [];
   for (const file of files) {
     if (custodyPathFinding(file, repo, findings)) continue;

package/runtime/scripts/lib/bypass-markers.mjs

@@ -0,0 +1,116 @@
+// bypass-markers.mjs - what a BYPASS of a check looks like in text (owner ruling loosening-always-red: any bypass is red, always).
+// One table serves both sides of the no-bypass law:
+//   product   scripts/hfs/rules/bypass-markers.mjs (HFS_BYPASS_MARKER, `starci app check`) and `starci app hygiene` (the pre-commit
+//             hook) read a whole file and refuse every marker in it;
+//   runtime   scripts/lib/gate-loosening.mjs reads the ADDED lines of a diff of a watched check, canon template or workflow.
+// A marker is a way to make a check pass without satisfying it: an inline disable of any tool, a type-check escape, a Sonar or
+// coverage exclusion comment, a skipped or focused test, a failure swallowed in a hook or a workflow step.
+// The patterns are assembled from fragments (joined) so that this file never spells a marker itself: the runtime detector watches
+// its own library like every other check script.
+const join = (...parts) => parts.join('');
+const COMMENT_OPEN = /\/\/|\/\*/g;
+
+const SUPPRESSION_WORDS = [
+  join('eslint', '-disable'), join('stylelint', '-disable'), join('tslint', ':disable'), join('prettier', '-ignore'), join('biome', '-ignore'),
+  join('@ts', '-ignore'), join('@ts', '-expect-error'), join('@ts', '-nocheck'), join('NO', 'SONAR'),
+  join('istanbul', ' ignore'), join('c8', ' ignore'), join('v8', ' ignore'), join('jscpd', ':ignore'),
+];
+const escaped = (word) => word.replace(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
+const COMMENT_MARKER = new RegExp(`(${SUPPRESSION_WORDS.map(escaped).join('|')})`);
+
+const TEST_MARKERS = [
+  [new RegExp(String.raw`\b(?:it|test|describe|suite|context)\.(?:skip|only|todo|failing)\b`), 'a skipped or focused test'],
+  [new RegExp(String.raw`\b(?:xit|xtest|xdescribe|fit|fdescribe)\(`), 'a skipped or focused test'],
+  [new RegExp(String.raw`\.skipIf\(|\.runIf\(`), 'a conditionally skipped test'],
+  [new RegExp(String.raw`\bskip\s*:\s*(?!false\b)\S`), 'a skip option'],
+  [new RegExp(String.raw`\bpending\(\)`), 'a pending test'],
+];
+
+const SWALLOW = [
+  [/\|\|\s*(?:true|:)(?![\w-])/, 'a failure swallowed with `|| true`'],
+  [/\bcontinue-on-error\s*:\s*(?!false\b)\S/, join('continue', '-on-error')],
+  [/\bset\s+\+e\b/, 'set +e'],
+  [/\bHUSKY\s*=\s*0\b/, 'HUSKY=0'],
+  [/--no-verify\b/, '--no-verify'],
+  [/\bfail_ci_if_error\s*:\s*false\b/, 'fail_ci_if_error: false'],
+];
+
+// A weakening of the run itself that today's rendered canon still spells in places (the CI template runs jest with it); the runtime
+// detector refuses it as an ADDED line, the product rule waits until the canon is rid of it.
+const PENDING = [
+  [/--passWithNoTests\b/, '--passWithNoTests'],
+  [/--coverageThreshold\b/, '--coverageThreshold'],
+];
+
+const CODE_FILE = /\.(?:[cm]?[jt]sx?|vue|svelte|css|scss|less)$/;
+const SHELL_FILE = /(?:^|\/)(?:\.husky\/(?!_\/)[^/]+|[^/]+\.sh|hooks\/husky\/[^/]+)$/;
+const WORKFLOW_FILE = /(?:^|\/)(?:\.github|github)\/(?:workflows|actions)\/.+\.ya?ml$/;
+const MANIFEST_FILE = /(?:^|\/)package\.json$/;
+const SKIPPED_TREE = /(?:^|\/)(?:node_modules|dist|coverage|\.next|build)\//;
+const GENERATED_NAME = /(?:^|\/)(?:package-lock\.json|[^/]+\.generated\.[^/]+|[^/]+\.min\.[^/]+)$/;
+
+/** The kind of text `file` holds for the markers: 'code', 'shell' (hooks, scripts), 'workflow', 'manifest', or null for a file no marker is read in. */
+export function bypassFileKind(file) {
+  if (SKIPPED_TREE.test(file) || GENERATED_NAME.test(file)) return null;
+  if (SHELL_FILE.test(file)) return 'shell';
+  if (WORKFLOW_FILE.test(file)) return 'workflow';
+  if (MANIFEST_FILE.test(file)) return 'manifest';
+  if (CODE_FILE.test(file)) return 'code';
+  return null;
+}
+
+/** Whether `index` of `line` is outside every quoted string (a marker spelled inside a string is data, not a directive). */
+function outsideQuotes(line, index) {
+  let quote = null;
+  for (let at = 0; at < index; at += 1) {
+    const char = line[at];
+    if (quote) {
+      if (char === '\\') at += 1;
+      else if (char === quote) quote = null;
+    } else if (char === '"' || char === "'" || char === '`') quote = char;
+  }
+  return quote === null;
+}
+
+/** The text of a shell line without its `$(...)` and backtick substitutions: `|| true` inside one is a query, not a bypass. */
+const withoutSubstitutions = (line) => line.replace(/\$\([^()]*\)/g, '').replace(/`[^`]*`/g, '');
+
+const hitsOf = (pairs, line) => pairs.filter(([pattern]) => pattern.test(line)).map(([, label]) => label);
+
+function commentHit(line) {
+  for (const open of line.matchAll(COMMENT_OPEN)) {
+    if (!outsideQuotes(line, open.index)) continue;
+    const marker = COMMENT_MARKER.exec(line.slice(open.index));
+    if (marker) return marker[1];
+  }
+  return null;
+}
+
+/** The labels of the bypass markers on one `line` of a file of `kind` ([] when none). `pending` also reads the markers the canon still spells. */
+export function bypassLabelsOf(kind, line, { pending = false } = {}) {
+  if (kind === 'code') {
+    const comment = commentHit(line);
+    const tests = TEST_MARKERS.filter(([pattern]) => {
+      const hit = pattern.exec(line);
+      return hit && outsideQuotes(line, hit.index);
+    }).map(([, label]) => label);
+    return [...(comment ? [comment] : []), ...tests];
+  }
+  if (kind === 'shell' || kind === 'workflow' || kind === 'manifest') {
+    const text = withoutSubstitutions(line);
+    if (kind === 'manifest' && !/"[^"]+"\s*:\s*"/.test(line)) return [];
+    if (/^\s*#/.test(text)) return [];
+    return [...hitsOf(SWALLOW, text), ...(pending ? hitsOf(PENDING, text) : [])];
+  }
+  return [];
+}
+
+/**
+ * Every bypass marker of the text of one file: [{line, label, text}] (line numbers from 1). The file's kind decides the patterns;
+ * a file of no kind has none.
+ */
+export function bypassesIn(file, text, options = {}) {
+  const kind = bypassFileKind(file);
+  if (!kind || typeof text !== 'string') return [];
+  return text.split(/\r?\n/).flatMap((content, index) => bypassLabelsOf(kind, content, options).map((label) => ({ line: index + 1, label, text: content.trim() })));
+}

package/runtime/scripts/lib/check-code-loosening.mjs

@@ -0,0 +1,128 @@
+// check-code-loosening.mjs - what loosens a gate when the gate is CODE: a check script, a canon template, a lint package, a workflow or a hook.
+// gate-loosening.mjs judges the lists and numbers of the listed gate files; a bypass done by editing the check itself (a skip, an inline disable,
+// a swallowed failure, a ban or an assertion deleted, an exemption widened) is judged here, over the same unified diff, rename-aware (a line
+// that moves keeps its text, so it is paired off against its removal anywhere in the change). The kinds it reports:
+//   bypass-added     a bypass marker added to a file of checkCode (scripts/lib/bypass-markers.mjs)
+//   check-weakened   the change removes more enforcement lines from the files of checkCode than it adds back to them
+//   check-removed    a pattern-table row or quoted list entry removed from a check script and added nowhere in the change (a quoted
+//                    operand of a string concatenation, the text of a message, is no row)
+//   scope-widened    an exemption added: an ignore / exclude / exclusion key gaining an entry, a line more in an ignore file, an item added
+//                    under codecov.yml `ignore:`, or skipLibCheck turned on
+// A deleted file is not counted for check-weakened or check-removed: a registered check is judged by its entry in a gate file
+// (knowledge/hfs/runtime-slots.yaml), and an unregistered script deleted is dead code (scripts/checks/check-dead-scripts.mjs).
+import { bypassFileKind, bypassLabelsOf } from './bypass-markers.mjs';
+
+const SPEC_NAME = /\.spec\.[cm]?[jt]sx?$/;
+const FIXTURE_NAME = /\.fixture(?:\.\w+)?$/;
+const CODE_NAME = /\.[cm]?[jt]sx?$/;
+const COMMENT_LINE = /^\s*(?:\/\/|\/\*|\*|#)/;
+const NOT_TEXT = /^\s*(?:#|\/\/|$)/;
+
+const trimmed = (line) => line.trim();
+const clip = (text) => (text.length > 90 ? `${text.slice(0, 89)}…` : text);
+
+/** Whether `file` is one of the entries: a folder (the entry ends in a slash) or one file. */
+const listed = (file, entries = []) => entries.some((entry) => (entry.endsWith('/') ? file.startsWith(entry) : file === entry));
+
+/** Whether `file` is a check, a canon template, a lint package, a workflow or a hook (checkCode); its specs and fixtures spell markers on purpose and are not. */
+export const isCheckCode = (file, rules) => listed(file, rules.checkCode) && !listed(file, rules.capabilityFiles) && !SPEC_NAME.test(file) && !FIXTURE_NAME.test(file);
+
+const WORD = String.raw`\b(?:findings|violations|failures|errors|problems|issues|found|flag|fail)\s*(?:\.push\(|\()`;
+const EXIT = String.raw`process\.exit(?:Code)?\b|\bassert[.(]|\bexpect\(|\bok\s*:\s*false\b`;
+/** The lines that make a check fail: a finding pushed, a failing exit, an assertion. */
+const ENFORCEMENT = new RegExp(`${WORD}|${EXIT}`);
+const enforcementCount = (lines) => lines.filter((line) => !COMMENT_LINE.test(line) && ENFORCEMENT.test(line)).length;
+
+const LITERAL = '/.+/[a-z]*|\'[^\']*\'|"[^"]*"|`[^`]*`';
+/** A pattern-table row or a quoted list entry of a check script: the shape of a ban list or a rule table. */
+const LIST_ENTRY = new RegExp(String.raw`^\s*(?:\[\s*(?:${LITERAL})\s*,.*\]|${LITERAL})\s*,?\s*(?://.*)?$`);
+
+const countOf = (lines) => lines.reduce((counts, line) => counts.set(trimmed(line), (counts.get(trimmed(line)) ?? 0) + 1), new Map());
+
+/** Each file's added lines once every line that also appears removed somewhere in the change (it only moved) is paired off: Map(entry -> {added, removed}). */
+function unmovedOf(files) {
+  const added = countOf(files.flatMap((entry) => entry.added));
+  const removed = countOf(files.flatMap((entry) => entry.removed));
+  const keep = (line) => {
+    const key = trimmed(line);
+    if ((added.get(key) ?? 0) <= 0 || (removed.get(key) ?? 0) <= 0) return true;
+    added.set(key, added.get(key) - 1);
+    removed.set(key, removed.get(key) - 1);
+    return false;
+  };
+  return new Map(files.map((entry) => [entry, { added: entry.added.filter(keep), removed: entry.removed }]));
+}
+
+function bypassesAdded(entry, unmoved) {
+  const kind = bypassFileKind(entry.file);
+  if (!kind || entry.deleted) return [];
+  return unmoved.added.flatMap((line) => bypassLabelsOf(kind, line, { pending: true })
+    .map((label) => ({ kind: 'bypass-added', file: entry.file, detail: `${label}: ${clip(trimmed(line))}`, text: trimmed(line) })));
+}
+
+function entriesRemoved(entry, addedBack) {
+  if (entry.deleted || !CODE_NAME.test(entry.file)) return [];
+  const operand = (line) => entry.operands?.has(line) === true;
+  return entry.removed.filter((line) => LIST_ENTRY.test(line) && !COMMENT_LINE.test(line) && !operand(line)).flatMap((line) => {
+    const left = addedBack.get(trimmed(line)) ?? 0;
+    if (left > 0) { addedBack.set(trimmed(line), left - 1); return []; }
+    return [{ kind: 'check-removed', file: entry.file, detail: clip(trimmed(line)) }];
+  });
+}
+
+const EXEMPT_WORDS = ['ignores?', 'excludes?', 'exclusions?', 'coverageExclusions', '(?:coverage|testPath|modulePath)(?:Path)?IgnorePatterns', 'globalIgnores', String.raw`sonar\.(?:coverage\.)?exclusions`];
+const EXEMPT_KEY = new RegExp(String.raw`["']?(?:${EXEMPT_WORDS.join('|')})["']?\s*[:=]`, 'i');
+const SKIP_LIB_CHECK = /skipLibCheck["']?\s*:\s*true/;
+const IGNORE_FILE = /(?:^|\/)[^/]*ignore$/;
+const CODECOV_FILE = /(?:^|\/)codecov\.ya?ml$/;
+
+const itemsOf = (line) => (line.match(/[^\s,"'[\]{}=:]+/g) ?? []).slice(1);
+
+function scopesWidened(entry, unmoved) {
+  if (entry.deleted) return [];
+  const widened = (line) => ({ kind: 'scope-widened', file: entry.file, detail: clip(trimmed(line)) });
+  // An ignore file that gains more lines than it loses (a line rewritten is not a line more); codecov.yml: a list item added under `ignore:`.
+  if (IGNORE_FILE.test(entry.file)) return unmoved.added.filter((line) => !NOT_TEXT.test(line)).slice(unmoved.removed.filter((line) => !NOT_TEXT.test(line)).length).map(widened);
+  if (CODECOV_FILE.test(entry.file)) return unmoved.added.filter((line) => (entry.under?.get(line) ?? []).some((section) => /^ignore\b/.test(section))).map(widened);
+  return unmoved.added.flatMap((line) => {
+    if (SKIP_LIB_CHECK.test(line)) return [widened(line)];
+    const key = EXEMPT_KEY.exec(line)?.[0];
+    if (!key) return [];
+    const before = unmoved.removed.find((value) => value.includes(key));
+    const known = new Set(before === undefined ? [] : itemsOf(before));
+    return before === undefined || itemsOf(line).some((item) => !known.has(item)) ? [widened(line)] : [];
+  });
+}
+
+/** An import of the runtime's one exception list (scripts/lib/allowlist.mjs). */
+const ALLOWLIST_IMPORT = /\bfrom\s+['"][./]*(?:scripts\/)?lib\/allowlist\.mjs['"]/;
+const NAMES_ALLOWLIST = /allowlist/i;
+
+/**
+ * The removed lines of `entry` that count as enforcement lost. A check that stops reading the exception list (the change removes its import of
+ * scripts/lib/allowlist.mjs and adds none back) loses the enforcement that policed that list's own entries (a stale entry, an entry code now
+ * reads): those lines name the list, and with the list gone they police nothing. Every other removed enforcement line counts.
+ */
+function enforcementRemoved(entry) {
+  const dropsList = entry.removed.some((line) => ALLOWLIST_IMPORT.test(line)) && !entry.added.some((line) => ALLOWLIST_IMPORT.test(line));
+  return dropsList ? entry.removed.filter((line) => !NAMES_ALLOWLIST.test(line)) : entry.removed;
+}
+
+/** Every finding the check files of the change `files` (parseDiff entries) add under `rules` (modules/kernel/gate-loosening.yaml): [{kind, file, detail}]. */
+export function checkCodeFindings(files, rules) {
+  const watched = files.filter((entry) => isCheckCode(entry.file, rules));
+  const unmoved = unmovedOf(watched);
+  const alive = watched.filter((entry) => !entry.deleted);
+  const fewerInChange = enforcementCount(alive.flatMap(enforcementRemoved)) - enforcementCount(alive.flatMap((entry) => entry.added));
+  const addedBack = countOf(watched.flatMap((entry) => entry.added));
+  return watched.flatMap((entry) => {
+    const own = unmoved.get(entry);
+    const fewer = enforcementCount(enforcementRemoved(entry)) - enforcementCount(entry.added);
+    return [
+      ...bypassesAdded(entry, own),
+      ...entriesRemoved(entry, addedBack),
+      ...scopesWidened(entry, own),
+      ...(fewerInChange > 0 && !entry.deleted && fewer > 0 ? [{ kind: 'check-weakened', file: entry.file, detail: `${fewer} enforcement line(s) fewer` }] : []),
+    ];
+  });
+}

package/runtime/scripts/lib/example-refs.mjs

@@ -0,0 +1,205 @@
+// example-refs.mjs — the ONE runtime source file that may spell a path into the runtime's own examples/
+// tree or a product name the runtime legitimately knows (R206, NO_EXAMPLE_COUPLING): every other source
+// file reaches these through the constants below, and scripts/checks/check-example-coupling.mjs exempts
+// this file's name only - a declared read, never a path allowlist. A constant belongs here only when the
+// runtime genuinely reads that tree or names that product at run time; a pointer that can be generic must
+// be generic in the file that holds it.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseYaml } from '../../engine/yaml.mjs';
+import { validateAgainstSchema } from './json-schema.mjs';
+import { insidePath, samePath, slash } from './path-key.mjs';
+import { byCodeUnit } from './list.mjs';
+import { isLiteWorkRoot, workPathAllowed } from './work-edition.mjs';
+import { WORK_DIR_NAME } from './roots.mjs';
+
+/** The runtime's example tree root. */
+export const EXAMPLES_ROOT = 'examples';
+
+/** Curated basic sample source; operational artifact writers remain external. */
+export const EXAMPLE_RUNTIMES_ROOT = `${EXAMPLES_ROOT}/.runtimes`;
+
+/** Every examples/<name>/hfs.json declaration of kind app, sorted by name. */
+export function discoverExampleApps(root) {
+  const directory = path.join(root, EXAMPLES_ROOT);
+  let entries;
+  try { entries = fs.readdirSync(directory, { withFileTypes: true }); } catch { return []; }
+  return entries.filter((entry) => entry.isDirectory()).filter((entry) => {
+    try { return JSON.parse(fs.readFileSync(path.join(directory, entry.name, 'hfs.json'), 'utf8'))?.kind === 'app'; }
+    catch { return false; }
+  }).map((entry) => entry.name).sort(byCodeUnit);
+}
+
+/** The example apps that declare a browser journey (hfs.json `browser: true`, the opt-in slot app.browser-config), sorted by name: the matrix of the examples workflow's browser job. */
+export function discoverBrowserExampleApps(root) {
+  return discoverExampleApps(root).filter((name) => {
+    try { return JSON.parse(fs.readFileSync(path.join(root, EXAMPLES_ROOT, name, 'hfs.json'), 'utf8'))?.browser === true; }
+    catch { return false; }
+  });
+}
+
+/** The generic services-block template a starcistacks follow-up leg is pointed at (S11-02: one template
+ *  for every repository). */
+export const STACK_DECLARATION_TEMPLATE = `${EXAMPLES_ROOT}/starcistacks-services/template.services.yaml`;
+
+/** The reference app declaration scripts/hfs/derived-fields.mjs samples for per-field slot ownership. */
+export const REFERENCE_APP_MANIFEST = `${EXAMPLES_ROOT}/full-app/hfs.json`;
+
+/** The example app whose installed tree an fe-kit peer link points at by default. */
+export const REFERENCE_EXAMPLE_APP = 'full-app';
+
+/** The grammar css families a product repository may declare (`[data-grammar-family="<id>"]`); the
+ *  runtime's own product maps to the core sheet. */
+export const GRAMMAR_FAMILIES = Object.freeze({ starci: 'core', nivo: 'nivo' });
+
+/** A feature-folder segment that is only the product's own name - no useful leaf (display-names pathLabel). */
+export const PRODUCT_NAME_SEGMENT = /^(nivo|starci|mia)[-\w]*$/i;
+
+/** The closed list of product names this runtime shipped against - the names R206
+ *  (check-example-coupling.mjs) refuses anywhere in runtime source outside this file. */
+export const PRODUCT_NAMES = Object.freeze(['mia-mia', 'miamia', 'nivo', 'starci-academy', 'full-app', 'shape-slot']);
+
+/** The catalog of stable pattern IDs pointing at actual executable example source. */
+export const EXAMPLE_CATALOG_FILE = `${EXAMPLES_ROOT}/index.yaml`;
+
+function referenceFile(root, relative, { directory = false, exact = false } = {}) {
+  if (typeof relative !== 'string' || !relative || relative.includes('\\') || relative.includes(':') || path.isAbsolute(relative)
+    || relative.split('/').some((part) => !part || part === '.' || part === '..')) throw new Error(`invalid example input: ${relative}`);
+  const file = path.resolve(root, relative);
+  if (!insidePath(root, file)) throw new Error(`example input is outside its declared root: ${relative}`);
+  const realRoot = fs.realpathSync.native(root), base = path.resolve(root);
+  let at = base, expected = realRoot; // the root's own spelling (8.3 short name, symlinked prefix) is not a link inside the tree
+  for (const segment of path.relative(base, file).split(path.sep).filter(Boolean)) {
+    at = path.join(at, segment); expected = path.join(expected, segment);
+    if (fs.lstatSync(at).isSymbolicLink() || !samePath(fs.realpathSync.native(at), expected)
+      || (exact && !fs.readdirSync(path.dirname(at)).includes(path.basename(at))))
+      throw new Error(`linked example input: ${relative}`);
+  }
+  if (!(directory ? fs.lstatSync(file).isDirectory() : fs.lstatSync(file).isFile())
+    || !insidePath(realRoot, fs.realpathSync.native(file)))
+    throw new Error(`example input is not a contained regular file: ${relative}`);
+  return file;
+}
+
+/** Read and validate complete source references. Duplicate IDs refuse before
+ * lookup; source, compiler and test pointers stay within one declared HFS app. */
+function loadExampleCatalog(root, { file = EXAMPLE_CATALOG_FILE } = {}) {
+  const catalog = parseYaml(fs.readFileSync(referenceFile(root, file), 'utf8'));
+  const schema = parseYaml(fs.readFileSync(referenceFile(root, 'modules/schemas/code-example-catalog.schema.yaml'), 'utf8'));
+  const errors = validateAgainstSchema(catalog, schema);
+  if (errors.length) throw new Error(`invalid example catalog: ${errors.join('; ')}`);
+  assertUniqueExampleIds(catalog.examples);
+  for (const row of catalog.examples) assertExampleRow(root, row);
+  return catalog;
+}
+
+function assertUniqueExampleIds(examples) {
+  const ids = new Set();
+  for (const row of examples) {
+    if (ids.has(row.id)) throw new Error(`duplicate example id: ${row.id}`);
+    ids.add(row.id);
+  }
+}
+
+function assertExampleRow(root, row) {
+  const app = exampleAppRoot(root, row);
+  assertExampleEntrypoint(row);
+  assertUniqueRowValues(row, 'relatedRules');
+  for (const key of ['files', 'projects', 'tests']) assertExampleInputs(app, row, key);
+  assertSupportedExampleSources(row);
+}
+
+function exampleAppRoot(root, row) {
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(row.path)) throw new Error(`invalid example app: ${row.path}`);
+  const app = path.join(root, EXAMPLES_ROOT, row.path);
+  const declaration = JSON.parse(fs.readFileSync(referenceFile(root, `${EXAMPLES_ROOT}/${row.path}/hfs.json`), 'utf8'));
+  if (declaration.kind !== 'app') throw new Error(`example has no HFS app declaration: ${row.id}`);
+  return app;
+}
+
+function assertExampleEntrypoint(row) {
+  if (!row.files.includes(row.entrypoint) || !/\.tsx?$/.test(row.entrypoint)) throw new Error(`example entrypoint is not a listed source: ${row.id}`);
+}
+
+function assertUniqueRowValues(row, key) {
+  if (new Set(row[key]).size !== row[key].length) throw new Error(`duplicate example ${key}: ${row.id}`);
+}
+
+function assertExampleInputs(app, row, key) {
+  assertUniqueRowValues(row, key);
+  for (const relative of row[key]) assertAuthoredExampleInput(app, relative);
+}
+
+function assertAuthoredExampleInput(app, relative) {
+  if (relative.split('/').some((part) => ['node_modules', 'dist', '.next', '_derived', '.git'].includes(part)))
+    throw new Error(`derived or installed example input: ${relative}`);
+  referenceFile(app, relative);
+}
+
+function assertSupportedExampleSources(row) {
+  if (row.files.some((relative) => !/\.(?:tsx?|json)$/.test(relative))) throw new Error(`unsupported example source: ${row.id}`);
+}
+
+/** Source, compiler and test inputs of selected stable IDs, relative to the runtime.
+ * A null selection requests the declared whole catalog; unknown IDs refuse. */
+export function exampleSourcePaths(root, ids = null, options = {}) {
+  const catalog = loadExampleCatalog(root, options), selected = new Set(ids ?? catalog.examples.map((row) => row.id));
+  const known = new Set(catalog.examples.map((row) => row.id));
+  for (const id of selected) if (!known.has(id)) throw new Error(`unknown example id: ${id}`);
+  return [...new Set(catalog.examples.filter((row) => selected.has(row.id))
+    .flatMap((row) => [...row.files, ...row.projects, ...row.tests].map((relative) => `${EXAMPLES_ROOT}/${row.path}/${relative}`)))];
+}
+
+/** Actual example apps' own Work trees in app-name order. Dependency/template
+ * trees are not app Work; an absent own tree contributes no checker input. */
+export function exampleWorkRoots(root) {
+  return discoverExampleApps(root).flatMap((app) => {
+    const relative = `${EXAMPLES_ROOT}/${app}/.starciwork/index.yaml`;
+    const directory = path.dirname(path.join(root, relative)), stat = fs.lstatSync(directory, { throwIfNoEntry: false });
+    if (!stat) return [];
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`invalid example Work directory: ${app}`);
+    referenceFile(root, `${EXAMPLES_ROOT}/${app}/.starciwork`, { directory: true });
+    if (!isLiteWorkRoot(directory)) referenceFile(root, relative);
+    return [directory];
+  });
+}
+
+/**
+ * The runtime checkout that holds `workRoot` when it is one of that checkout's example Work trees
+ * (`<checkout>/examples/<app>/.starciwork` beside `<checkout>/examples/.runtimes`), else null. An example is judged against its
+ * own checkout's fixture store: a lane's example by the lane's store, whichever runtime runs the check (the shared pre-commit hook
+ * runs the canonical runtime over a lane's staged files).
+ */
+export function exampleCheckoutOf(workRoot) {
+  if (typeof workRoot !== 'string') return null;
+  const work = path.resolve(workRoot);
+  const appDir = path.dirname(work), examplesDir = path.dirname(appDir), checkout = path.dirname(examplesDir);
+  if (path.basename(work) !== WORK_DIR_NAME || path.basename(examplesDir) !== EXAMPLES_ROOT) return null;
+  return fs.existsSync(path.join(examplesDir, '.runtimes')) && fs.existsSync(path.join(appDir, 'hfs.json')) ? checkout : null;
+}
+
+/** Per-call READ options for an actual HFS app's own Work tree. A real project
+ * uses the default external store; an example never falls back to that store.
+ * The fixture CAS is curated source, not a destination for operational writers. */
+export function exampleArtifactReadOptions(runtimeRoot, workRoot, { resolveRoot = workRoot } = {}) {
+  if (typeof runtimeRoot !== 'string' || typeof workRoot !== 'string') throw new TypeError('example artifact context needs runtime and Work paths');
+  const base = path.resolve(runtimeRoot), target = path.resolve(workRoot);
+  const relative = slash(path.relative(base, target)), parts = relative.split('/');
+  if (parts[0]?.toLowerCase() !== EXAMPLES_ROOT) return Object.freeze({});
+  const app = parts[1];
+  if (parts[0] !== EXAMPLES_ROOT || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(app ?? '')
+    || !discoverExampleApps(base).includes(app) || parts[2] !== WORK_DIR_NAME)
+    throw new Error(`invalid example Work artifact context: ${relative}`);
+  referenceFile(base, `${EXAMPLES_ROOT}/${app}/hfs.json`, { exact: true });
+  const ownWork = path.join(base, EXAMPLES_ROOT, app, WORK_DIR_NAME);
+  if (!isLiteWorkRoot(ownWork)) referenceFile(base, `${EXAMPLES_ROOT}/${app}/.starciwork/index.yaml`, { exact: true });
+  if (!workPathAllowed(ownWork, target, { dir: true })) throw new Error('lite .starciwork holds only workspace.yaml and brand/ (plus .gitignore)');
+  referenceFile(base, relative, { directory: true, exact: true });
+  const resolution = path.resolve(resolveRoot);
+  if (!workPathAllowed(ownWork, resolution, { dir: true })) throw new Error('lite .starciwork holds only workspace.yaml and brand/ (plus .gitignore)');
+  if (!insidePath(resolution, target, { includeSelf: true }) || !insidePath(ownWork, resolution, { includeSelf: true }))
+    throw new Error('selected example validation and resolution must share its own Work root');
+  referenceFile(base, slash(path.relative(base, resolution)), { directory: true, exact: true });
+  return Object.freeze({ root: path.join(base, EXAMPLE_RUNTIMES_ROOT, app, 'artifacts') });
+}