@starci/hfs 4.7.27 → 4.7.29

package/runtime/scripts/gates/starcistacks.mjs

@@ -0,0 +1,499 @@
+#!/usr/bin/env node
+// check-starcistacks.mjs - the .starcistacks services contract (owner ruling 2026-09-24: "the stacks make sonar
+// clear ... update .claude and enforce the .starcistacks format").
+//
+// Every product states the delivery and quality services its code and CI use - Sonar, a
+// container registry, analytics, error tracking - in the `services` block of its stack declaration
+// (modules/schemas/application-stacks.schema.yaml $defs.service): provider, mode local|hosted|disabled,
+// host (local and public URL), the stack that runs a local one, project keys per repository, credentials
+// as custody references, how GitHub CI gets them and ownerAction. A Kernel or an op reads this block
+// before it asks for any credential, and never asks the owner for what it declares `ownerAction: none`
+// with custody present.
+//
+//   starci gate starcistacks <repo-root> [--new] [--json]
+//
+//   --new          the repository is being created by this leg (interface.scaffold, backend.scaffold,
+//                  package.scaffold): a missing declaration or services block is refused, not a suspect
+//
+// Refusals: an unknown or ambiguous service declaration, custody that is missing where it is declared,
+// an owner action declared for something custody already holds, CI calling a service the declaration
+// disables or omits, and a tracked plaintext secret. Everything an existing repository merely lacks -
+// the declaration, the services block, the .starcistacks rename, ignore rules - is a suspect with a
+// planned follow-up (workspace.manage mode stacks), never a block on running work.
+//
+// Values are never read: custody presence is a file-existence test, and nothing here prints a secret.
+// Exit 0 clean (suspects allowed), 1 refused, 2 usage.
+import fs from 'node:fs';
+import path from 'node:path';
+import { lsFiles } from '../api/git/ls-files.mjs'; import { checkIgnore } from '../api/git/check-ignore.mjs';
+import { repositoryName, repositoryHome } from '../hfs/repo-identity.mjs';
+import { isMain } from '../lib/is-main.mjs';
+import { skillRoot } from '../../engine/runtime-root.mjs';
+import {isPlainObject as plain} from '../../engine/plain-object.mjs';
+import { parseYaml } from '../../engine/yaml.mjs';
+import { list } from '../lib/list.mjs';
+import { isFile, isDir } from '../lib/fs-kind.mjs';
+import { loadSonarGate } from './sonar-gate.mjs';
+import { resolveCustodyFile, resolveDeclaredRepository, runtimeHostRoot } from './runtime-host.mjs';
+import { slash, trimTrailingSlashes } from '../lib/path-key.mjs';
+import { DECLARATION, STACK_ROOT, declaredStack, findStackDeclaration, readDeclaration, readText, text } from '../lib/stack-declaration.mjs';
+import { readProperties } from '../lib/properties.mjs';
+import { escapeRegExp } from '../lib/regex.mjs';
+import { isInfrastructureValueFile } from './starcistacks-value-file.mjs';
+import { STACK_DECLARATION_TEMPLATE } from '../lib/example-refs.mjs';
+import { checkSecretForm, kindOf } from './starcistacks-form.mjs';
+import { SERVICE_CATALOG, checkServiceForm, checkCiDeclaration, checkQualityService } from './starcistacks-ci.mjs';
+import { applicationStackFindings } from './starcistacks-runtime.mjs';
+export { DECLARATION, STACK_ROOT, findStackDeclaration };
+const RESULT_SCHEMA = 'starci/starcistacks-check@1';
+const DECLARATION_SCHEMA = 'starci/application-stacks@1';
+const FOLLOW_UP = { op: 'workspace.manage', params: { mode: 'stacks' },
+  detail: `author the services block of the repository stack declaration (sonar and every other delivery/quality service) from ${STACK_DECLARATION_TEMPLATE}` };
+/** Every finding code this check can emit. */
+export const CODES = [
+  'STACKS_BADGE_TOKEN_SERVICE', 'STACKS_DECLARATION_MISSING', 'STACKS_DECLARATION_INVALID', 'STACKS_SERVICES_MISSING',
+  'STACKS_SCHEMA_INVALID', 'STACKS_SERVICE_UNKNOWN', 'STACKS_PROVIDER_UNKNOWN',
+  'STACKS_SERVICE_AMBIGUOUS', 'STACKS_STACK_UNRESOLVED', 'STACKS_CUSTODY_MISSING', 'STACKS_CUSTODY_UNVERIFIED',
+  'STACKS_OWNER_ACTION_REDUNDANT', 'STACKS_PROJECT_MISSING', 'STACKS_PROJECT_DRIFT', 'STACKS_HOST_DRIFT',
+  'STACKS_SERVICE_UNDECLARED', 'STACKS_CI_CONTRADICTION', 'STACKS_CI_UNUSED', 'STACKS_CI_NAME_UNREFERENCED',
+  'STACKS_PLAINTEXT_TRACKED', 'STACKS_ENC_TWIN_MISSING', 'STACKS_GITIGNORE_OPEN', 'STACKS_DECLARATION_IGNORED',
+  'STACKS_GITIGNORE_VALUE_OPEN', 'STACKS_RUNBOOK_IGNORED', 'STACKS_QUALITY_GATE_DRIFT',
+  'CI_DECLARATION_INVALID', 'STACKS_CI_LEGACY_FORM',
+  'STACKS_EXAMPLE_FORM', 'STACKS_PRODUCT_FORM', 'HFS_STACKS_SHAPE',
+];
+/** Paths (under <root>/<environment>/) the ignore rules must deny; they need not exist. */
+const INFRA_VALUE_PROBES = ['infra/compose/.env', 'infra/compose/.env.generated', 'infra/compose/service/.env.local',
+  'infra/compose/tls.key', 'infra/terraform/terraform.tfvars'];
+let schemaCache = null;
+function declarationSchema() {
+  if (!schemaCache) schemaCache = parseYaml(fs.readFileSync(path.join(skillRoot, 'modules', 'schemas', 'application-stacks.schema.yaml'), 'utf8'));
+  return schemaCache;
+}
+const appendSchemaArrayErrors = (out, node, s, where, run) => { node.forEach((item, index) => { if (s.items) out.push(...run(item, s.items, `${where}[${index}]`)); }); };
+const appendSchemaObjectErrors = (out, node, s, where, run) => {
+  if (s.minProperties && Object.keys(node).length < s.minProperties) out.push({ path: where, message: 'object has too few properties' });
+  for (const key of s.required ?? []) if (!Object.hasOwn(node, key)) out.push({ path: where, message: `missing ${key}` });
+  for (const [key, child] of Object.entries(node)) {
+    if (Object.hasOwn(s.properties ?? {}, key)) out.push(...run(child, s.properties[key], `${where}.${key}`));
+    else if (s.additionalProperties === false) out.push({ path: `${where}.${key}`, message: 'unknown field' });
+    else if (plain(s.additionalProperties)) out.push(...run(child, s.additionalProperties, `${where}.${key}`));
+  }
+};
+/** The subset of JSON Schema the declaration schema uses: type, const, enum, pattern, minLength, required, properties, additionalProperties, items, minProperties, minimum, maximum, $ref, anyOf. */
+function schemaErrors(value, shape, at = '$', root = declarationSchema()) {
+  const resolve = (ref) => ref.slice(2).split('/').reduce((node, key) => node?.[key], root);
+  const typeOk = (node, s) => ({ object: plain, array: Array.isArray, integer: Number.isInteger }[s.type] ?? ((n) => (s.type ? typeof n === s.type : true)))(node);
+  const run = (node, s, where) => {
+    if (!plain(s)) return [];
+    if (s.$ref) return run(node, resolve(s.$ref), where);
+    if (Array.isArray(s.anyOf) && !s.anyOf.some((option) => run(node, option, where).length === 0))
+      return [{ path: where, message: 'matches none of the allowed shapes' }];
+    if (!typeOk(node, s)) return [{ path: where, message: `expected ${s.type}` }];
+    const out = [];
+    if (Object.hasOwn(s, 'const') && node !== s.const) out.push({ path: where, message: `must be ${JSON.stringify(s.const)}` });
+    if (Array.isArray(s.enum) && !s.enum.includes(node)) out.push({ path: where, message: `must be one of ${s.enum.join(', ')}` });
+    if (typeof node === 'number' && ((s.minimum !== undefined && node < s.minimum) || (s.maximum !== undefined && node > s.maximum))) out.push({ path: where, message: 'number outside allowed range' });
+    if (typeof node === 'string') out.push(...stringErrors(node, s, where));
+    if (Array.isArray(node)) { appendSchemaArrayErrors(out, node, s, where, run); return out; }
+    if (!plain(node)) return out;
+    appendSchemaObjectErrors(out, node, s, where, run);
+    return out;
+  };
+  const stringErrors = (node, s, where) => {
+    const out = [];
+    if (s.minLength && node.length < s.minLength) out.push({ path: where, message: 'string too short' });
+    if (s.pattern && !new RegExp(s.pattern, 'u').test(node)) out.push({ path: where, message: `does not match ${s.pattern}` });
+    return out;
+  };
+  return run(value, shape, at);
+}
+// ---- locating declarations and repositories -------------------------------------------------------------
+/** A frontend declared by its backend's stack: a sibling declaration whose `sources` lists this repository. */
+function governingDeclaration(repo) {
+  const name = repositoryName(repo);
+  const parent = path.dirname(repositoryHome(repo));
+  let entries = []; try { entries = fs.readdirSync(parent, { withFileTypes: true }); } catch { return null; }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name === name) continue;
+    const file = path.join(parent, entry.name, STACK_ROOT, DECLARATION);
+    if (!isFile(file)) continue;
+    const read = readDeclaration(file);
+    if (read.doc && list(read.doc.sources).some((source) => source?.repository === name))
+      return { repo: path.join(parent, entry.name), root: STACK_ROOT, file, governs: name, ...read };
+  }
+  return null;
+}
+// ---- normalizing a service ------------------------------------------------------------------------------
+const normalizeCredential = (credential, declaringRepo) => {
+  const custody = plain(credential.custody) ? credential.custody : {};
+  const repo = resolveDeclaredRepository(custody.repository, { fromRepo: declaringRepo });
+  const rel = text(custody.path);
+  const abs = resolveCustodyFile(repo, rel);
+  return { id: text(credential.id), env: text(credential.env), key: text(credential.key), purpose: text(credential.purpose),
+    custody: { repository: text(custody.repository), path: rel, resolved: Boolean(repo), file: abs,
+      encPresent: abs ? isFile(`${abs}.enc`) : null, plainPresent: abs ? isFile(abs) : null } };
+};
+const ownerActionOf = (s) => {
+  const noAction = s.ownerAction === 'none' ? 'none' : null;
+  return plain(s.ownerAction) ? { needed: text(s.ownerAction.needed), reason: text(s.ownerAction.reason) } : noAction;
+};
+/** Resolve a declared stack to its host or repository directory without reading custody values. */
+function normalizeStack(stack, entry, declaringRepo) {
+  // owner: host - the stack lives inside the installed runtime tree (.claude/ext/<service>);
+  // `environment` is the slot the extension serves, not a path segment (<root>/<compose> resolves it).
+  const hostOwned = declaredStack(entry)?.hostOwned ?? false;
+  const hostRoot = hostOwned ? slash(stack.root) : null;
+  const extDir = hostRoot && hostRoot.startsWith('.claude/') && !hostRoot.split('/').includes('..')
+    ? path.join(skillRoot, hostRoot.replace(/^\.claude\//, '')) : null;
+  const stackRepo = stack && !hostOwned ? resolveDeclaredRepository(stack.repository, { fromRepo: declaringRepo }) : null;
+  let stackDir = null;
+  if (hostOwned) stackDir = extDir;
+  else if (stackRepo && text(stack.root) && text(stack.environment)) stackDir = path.join(stackRepo, stack.root, stack.environment);
+  return stack ? { owner: text(stack.owner), repository: text(stack.repository), root: text(stack.root), environment: text(stack.environment), compose: text(stack.compose),
+    container: text(stack.container), publishedBy: text(stack.publishedBy), hostOwned, repo: stackRepo, dir: stackDir,
+    composeFile: stackDir && text(stack.compose) ? path.join(stackDir, stack.compose) : null } : null;
+}
+/** One declared service with its custody resolved to presence (never a value). */
+export function normalizeService(id, entry, { declaringRepo } = {}) {
+  const s = plain(entry) ? entry : {};
+  const stack = plain(s.stack) ? s.stack : null;
+  const normalizedStack = normalizeStack(stack, entry, declaringRepo);
+  const credentials = list(s.credentials).filter(plain).map((credential) => normalizeCredential(credential, declaringRepo));
+  const ci = plain(s.ci) ? s.ci : {};
+  return {
+    id, organization: text(s.organization), provider: text(s.provider), mode: text(s.mode), purpose: text(s.purpose), reason: text(s.reason), auth: text(s.auth), qualityGate: text(s.qualityGate),
+    host: { local: text(s.host?.local), public: text(s.host?.public), fromCredential: text(s.host?.fromCredential) },
+    stack: normalizedStack,
+    projects: list(s.projects).filter(plain).map((project) => ({ repository: text(project.repository), key: text(project.key), name: text(project.name) })),
+    credentials,
+    runtimeSecrets: list(s.runtimeSecrets).map(String),
+    ci: { token: text(ci.token), hostVar: text(ci.hostVar),
+      organizationVar: text(ci.organizationVar) || (s.provider === 'sonarcloud' && list(s.runtimeSecrets).length && !credentials.length ? 'SONAR_ORGANIZATION' : null), wiring: text(ci.wiring), workflow: text(ci.workflow), permissions: list(ci.permissions).map(String),
+      secrets: list(ci.secrets).filter(plain).map((item) => ({ name: text(item.name), credential: text(item.credential) })),
+      vars: list(ci.vars).filter(plain).map((item) => ({ name: text(item.name), value: text(item.value) })),
+      provisioning: text(ci.provisioning) },
+    ownerAction: ownerActionOf(s),
+  };
+}
+const custodyHeld = (service) => (service.credentials.length ? service.credentials.every((credential) => credential.custody.encPresent || credential.custody.plainPresent) : ['oidc', 'github-token', 'none'].includes(service.auth));
+/**
+ * What a tool (scripts/gates/sonar-local.mjs, a CI wiring leg) reads for one service of one repository:
+ * the repository's own (or governing) declaration first, then the source host's declaration when its entry
+ * lists this repository among its projects. Null when nothing declares it.
+ */
+export function resolveStackService(repoRoot, serviceId) {
+  const repo = path.resolve(String(repoRoot ?? ''));
+  const name = repositoryName(repo);
+  const own = findStackDeclaration(repo);
+  const candidates = [own.doc ? own : governingDeclaration(repo)].filter(Boolean);
+  const host = runtimeHostRoot();
+  if (path.resolve(host) !== repo) { const source = findStackDeclaration(host); if (source.doc) candidates.push({ ...source, sourceHost: true }); }
+  for (const declaration of candidates) {
+    const entry = declaration.doc?.services?.[serviceId];
+    if (!plain(entry)) continue;
+    let service = normalizeService(serviceId, entry, { declaringRepo: declaration.repo });
+    const listed = service.projects.some((project) => project.repository === name);
+    if (declaration.sourceHost && !listed) continue;
+    // Through the source host a product gets the shared server, its shared credentials and its own project
+    // token (a credential whose id is a project key); other projects' tokens and the host's CI wiring are not its.
+    const ownKey = service.projects.find((project) => project.repository === name)?.key;
+    const projectKeys = new Set(service.projects.map((project) => project.key));
+    if (declaration.sourceHost) service = { ...service, credentials: service.credentials.filter((credential) => !projectKeys.has(credential.id) || credential.id === ownKey),
+      ci: { wiring: null, workflow: null, permissions: [], secrets: [], vars: [], provisioning: null } };
+    return { declaration: declaration.file, declaringRepo: declaration.repo, sourceHost: Boolean(declaration.sourceHost),
+      repository: name, projectKey: service.projects.find((project) => project.repository === name)?.key ?? null, ...service };
+  }
+  return null;
+}
+// ---- repository evidence --------------------------------------------------------------------------------
+function workflowTexts(repo) {
+  const dir = path.join(repo, '.github', 'workflows');
+  let entries = []; try { entries = fs.readdirSync(dir).filter((name) => /\.ya?ml$/i.test(name)); } catch { return []; }
+  return entries.map((name) => ({ file: `.github/workflows/${name}`, text: readText(path.join(dir, name)) ?? '' }));
+}
+function git(call, repo, args) {
+  try {
+    const result = call(args, { dir: repo, timeout: 8000 });
+    if (result.error) return null;
+    return { status: result.status, stdout: String(result.stdout ?? '') };
+  } catch { return null; }
+}
+// ---- the check ------------------------------------------------------------------------------------------
+const checkLocalStack = (service, at, add, ambiguous) => {
+  if (!service.host.local) ambiguous('a local service names host.local, the URL the stack serves it on');
+  if (!service.stack) ambiguous('a local service names the stack that runs it (repository, root, environment, compose) or owns it as a host extension (owner: host, root: .claude/ext/<service>)');
+  else if (service.stack.hostOwned) {
+    if (!service.stack.composeFile || !isFile(service.stack.composeFile))
+      add('refuse', 'STACKS_STACK_UNRESOLVED', `${at}.stack`, `the host extension file ${service.stack.root}/${service.stack.compose} does not exist under the runtime tree (${slash(skillRoot)})`);
+    const publisher = service.stack.publishedBy;
+    if (publisher && service.stack.dir && !isFile(path.join(service.stack.dir, publisher)))
+      add('refuse', 'STACKS_STACK_UNRESOLVED', `${at}.stack.publishedBy`, `the host extension file ${service.stack.root}/${publisher} does not exist under the runtime tree (${slash(skillRoot)})`);
+  }
+  else if (!service.stack.repo) add('suspect', 'STACKS_STACK_UNRESOLVED', `${at}.stack`, `repository ${service.stack.repository} is not checked out on this machine; its compose file and custody are unverified`);
+  else if (!service.stack.composeFile || !isFile(service.stack.composeFile))
+    add('refuse', 'STACKS_STACK_UNRESOLVED', `${at}.stack`, `${service.stack.repository}/${service.stack.root}/${service.stack.environment}/${service.stack.compose} does not exist`);
+};
+const checkServiceCredentials = (service, at, add, ambiguous) => {
+  const ids = new Set();
+  for (const credential of service.credentials) {
+    const where = `${at}.credentials.${credential.id ?? '?'}`;
+    if (credential.id && ids.has(credential.id)) ambiguous(`credential id ${credential.id} is declared twice`);
+    ids.add(credential.id);
+    if (!credential.env && !credential.key) ambiguous(`credential ${credential.id ?? '?'} names the env variable or the file key its consumer reads`);
+    if (!credential.custody.resolved) add('suspect', 'STACKS_CUSTODY_UNVERIFIED', where, `custody repository ${credential.custody.repository} is not checked out on this machine`);
+    else if (!credential.custody.encPresent)
+      add('refuse', 'STACKS_CUSTODY_MISSING', where, `${credential.custody.repository}/${credential.custody.path}.enc is not in custody; repair the stack custody (secret:gen / stack-secret) - never ask the owner for a value the declaration says the runtime holds`);
+  }
+  return ids;
+};
+const checkCiNames = (service, id, at, ciUses, ciText, add) => { if (['required', 'optional-follow-up'].includes(service.ci.wiring) && ciUses[id].length) for (const item of [...service.ci.secrets, ...service.ci.vars]) if (item.name && !new RegExp(String.raw`\b${escapeRegExp(item.name)}\b`).test(ciText)) add('suspect', 'STACKS_CI_NAME_UNREFERENCED', `${at}.ci`, `${item.name} is declared for CI but no workflow reads it`); };
+const checkServiceCi = (service, id, at, { governing, name, ciUses, ciText, add, ambiguous }) => {
+  const ids = checkServiceCredentials(service, at, add, ambiguous);
+  for (const secret of service.ci.secrets)
+    if (secret.credential && !ids.has(secret.credential)) ambiguous(`ci secret ${secret.name} names credential ${secret.credential}, which the service does not declare`);
+  if (plain(service.ownerAction) && service.credentials.length && custodyHeld(service))
+    add('refuse', 'STACKS_OWNER_ACTION_REDUNDANT', `${at}.ownerAction`, 'every credential is already in custody; ownerAction must be none - the owner is never asked for what the runtime holds');
+  if (service.ci.wiring === 'not-used' && ciUses[id].length)
+    add('refuse', 'STACKS_CI_CONTRADICTION', `${at}.ci`, `ci.wiring not-used, but ${ciUses[id].join(', ')} call it`);
+  // A frontend governed by its backend declaration answers only for the services that name it as a project:
+  // the backend CI wiring (its image registry, say) is not the frontend's to call.
+  const servesThisRepository = !governing || service.projects.some((project) => project.repository === name);
+  if (service.ci.wiring === 'required' && !ciUses[id].length && SERVICE_CATALOG[id].ci.length && servesThisRepository)
+    add('suspect', 'STACKS_CI_UNUSED', `${at}.ci`, 'ci.wiring required, but no workflow calls the service');
+  checkCiNames(service, id, at, ciUses, ciText, add);
+  if (ciUses[id].length && service.projects.length && !service.projects.some((project) => project.repository === name) && !governing)
+    add('refuse', 'STACKS_PROJECT_MISSING', `${at}.projects`, `the workflows call ${id} but no project entry names repository ${name}`);
+};
+const checkDisabledService = (service, id, at, ciUses, ambiguous, add) => { if (service.mode !== 'disabled') { return false; } if (!service.reason) { ambiguous('a disabled service states its reason'); } if (ciUses[id].length) { add('refuse', 'STACKS_CI_CONTRADICTION', at, `declared disabled, but ${ciUses[id].join(', ')} call it`); } return true; };
+const checkEnabledService = (service, id, at, { governing, name, ciUses, ciText, add, kind }, ambiguous) => {
+  checkSecretForm(service, id, at, kind, add);
+  if (service.mode === 'local') checkLocalStack(service, at, add, ambiguous);
+  if (service.mode === 'hosted' && !service.host.public && !service.host.fromCredential) ambiguous('a hosted service names host.public, or host.fromCredential when the endpoint travels inside a credential');
+  if (ciUses[id].length && service.ci.wiring !== 'not-used' && !service.host.public) ambiguous('GitHub CI reaches a service only through host.public; name it');
+  if (!service.auth) ambiguous('auth is token, oidc, github-token or none');
+  if (service.auth === 'token' && !service.credentials.length && !service.runtimeSecrets.length && !service.ci.token) ambiguous('auth token names at least one credential in custody, or the runtime secret.env variables an example reads (runtimeSecrets)');
+  if (service.host.fromCredential && !service.credentials.some((credential) => credential.id === service.host.fromCredential)) ambiguous(`host.fromCredential names ${service.host.fromCredential}, which is not one of its credentials`);
+  if (!service.projects.length) ambiguous('an enabled service lists the project key of every repository it serves');
+  checkServiceCi(service, id, at, { governing, name, ciUses, ciText, add, ambiguous });
+};
+const checkService = (id, entry, { schema, declFile, declaration, governing, name, ciUses, ciText, normalized, add, kind }) => {
+  if (entry?.badgeToken !== undefined && !['codecov', 'sonar'].includes(id)) add('refuse', 'STACKS_BADGE_TOKEN_SERVICE', `${declFile}#services.${id}.badgeToken`, 'badgeToken is allowed only on codecov or sonar');
+  if (!Object.hasOwn(SERVICE_CATALOG, id)) {
+    add('refuse', 'STACKS_SERVICE_UNKNOWN', `${declFile}#services.${id}`, `${id} is not a catalogued service (${Object.keys(SERVICE_CATALOG).join(', ')}); a service the catalog does not know is one nobody can read unambiguously`);
+    return;
+  }
+  for (const issue of schemaErrors(entry, ['dependabot', 'audit'].includes(id) ? schema.$defs.serviceOptionalCi : schema.$defs.service, `services.${id}`))
+    add('refuse', 'STACKS_SCHEMA_INVALID', `${declFile}#${issue.path}`, issue.message);
+  const service = normalizeService(id, entry, { declaringRepo: declaration.repo });
+  normalized[id] = service;
+  const at = `${declFile}#services.${id}`;
+  const ambiguous = (message) => add('refuse', 'STACKS_SERVICE_AMBIGUOUS', at, message);
+  checkServiceForm(service, id, entry, at, kind, add, ambiguous);
+  if (checkDisabledService(service, id, at, ciUses, ambiguous, add)) return;
+  if (checkQualityService(service, id, at, { governing, name, ciUses, ciText, add, ambiguous }, checkServiceCi)) return;
+  checkEnabledService(service, id, at, { governing, name, ciUses, ciText, add, kind }, ambiguous);
+};
+const checkUndeclared = ({ repo, ciUses, normalized, services, declFile, add }) => {
+  for (const [id, files] of Object.entries(ciUses)) {
+    if (['codecov', 'dependabot', 'audit'].includes(id)) continue;
+    if (!files.length || normalized[id] || (services && Object.hasOwn(services, id))) continue;
+    const viaSource = resolveStackService(repo, id);
+    if (viaSource && !services) continue;
+    const followUp = services ? '' : ` - follow-up: ${FOLLOW_UP.op} mode stacks`;
+    add(services ? 'refuse' : 'suspect', 'STACKS_SERVICE_UNDECLARED', declFile,
+      `${files.join(', ')} call ${id}, which the declaration does not state${followUp}`);
+  }
+};
+const checkQualityGate = (sonar, normalized, declFile, add, repo) => { if (!sonar || sonar.mode === 'disabled') { return; } const gateName = loadSonarGate({ cwd: repo }).gate.name; if (sonar.qualityGate !== gateName) { add(normalized.sonar ? 'refuse' : 'suspect', 'STACKS_QUALITY_GATE_DRIFT', `${declFile}#services.sonar.qualityGate`, `services.sonar.qualityGate is ${sonar.qualityGate ?? 'absent'}; every product names the one gate ${gateName} (knowledge/sonar-gate.yaml owns its thresholds)`); } };
+// Sonar settings the repository carries must agree with the declaration, and every repository names the one quality gate.
+const checkSonarDrift = ({ repo, name, normalized, services, declFile, add }) => {
+  const sonar = normalized.sonar ?? (services ? null : resolveStackService(repo, 'sonar'));
+  const props = readProperties(path.join(repo, 'sonar-project.properties'));
+  if (sonar && sonar.mode !== 'disabled' && Object.keys(props).length) {
+    const declared = sonar.projects.find((project) => project.repository === name)?.key;
+    if (declared && props['sonar.projectKey'] && props['sonar.projectKey'] !== declared)
+      add(normalized.sonar ? 'refuse' : 'suspect', 'STACKS_PROJECT_DRIFT', 'sonar-project.properties', `sonar.projectKey ${props['sonar.projectKey']} but the declaration names ${declared}`);
+    if (sonar.host.public && props['sonar.host.url'] && trimTrailingSlashes(props['sonar.host.url']) !== trimTrailingSlashes(sonar.host.public))
+      add('suspect', 'STACKS_HOST_DRIFT', 'sonar-project.properties', `sonar.host.url ${props['sonar.host.url']} but the declaration's public host is ${sonar.host.public}`);
+  }
+  // The one quality gate (knowledge/sonar-gate.yaml): a repository names it, never its own thresholds.
+  checkQualityGate(sonar, normalized, declFile, add, repo);
+};
+const checkTrackedCustody = ({ repo, root, add }) => {
+  const tracked = git(lsFiles, repo, ['--', root]);
+  if (tracked?.status !== 0) return;
+  for (const file of tracked.stdout.split(/\r?\n/).filter(Boolean)) {
+    const parts = slash(file).split('/');
+    const custodyArea = parts.length > 3 && (parts[2] === 'runtime' || parts[2] === 'secrets');
+    const base = parts.at(-1);
+    // infra/** is tracked source, but a value file inside it (.env*, *.env, *.key, *.pem, *.tfvars)
+    // is plaintext custody (inc-5360513a96b3: infra/compose/.env.generated was trackable).
+    const infraValue = parts.length > 3 && parts[2] === 'infra' && isInfrastructureValueFile(base) && !base.endsWith('.enc') && !base.endsWith('.example');
+    if ((custodyArea && !base.endsWith('.enc') && !['KEYS.md', '.gitkeep'].includes(base)) || infraValue)
+      add('refuse', 'STACKS_PLAINTEXT_TRACKED', file, /\.enc\.(?:ya?ml|json|env)$/u.test(base)
+        ? `${base} is named the wrong way round: a custody file is <name>.<fmt>.enc (rename it to ${base.replace(/\.enc\.(ya?ml|json|env)$/u, '.$1.enc')}) and every read states the format (scripts/api/sops/exec-env.mjs)`
+        : 'a custody member is tracked in plaintext; untrack it (git rm --cached), rotate the value and commit only its .enc twin');
+  }
+};
+const checkEncTwins = ({ repo, root, add }) => {
+  for (const env of envDirs(repo, root)) {
+    const filesDir = path.join(repo, root, env.name, 'runtime', 'files');
+    let members = [];
+    try { members = fs.readdirSync(filesDir); } catch { continue; }
+    const bare = members.filter((member) => !member.endsWith('.enc') && !/\.md$/i.test(member) && member !== '.gitkeep'
+      && !/\.(rotation-pending|bak)$/.test(member) && !members.includes(`${member}.enc`));
+    if (bare.length) add('suspect', 'STACKS_ENC_TWIN_MISSING', `${root}/${env.name}/runtime/files`,
+      `${bare.length} plaintext custody member(s) have no .enc twin (${bare.slice(0, 5).join(', ')}${bare.length > 5 ? ', ...' : ''}); encrypt them (stack-secret) so another machine can decrypt them`);
+  }
+};
+const checkIgnoreRules = ({ repo, root, add }) => {
+  // The rules must still deny a value file under infra AFTER the infra re-includes
+  // (stacks-layout.yaml custody.gitignoreRules). git check-ignore --no-index answers for paths
+  // that do not exist yet, so the probe proves the rule, not today's files.
+  for (const env of envDirs(repo, root)) {
+    const open = INFRA_VALUE_PROBES.map((probe) => `${root}/${env.name}/${probe}`)
+      .filter((rel) => git(checkIgnore, repo, ['-q', '--no-index', '--', rel])?.status === 1);
+    if (open.length) add('refuse', 'STACKS_GITIGNORE_VALUE_OPEN', '.gitignore',
+      `the ignore rules leave plaintext value files under ${root}/${env.name}/infra trackable (${open.join(', ')}); deny them after the infra re-includes and re-include *.enc last (modules/schemas/stacks-layout.yaml custody.gitignoreRules)`);
+    // The environment runbook is part of the layout contract (stacks-layout.yaml shape.runbook);
+    // rules that hide it strand it on one machine.
+    const runbook = `${root}/${env.name}/README.md`;
+    if (git(checkIgnore, repo, ['-q', '--no-index', '--', runbook])?.status === 0)
+      add('suspect', 'STACKS_RUNBOOK_IGNORED', runbook, `the ignore rules hide the ${env.name} runbook; re-include it (!${runbook}) so every machine reads it`);
+  }
+};
+// Custody layout (modules/schemas/stacks-layout.yaml custody, the product repositories' secrets-guard).
+const envDirs = (repo, root) => fs.readdirSync(path.join(repo, root), { withFileTypes: true }).filter((entry) => entry.isDirectory());
+const checkCustodyLayout = ({ repo, own, add }) => {
+  if (!own.rooted) return;
+  const root = STACK_ROOT;
+  checkTrackedCustody({ repo, root, add });
+  checkEncTwins({ repo, root, add });
+  const ignore = readText(path.join(repo, '.gitignore')) ?? '';
+  if (!new RegExp(String.raw`^/?${escapeRegExp(root)}/\*\*\s*$`, 'm').test(ignore))
+    add('suspect', 'STACKS_GITIGNORE_OPEN', '.gitignore', `no deny-all rule \`${root}/**\`; custody plaintext is only safe when the tree is denied and *.enc, KEYS.md and the declaration are re-included`);
+  checkIgnoreRules({ repo, root, add });
+};
+const buildResult = ({ repo, name, newRepo, declaration, governing, normalized, findings }) => {
+  const pick = (level) => findings.filter((finding) => finding.level === level).map((finding) => `${finding.file}: ${finding.message} [${finding.code}]`);
+  const refused = pick('refuse');
+  const needsFollowUp = findings.some((finding) => ['STACKS_DECLARATION_MISSING', 'STACKS_SERVICES_MISSING', 'STACKS_SERVICE_UNDECLARED'].includes(finding.code) && finding.level !== 'refuse');
+  return {
+    schema: RESULT_SCHEMA, ok: refused.length === 0, repository: name, repoRoot: slash(repo), newRepo,
+    declaration: declaration?.file ? slash(declaration.file) : null, root: declaration?.root ?? null,
+    governedBy: governing ? slash(governing.repo) : null,
+    services: Object.fromEntries(Object.entries(normalized).map(([id, service]) => [id, summary(service)])),
+    refused, suspect: pick('suspect'), findings,
+    ...(needsFollowUp ? { followUp: { ...FOLLOW_UP, ...(isFile(path.join(skillRoot, STACK_DECLARATION_TEMPLATE)) ? { fixture: STACK_DECLARATION_TEMPLATE } : {}) } } : {}),
+  };
+};
+const declarationView = (own, governing, missingLevel, shown, add) => {
+  const declaration = own.missing ? governing : own;
+  if (own.missing && !governing) add(missingLevel, 'STACKS_DECLARATION_MISSING', `.starcistacks/${DECLARATION}`, `no stack declaration (.starcistacks/${DECLARATION}); the services this repository's CI uses are undeclared - follow-up: ${FOLLOW_UP.op} mode stacks`);
+  if (declaration?.error) add('refuse', 'STACKS_DECLARATION_INVALID', shown(declaration.file), declaration.error);
+  if (declaration?.doc && declaration.doc.schema !== DECLARATION_SCHEMA) add('refuse', 'STACKS_DECLARATION_INVALID', shown(declaration.file), `schema must be ${DECLARATION_SCHEMA}`);
+  const doc = declaration?.doc ?? null, services = plain(doc?.services) ? doc.services : null;
+  const declFile = declaration?.file ? shown(declaration.file) : `.starcistacks/${DECLARATION}`;
+  if (doc && !Object.hasOwn(doc, 'services')) add(missingLevel, 'STACKS_SERVICES_MISSING', declFile, `the declaration has no services block; declare sonar and every other delivery/quality service the repository uses - follow-up: ${FOLLOW_UP.op} mode stacks`);
+  return { declaration, services, declFile };
+};
+const checkDeclaredServices = ({ services, declaration, governing, name, ciUses, ciText, declFile, normalized, add, kind }) => {
+  if (!services) return;
+  const schema = declarationSchema(), ctx = { schema, declFile, declaration, governing, name, ciUses, ciText, normalized, add, kind };
+  for (const [id, entry] of Object.entries(services)) checkService(id, entry, ctx);
+};
+const checkDeclarationIgnore = (own, repo, shown, add) => {
+  if (!own.missing && own.file) {
+    const ignored = git(checkIgnore, repo, ['-q', '--', slash(path.relative(repo, own.file))]);
+    if (ignored?.status === 0) add('suspect', 'STACKS_DECLARATION_IGNORED', shown(own.file), `the ignore rules hide the declaration; re-include it (!${slash(path.relative(repo, own.file))}) so every machine reads the same services`);
+  }
+};
+/**
+ * The whole check for one repository. `newRepo`: the leg creates this repository, so what it lacks is
+ * refused under the current declaration and custody rules.
+ */
+export function checkStarciStacks(repoRoot, { newRepo = false, examplesRoot = path.join(skillRoot, 'examples') } = {}) {
+  const repo = path.resolve(String(repoRoot ?? ''));
+  const name = repositoryName(repo);
+  const findings = [];
+  const add = (level, code, file, message) => findings.push({ level, code, file: slash(file), message });
+  const missingLevel = newRepo ? 'refuse' : 'suspect', own = findStackDeclaration(repo);
+  const governing = own.missing ? governingDeclaration(repo) : null;
+  const shown = (file) => slash(path.relative(repo, file)) || '.';
+  const { declaration, services, declFile } = declarationView(own, governing, missingLevel, shown, add);
+  checkCiDeclaration(declaration, declFile, kindOf(repo, examplesRoot), declarationSchema, schemaErrors, add);
+  // CI evidence: which services the workflows call, and which secret/variable names they read.
+  const workflows = workflowTexts(repo);
+  const ciText = workflows.map((workflow) => workflow.text).join('\n');
+  const ciUses = Object.fromEntries(Object.entries(SERVICE_CATALOG).map(([id, entry]) => [id, workflows.filter((workflow) => entry.ci.some((re) => re.test(workflow.text))).map((workflow) => workflow.file)]));
+  const normalized = {};
+  checkDeclaredServices({ services, declaration, governing, name, ciUses, ciText, declFile, normalized, add, kind: kindOf(repo, examplesRoot) });
+  checkUndeclared({ repo, ciUses, normalized, services, declFile, add });
+  checkSonarDrift({ repo, name, normalized, services, declFile, add });
+  checkCustodyLayout({ repo, own, add });
+  checkDeclarationIgnore(own, repo, shown, add);
+  for (const item of applicationStackFindings(repo)) add('refuse', item.code, item.path, item.message);
+  return buildResult({ repo, name, newRepo, declaration, governing, normalized, findings });
+}
+/** A report-safe view: custody as presence, never a value. */
+function summary(service) {
+  return { provider: service.provider, mode: service.mode, auth: service.auth, host: service.host,
+    stack: service.stack ? { owner: service.stack.owner ?? null, repository: service.stack.repository, root: service.stack.root, environment: service.stack.environment, compose: service.stack.compose, container: service.stack.container } : null,
+    projects: service.projects, credentials: service.credentials.map((credential) => ({ id: credential.id, env: credential.env, key: credential.key,
+      custody: `${credential.custody.repository}/${credential.custody.path}`, present: credential.custody.encPresent ?? null })),
+    ci: service.ci, ownerAction: service.ownerAction };
+}
+// ---- the owner-ask guard --------------------------------------------------------------------------------
+const asksAboutCustody = (body) => /\b(tokens?|secrets?|credentials?|api[ _-]?keys?|passwords?|host|url|access)\b/i.test(body) || /\b(github|repository) (settings?|secrets?|variables?)\b|\bSONAR_[A-Z_]+/i.test(body);
+/**
+ * An ask that requests what a stack declaration already answers: a service declared `ownerAction: none`
+ * whose custody is present (or needs none), named by one of its credential/CI variable names or by the
+ * service's name next to a credential word. Returns {service, provider, declaration, matched, message}
+ * or null. Declarations read: the asking repository's own (or governing) one, then the source host's
+ * when its entry lists this repository.
+ */
+export function ownerAskConflict({ repo, question } = {}) {
+  if (!repo || question === undefined || question === null) return null;
+  const body = typeof question === 'string' ? question : JSON.stringify(question);
+  for (const id of Object.keys(SERVICE_CATALOG)) {
+    const service = resolveStackService(repo, id);
+    if (!service || service.mode === 'disabled' || service.ownerAction !== 'none' || !custodyHeld(service)) continue;
+    const names = [...service.credentials.map((credential) => credential.env), ...service.ci.secrets.map((item) => item.name), ...service.ci.vars.map((item) => item.name)].filter(Boolean);
+    const byName = names.find((item) => new RegExp(String.raw`\b${escapeRegExp(item)}\b`).test(body));
+    const words = [...new Set([id, service.provider, ...SERVICE_CATALOG[id].words].filter(Boolean))];
+    const byWord = words.find((word) => new RegExp(String.raw`\b${escapeRegExp(word)}\b`, 'i').test(body));
+    if (!byName && !(byWord && asksAboutCustody(body))) continue;
+    const custody = service.credentials.map((credential) => `${credential.custody.repository}/${credential.custody.path}`);
+    const custodyNote = custody.length ? ` and its credentials in custody (${custody.join(', ')})` : ` and auth ${service.auth}`;
+    const sonarNote = id === 'sonar' ? 'Run starci gate sonar (status, ensure-project, scan) - it reads host, project and token from the declaration and custody. ' : '';
+    const provisioningNote = service.ci.provisioning ? ` (${service.ci.provisioning})` : '';
+    return { service: id, provider: service.provider, declaration: slash(service.declaration), matched: byName ?? byWord,
+      message: `${id} (${service.provider}, ${service.mode}) is declared in ${slash(service.declaration)} with ownerAction none${custodyNote}; the owner is never asked for it. ${sonarNote}CI wiring is ${service.ci.wiring ?? 'undeclared'}${provisioningNote}.` };
+  }
+  return null;
+}
+// ---- CLI ------------------------------------------------------------------------------------------------
+const USAGE = 'Usage: starci gate starcistacks <repo-root> [--new] [--json]\n\nHolds a repository\'s stack declaration services block (sonar, codecov, dependabot, audit, container-registry, analytics, error-tracking) and its custody layout to modules/schemas/application-stacks.schema.yaml and stacks-layout.yaml. Exit 0 clean (suspects allowed), 1 refused, 2 usage.\n';
+async function checkStarciStacksMain(argv = []) {
+  const rest = argv;
+  const args = rest.filter((arg) => !['--json', '--new'].includes(arg));
+  if (args.includes('--help') || args.includes('-h')) return { exitCode: 0, text: USAGE };
+  if (args.length !== 1) return { exitCode: 2, text: USAGE };
+  if (!isDir(args[0])) return { exitCode: 2, text: `${args[0]}: not a directory\n` };
+  const result = checkStarciStacks(args[0], { newRepo: rest.includes('--new') });
+  if (rest.includes('--json')) return { exitCode: result.ok ? 0 : 1, text: `${JSON.stringify(result, null, 2)}\n` };
+  const lines = [...result.refused.map((line) => `  REFUSED ${line}`), ...result.suspect.map((line) => `  SUSPECT ${line}`)];
+  const fixtureNote = result.followUp?.fixture ? ` from ${result.followUp.fixture}` : '';
+  if (result.followUp) lines.push(`  follow-up: ${result.followUp.op} mode ${result.followUp.params.mode}${fixtureNote}`);
+  const listing = `${lines.join('\n')}${lines.length ? '\n' : ''}`;
+  const verdict = `${result.ok ? 'OK' : 'FAIL'}: starcistacks ${result.repository} - ${result.refused.length} refused, ${result.suspect.length} suspect, services: ${Object.keys(result.services).join(', ') || 'none declared'}.\n`;
+  return { exitCode: result.ok ? 0 : 1, text: `${listing}${verdict}` };
+}
+if (isMain(import.meta.url)) {
+  try {
+    const { exitCode, text: out } = await checkStarciStacksMain(process.argv.slice(2));
+    process.stdout.write(out); process.exitCode = exitCode;
+  } catch (error) {
+    process.stderr.write(`check-starcistacks: ${error?.stack ?? error}\n`); process.exitCode = 2;
+  }
+}

package/runtime/scripts/hfs/app-wiring.mjs

@@ -24,7 +24,7 @@ const COMPILATION_FAILURE = 'module or proof could not be compiled';
 const WORKER_FAILURE = 'proof worker failed or timed out';
 const SAFE_REASONS = new Set([...DI_FAILURES.values(), COMPILATION_FAILURE]);
 const modulePath = app => `apps/${app}/src/app.module.ts`;
-const wiringFixturePath = app => `src/tests/fixtures/builders/${app}.builder.ts`;
+export const wiringFixturePath = app => `src/tests/fixtures/builders/${app}.builder.ts`;
 
 const refusal = (file, reason) => ({ code: BOOT_PROOF_CODE, level: 'error', path: file,
   message: `${file}: lite boot proof failed (${reason}); compile the real AppModule with explicit fixture options and infrastructure doubles using starci app check --wiring`, reason });
@@ -177,7 +177,7 @@ export function appWiring({ repoRoot, repo = readJson(repoRoot, 'hfs.json'), fil
 }
 
 /** Optional standalone entry; coordinator connects the same seam to app check --wiring. */
-function appWiringMain(argv, { cwd = invocationDir(), stdout = text => process.stdout.write(text), stderr = text => process.stderr.write(text) } = {}) {
+export function appWiringMain(argv, { cwd = invocationDir(), stdout = text => process.stdout.write(text), stderr = text => process.stderr.write(text) } = {}) {
   let directory = cwd, json = false;
   for (let at = 0; at < argv.length; at += 1) {
     if (argv[at] === '--cwd' && argv[at + 1]) directory = path.resolve(cwd, argv[++at]);

package/runtime/scripts/hfs/architecture/supabase.mjs

@@ -209,7 +209,7 @@ export function checkBackendSupabase(input) {
   };
 }
 
-function checkJwtPolicy(input) {
+export function checkJwtPolicy(input) {
   const kit = machineKit(input);
   const violations = [];
   let verifyCalls = 0;

package/runtime/scripts/hfs/check.mjs

@@ -32,6 +32,7 @@
 //   BE_SPEC_PLACEMENT             (R102, rules/spec-placement.mjs) a spec or test file outside the four test layers, scripts/ and tools/ included
 //   HFS_REPO_LOCAL_CHECK          (R103, 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, rules/lint-suppression.mjs) an eslint suppressions file, script or option
+//   HFS_BYPASS_MARKER             (R303, rules/bypass-markers.mjs) an inline disable, type-check escape, skipped test or swallowed failure
 //   HFS_PROOF_COMMAND_FILE_MISSING (R105, rules/proof-commands.mjs) a .starciwork proof command that runs a file the repository does not hold
 //   HFS_PEER_INTEGRATION_MISSING  (R111, rules/peer-integrations.mjs) the app root package.json lacks the runtime peer a driver integration needs
 //   BE_INTEGRATION_SPEC_MISSING   (R112, rules/integration-specs.mjs) an integration with no integration spec that registers its module, maps its refusals and drives an outage
@@ -77,6 +78,7 @@ import { mcpToolsSnapshotFindings } from './rules/mcp-tools.mjs';
 import { appRootFindings } from './rules/app-root.mjs';
 import { frontendFindings } from './rules/frontend-tree.mjs';
 import { lintSuppressionFindings } from './rules/lint-suppression.mjs';
+import { bypassMarkerFindings } from './rules/bypass-markers.mjs';
 import { repoLocalCheckFindings } from './rules/repo-local-checks.mjs';
 import { supabaseSecretFindings } from './rules/supabase-secrets.mjs';
 import { untrackedSecretFindings } from './rules/secrets.mjs';
@@ -105,7 +107,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', 'HFS_MCP_TOOLS_SNAPSHOT',
-  'BE_TEST_TOPOLOGY', 'BE_SPEC_PLACEMENT', 'HFS_REPO_LOCAL_CHECK', 'HFS_LINT_SUPPRESSION_FILE', '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',
+  '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_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', 'DB_CONFIG_POLICY', 'DB_TYPES_DRIFT',
   'HFS_DOCKER_HEALTHCHECK_FAKE', 'DB_BE_ONLY_ACCESS', 'DB_REALTIME_UNLISTED', 'DB_APP_ROLE', 'DB_FORCE_RLS_DEFAULT',
@@ -213,6 +215,7 @@ function contentRuleFindings({ repoRoot, repo, resolver, files, all, scoped, pin
     ...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 }));

package/runtime/scripts/hfs/coverage-from.mjs

@@ -55,7 +55,7 @@ export function formatCoverageReport(report) {
 }
 
 /** Standalone coordinator entry point: exit 0 proof passed, 2 proof or invocation refused. */
-function coverageFromMain(argv, { cwd = invocationDir(), stdout = (text) => process.stdout.write(text), stderr = (text) => process.stderr.write(text), run = coverageFrom } = {}) {
+export function coverageFromMain(argv, { cwd = invocationDir(), stdout = (text) => process.stdout.write(text), stderr = (text) => process.stderr.write(text), run = coverageFrom } = {}) {
   try {
     const opts = parse(argv);
     const report = run({ repoRoot: path.resolve(cwd, opts.cwd ?? '.'), coverageFrom: opts.coverageFrom });

package/runtime/scripts/hfs/manifest-shape.mjs

@@ -84,7 +84,7 @@ export const MANIFEST_KINDS = [APP_KIND, RUNTIME_KIND];
 export const manifestKind = (m) => (isPlainObject(m) && m.kind !== undefined ? m.kind : APP_KIND);
 const strList = (v) => stringList(v);
 
-const APP_SLOT_KEYS = ['id', 'profiles', 'path', 'presence', 'tracked', 'tier', 'tests', 'owner', 'appKind', 'minInstances', 'requiredWhen', 'requiredInstances', 'requires', 'pattern', 'trigger', 'allows', 'forbids', 'layers', 'kinds', 'roles', 'composedBy', 'budget', 'managedBy', 'liteManagedBy', 'rules', 'goesTo', 'why', 'since', 'perConnection', 'parent', 'editions', 'editionWhy', 'litePresence', 'lite', 'provider', 'coverage', 'entries', 'outcomeHome', 'templateNa', 'exampleNa', 'exemplifiedBy'];
+const APP_SLOT_KEYS = ['id', 'profiles', 'path', 'presence', 'tracked', 'tier', 'tests', 'owner', 'appKind', 'minInstances', 'requiredWhen', 'requiredInstances', 'requires', 'pattern', 'trigger', 'allows', 'forbids', 'layers', 'kinds', 'roles', 'composedBy', 'budget', 'managedBy', 'liteManagedBy', 'rules', 'goesTo', 'why', 'since', 'perConnection', 'parent', 'editions', 'editionWhy', 'litePresence', 'lite', 'provider', 'coverage', 'entries', 'outcomeHome', 'templateNa', 'exemplifiedBy'];
 /** The fields a slot's `lite` overlay may hold: the same keys it would carry in the slot body, resolved under edition lite. */
 const LITE_OVERLAY_KEYS = ['path', 'requires', 'allows', 'forbids', 'minInstances', 'requiredInstances', 'why'];
 /** A runtime slot has no app kind, side composition, layer or managed template; it may name the generator of a generated copy. */
@@ -218,8 +218,6 @@ function slotCoverageEvidenceProblems(slot, at) {
   const bad = [];
   if (slot.templateNa !== undefined && !(typeof slot.templateNa === 'string' && slot.templateNa.trim()))
     bad.push(`${at}: templateNa must be non-empty text`);
-  if (slot.exampleNa !== undefined && !(typeof slot.exampleNa === 'string' && slot.exampleNa.trim()))
-    bad.push(`${at}: exampleNa must be non-empty text`);
   if (slot.exemplifiedBy === undefined) return bad;
   const refs = slot.exemplifiedBy;
   const valid = Array.isArray(refs) && refs.length > 0 && refs.every(slotEvidenceRefValid)