redlinegate 0.0.1

package/scripts/validate.mjs

@@ -0,0 +1,394 @@
+#!/usr/bin/env node
+// Bundle self-check. This repo enforces standards on hundreds of others; it has to hold
+// itself to the same bar. Run by .github/workflows/ci.yml.
+
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { ROOT, RANK, loadRules, parseFinding, RESERVED_RULE_IDS, RULE_ID } from './lib/rules.mjs';
+const errors = [];
+const warnings = [];
+
+const fail = (msg) => errors.push(msg);
+const warn = (msg) => warnings.push(msg);
+const read = (rel) => readFileSync(join(ROOT, rel), 'utf8');
+
+// --- manifest integrity -----------------------------------------------------
+const manifest = JSON.parse(read('standards/manifest.json'));
+
+if (!/^\d+\.\d+\.\d+$/.test(manifest.version)) fail(`manifest version "${manifest.version}" is not semver`);
+if (!existsSync(join(ROOT, manifest.core.source))) fail(`core source missing: ${manifest.core.source}`);
+
+for (const [id, stack] of Object.entries(manifest.stacks)) {
+  if (!existsSync(join(ROOT, stack.source))) fail(`stack "${id}": source missing (${stack.source})`);
+  if (!stack.globs?.length) fail(`stack "${id}": no globs`);
+  for (const glob of stack.globs ?? []) {
+    // Copilot's applyTo is a plain comma-separated glob list. Negation and brace
+    // expansion are not portable across Copilot, Cursor and AGENTS.md consumers.
+    if (glob.startsWith('!')) fail(`stack "${id}": negated glob "${glob}" is not supported by applyTo`);
+    if (glob.includes('{')) fail(`stack "${id}": brace expansion "${glob}" is not portable — list globs separately`);
+    if (glob.includes(',')) fail(`stack "${id}": glob "${glob}" contains a comma, which is the applyTo separator`);
+  }
+  for (const parent of stack.extends ?? []) {
+    if (!manifest.stacks[parent]) fail(`stack "${id}": extends unknown stack "${parent}"`);
+  }
+}
+
+for (const [name, stacks] of Object.entries(manifest.profiles)) {
+  if (!stacks.length) fail(`profile "${name}" is empty`);
+  for (const id of stacks) {
+    if (!manifest.stacks[id]) fail(`profile "${name}": unknown stack "${id}"`);
+  }
+}
+
+for (const [alias, target] of Object.entries(manifest.profileAliases)) {
+  if (!manifest.profiles[target]) fail(`profile alias "${alias}" points at unknown profile "${target}"`);
+  if (manifest.profiles[alias]) fail(`profile alias "${alias}" shadows a real profile`);
+}
+
+const unusedStacks = Object.keys(manifest.stacks).filter(
+  (id) => !Object.values(manifest.profiles).some((p) => p.includes(id))
+);
+if (unusedStacks.length) warn(`stacks in no profile (will never be distributed): ${unusedStacks.join(', ')}`);
+
+// --- the severity contract has to survive edits ------------------------------
+const core = read(manifest.core.source);
+for (const token of ['Redline/BLOCKER', 'Redline/HIGH', 'Redline/SUGGESTION']) {
+  if (!core.includes(token)) fail(`core standard no longer documents "${token}" — telemetry parsing depends on it`);
+}
+if (!core.includes('What NOT to flag')) fail('core standard lost its "What NOT to flag" section');
+if (!core.includes('[rule-id]')) fail('core standard no longer documents the rule-id part of the output contract');
+for (const reserved of RESERVED_RULE_IDS) {
+  if (!core.includes(reserved)) fail(`core standard must document the reserved id "${reserved}"`);
+}
+
+// The parser and the documented contract must not drift apart: parse the example the
+// standard itself gives and confirm it yields what the pipeline expects.
+const example = parseFinding('Redline/BLOCKER [core/query-string-concatenation]: example');
+if (example.severity !== 'BLOCKER' || example.ruleId !== 'core/query-string-concatenation') {
+  fail('the finding parser cannot parse the output contract documented in the core standard');
+}
+
+// --- rule catalogue -----------------------------------------------------------
+const rules = loadRules();
+if (rules.size < 200) fail(`only ${rules.size} rules carry an id — run: node scripts/assign-rule-ids.mjs`);
+
+for (const [id, rule] of rules) {
+  if (!RULE_ID.test(id)) fail(`rule id "${id}" is not <stack>/<slug> in kebab-case`);
+  const [prefix] = id.split('/');
+  if (prefix !== rule.stack) {
+    fail(`rule "${id}" lives in ${rule.source} but is prefixed "${prefix}" instead of "${rule.stack}"`);
+  }
+  if (id.split('/')[1].length < 4) warn(`rule id "${id}" has a very short slug — it should read as a name`);
+}
+
+// Every normative bullet must carry an id, or telemetry silently loses it.
+const idsAssigned = readdirSync(join(ROOT, 'standards/stacks'))
+  .map((f) => `standards/stacks/${f}`)
+  .concat(['standards/core.md']);
+for (const relPath of idsAssigned) {
+  const lines = read(relPath).split('\n');
+  let inRules = false;
+  let inFence = false;
+  lines.forEach((line, i) => {
+    if (/^```/.test(line.trim())) inFence = !inFence;
+    if (inFence) return;
+    if (/^#{1,6}\s/.test(line)) {
+      inRules = /^#{2,3}\s+(BLOCKER|HIGH|SUGGESTION|Security|Type safety|Error handling|General correctness|Scope discipline)\b/i.test(line);
+      return;
+    }
+    if (!inRules || !/^-\s+/.test(line)) return;
+    if (!/^-\s+`[a-z0-9][a-z0-9-]*\/[a-z0-9][a-z0-9-]*`\s+—\s/.test(line)) {
+      fail(`${relPath}:${i + 1} is a rule with no id — run: node scripts/assign-rule-ids.mjs`);
+    }
+  });
+}
+
+// --- rulesets ----------------------------------------------------------------
+const REQUIRED_CHECK = 'redline-gate / gate';
+for (const file of ['rulesets/redline-ruleset.json', 'rulesets/redline-org-ruleset.json']) {
+  const ruleset = JSON.parse(read(file));
+  const checks = ruleset.rules
+    .filter((r) => r.type === 'required_status_checks')
+    .flatMap((r) => r.parameters.required_status_checks.map((c) => c.context));
+  if (!checks.includes(REQUIRED_CHECK)) {
+    fail(`${file}: required status check is ${JSON.stringify(checks)}, expected "${REQUIRED_CHECK}"`);
+  }
+  const pr = ruleset.rules.find((r) => r.type === 'pull_request');
+  if (!pr) fail(`${file}: no pull_request rule — human approval is not enforced`);
+  else if ((pr.parameters.required_approving_review_count ?? 0) < 1) {
+    fail(`${file}: required_approving_review_count must be at least 1 — automated review never approves`);
+  }
+  if (ruleset.bypass_actors?.length) warn(`${file}: has ${ruleset.bypass_actors.length} bypass actor(s)`);
+}
+
+// --- workflows ---------------------------------------------------------------
+const callerTemplate = read('templates/redline.yml');
+if (!/^\s{2}redline-gate:\s*$/m.test(callerTemplate)) {
+  fail('templates/redline.yml: the caller job id must be `redline-gate` — the required check name derives from it');
+}
+
+const gate = read('workflows/redline-gate.yml');
+if (!/^\s{2}gate:\s*$/m.test(gate)) {
+  fail('workflows/redline-gate.yml: the aggregate job id must be `gate` — the required check name derives from it');
+}
+if (!gate.includes('pull-requests: write')) {
+  fail('workflows/redline-gate.yml: dependency-review needs pull-requests: write to comment');
+}
+
+// --- the derived register -----------------------------------------------------
+// The register is the estate's only source of truth for which repositories are
+// onboarded. It was lost once already — scripts/setup-repo.sh was its only writer
+// and sync-targets.txt went with it — and nothing failed, which is why the dashboard
+// quietly stopped reporting coverage. These two assertions are what makes that
+// silent again impossible.
+if (!existsSync(join(ROOT, 'scripts/build-registry.mjs'))) {
+  fail('scripts/build-registry.mjs is missing — the register cannot be derived, so redline sync has no targets and the dashboard loses its coverage figure');
+}
+
+// --- the estate command surface -------------------------------------------------
+// Every runner the metrics commands dispatch to must ship, because the commands
+// locate them inside the installed package rather than in a checkout. A runner
+// missing from package.json "files" is an installation where `redline metrics
+// dashboard` exists, is documented, and cannot run — the exact broken promise the
+// command surface was built to remove.
+const optionsSource = read('cli/metrics/options.ts');
+for (const match of optionsSource.matchAll(/script: '([^']+)'/g)) {
+  if (!existsSync(join(ROOT, match[1]))) {
+    fail(`cli/metrics/options.ts points at ${match[1]}, which does not exist`);
+  }
+}
+const shippedPaths = JSON.parse(read('package.json')).files ?? [];
+if (!shippedPaths.includes('scripts/')) {
+  fail('package.json "files" no longer ships scripts/ — every redline metrics command would be present, documented, and unable to run');
+}
+if (!existsSync(join(ROOT, '.github/workflows/registry.yml'))) {
+  fail('.github/workflows/registry.yml is missing — the register would silently stop refreshing and go stale without a single failing build');
+}
+
+// --- distribution -------------------------------------------------------------
+// Sync is what makes a standards change reach the estate. Without it every rule
+// change here is a change nobody receives, and the failure is silent by nature:
+// the repositories that did not get it look exactly like the ones that did.
+const syncWorkflow = read('workflows/redline-sync.yml');
+if (/^\s*if:\s*false\s*$/m.test(syncWorkflow)) {
+  fail('workflows/redline-sync.yml is gated off — a standards change would reach no onboarded repository');
+}
+if (!syncWorkflow.includes('redline.js sync')) {
+  fail('workflows/redline-sync.yml no longer calls `redline sync` — distribution is wired to nothing');
+}
+
+// Drift re-detection is the other half of distribution: sync makes a change
+// available, this is what notices a repository that never took it, or that had
+// its gate quietly weakened afterwards.
+const verifyWorkflow = read('workflows/verify-onboarding.yml');
+if (/^\s*if:\s*false\s*$/m.test(verifyWorkflow)) {
+  fail('workflows/verify-onboarding.yml is gated off — estate drift would go undetected');
+}
+if (!verifyWorkflow.includes('verify --repo')) {
+  fail('workflows/verify-onboarding.yml no longer calls `redline verify --repo` — drift detection is wired to nothing');
+}
+
+// The baseline is what every roadmap phase past 0 is judged against, and the
+// roadmap says plainly that the ordering of the later phases is a hypothesis
+// until it exists. Losing the instrument loses the ability to tell whether any
+// of them worked.
+if (!existsSync(join(ROOT, 'scripts/build-baseline.mjs'))) {
+  fail('scripts/build-baseline.mjs is missing — there is no way to compute the baseline every later roadmap phase is measured against');
+}
+if (!existsSync(join(ROOT, 'scripts/build-roi.mjs'))) {
+  fail('scripts/build-roi.mjs is missing — the one page that says what AI review cost against what it caught');
+}
+
+// --- exemptions ---------------------------------------------------------------
+// The exemption block is parsed twice, deliberately: the CLI enforces it at the
+// gate, and the collector reads it for telemetry in the metrics repo where there
+// is no build step to import dist/ from. The failure this guards is the gate
+// accepting a block the audit cannot read — an exemption enforced and then never
+// reported, which is precisely the state F exists to end.
+const exemptCli = read('cli/exempt/parse.ts');
+const exemptCollector = read('scripts/lib/exemptions.mjs');
+for (const token of ['## Redline exemption', 'reason', 'until', 'scope']) {
+  if (!exemptCli.includes(token) || !exemptCollector.includes(token)) {
+    fail(`the exemption block's "${token}" is missing from cli/exempt/parse.ts or scripts/lib/exemptions.mjs — the gate and the audit would read different blocks`);
+  }
+}
+if (!read('.github/pull_request_template.md').includes('Redline exemption')) {
+  fail('.github/pull_request_template.md does not mention the exemption block — an author asked to justify a waiver has nowhere to write it');
+}
+
+// --- ingestion ----------------------------------------------------------------
+// Same two-implementation arrangement as the exemption block, and the same guard.
+// The property being protected is different and larger: an ingested finding must
+// always be distinguishable from a Redline one. A collector that stopped tagging
+// the source would tune Redline's rules on another tool's noise, silently, and
+// nothing else in the system would notice.
+const sarifCli = read('cli/sarif/types.ts');
+const sarifCollector = read('scripts/lib/sarif.mjs');
+for (const token of ["'sarif'", 'severity']) {
+  if (!sarifCli.includes(token) || !sarifCollector.includes(token)) {
+    fail(`ingestion lost "${token}" from cli/sarif/ or scripts/lib/sarif.mjs — an ingested finding must always be distinguishable from a Redline one`);
+  }
+}
+if (!read('scripts/lib/metrics.mjs').includes('scanner')) {
+  fail('scripts/lib/metrics.mjs no longer aggregates ingested findings separately — they would be folded into Redline\'s own rule tuning');
+}
+if (read('workflows/redline-gate.yml').includes('code-scanning')) {
+  fail('workflows/redline-gate.yml reads code scanning — ingested findings are measured only and must never gate a merge (roadmap open question 4)');
+}
+
+// --- the deterministic tier ----------------------------------------------------
+// A rule classified as machine-checked and then checked by nobody is worse than
+// one left to the model: everybody believes it is covered, and the model was told
+// nothing, so it is enforced by no one at all.
+const deterministic = manifest.deterministic ?? [];
+const checksSource = read('cli/policy/checks.ts');
+for (const id of deterministic) {
+  if (!rules.has(id)) {
+    fail(`manifest "deterministic" lists "${id}", which is not a rule in standards/ — ids are permanent and this one does not exist`);
+  }
+  if (!checksSource.includes(`'${id}'`)) {
+    fail(`rule "${id}" is classified deterministic but cli/policy/checks.ts implements no check for it — it is enforced by nobody`);
+  }
+}
+
+// --- local review ---------------------------------------------------------------
+// A local review is opt-in and enforces nothing; the pull request review is the
+// system of record. Its findings must never reach the telemetry that tunes rules,
+// or acted-on rate is computed partly from runs nobody can verify — a local run
+// has no thread to resolve, no reviewer to attribute, and no way to tell a fixed
+// finding from one the author never read.
+if (!read('cli/commands/review.ts').includes('excludedFromTelemetry')) {
+  fail('cli/commands/review.ts no longer marks local reviews as excluded from telemetry — local findings would distort acted-on rate');
+}
+
+// --- pull request template ----------------------------------------------------
+// Two copies of one file, deliberately, kept identical by this check.
+//
+// templates/github/pull_request_template.md is the shipped source: package.json
+// "files" packages templates/, and `redline init` installs it into an onboarded
+// repository. It cannot live under .github/, because .github/ is excluded from the
+// tarball on purpose — packaging it would push this repo's own CI workflows into
+// every consumer.
+//
+// .github/pull_request_template.md is this repository's own copy. Redline is
+// onboarded to Redline, and the `checklist` job in workflows/redline-gate.yml reads
+// the pull request *body*, which GitHub pre-fills from that path. Without it every
+// pull request opened here starts empty and fails this repo's own gate.
+//
+// Neither file carries an explanatory comment of its own: the shipped one is copied
+// verbatim into every consumer's PR body, so a note about Redline's packaging would
+// end up in other teams' pull requests. The explanation lives here, where the drift
+// it guards against is caught.
+const GATED_SECTION = '## Launch readiness';
+const shippedTemplate = read('templates/github/pull_request_template.md');
+const ownTemplate = existsSync(join(ROOT, '.github/pull_request_template.md'))
+  ? read('.github/pull_request_template.md')
+  : null;
+
+if (ownTemplate === null) {
+  fail('.github/pull_request_template.md is missing — every pull request here would start with an empty body and fail the checklist job in workflows/redline-gate.yml');
+} else if (ownTemplate !== shippedTemplate) {
+  fail('.github/pull_request_template.md has drifted from templates/github/pull_request_template.md — the shipped template is the source, copy it across');
+}
+if (!shippedTemplate.includes(GATED_SECTION)) {
+  fail(`templates/github/pull_request_template.md: no "${GATED_SECTION}" section — workflows/redline-gate.yml fails the checklist job without it`);
+}
+
+const workflowFiles = [
+  ...readdirSync(join(ROOT, 'workflows')).map((f) => `workflows/${f}`),
+  ...(existsSync(join(ROOT, '.github/workflows'))
+    ? readdirSync(join(ROOT, '.github/workflows')).map((f) => `.github/workflows/${f}`)
+    : []),
+  'templates/redline.yml',
+].filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'));
+
+for (const file of workflowFiles) {
+  const body = read(file);
+  for (const [, action] of body.matchAll(/^\s*-?\s*uses:\s*([^\s#]+)\s*(?:#.*)?$/gm)) {
+    if (action.startsWith('<org>/') || action.startsWith('./')) continue;
+    if (/@(main|master|latest)$/.test(action)) {
+      // The org's own reusable workflow is a first-party ref and is allowed to float.
+      if (action.includes('/.github/.github/workflows/')) continue;
+      fail(`${file}: third-party action pinned to a mutable ref: ${action}`);
+    }
+    const [owner] = action.split('/');
+    if (owner !== 'actions' && !/@[0-9a-f]{40}$/.test(action)) {
+      warn(`${file}: ${action} is not pinned to a commit SHA`);
+    }
+  }
+  // Expressions are not allowed in a step-level `uses:`; the workflow silently fails to parse.
+  for (const [, action] of body.matchAll(/^\s+uses:\s*(\$\{\{[^\n]*)/gm)) {
+    if (!/^\s*jobs:/m.test(action)) fail(`${file}: expression in a step \`uses:\` is not supported by Actions: ${action.trim()}`);
+  }
+}
+
+// --- seeds --------------------------------------------------------------------
+// Recall without precision is meaningless, so both corpora are load-bearing and both
+// are enforced here rather than left to a reviewer to notice.
+const SEED_MARKER = /SEED\s+(\d+)\s*\[(BLOCKER|HIGH|SUGGESTION)\]\s*(?:\(([^)]+)\))?/;
+const MIN_BLOCKERS_PER_STACK = 4;
+const seedDir = join(ROOT, 'seeded');
+const seedDirs = readdirSync(seedDir, { withFileTypes: true })
+  .filter((e) => e.isDirectory())
+  .map((e) => e.name);
+
+const seedFiles = (dir) =>
+  readdirSync(join(seedDir, dir)).filter((f) => !f.endsWith('.md'));
+
+for (const id of Object.keys(manifest.stacks)) {
+  if (!seedDirs.includes(id)) {
+    fail(`seeded/${id}/ is missing — that stack's catch rate cannot be measured`);
+    continue;
+  }
+  const files = seedFiles(id);
+  if (!files.length) {
+    fail(`seeded/${id}/ has no seed file`);
+    continue;
+  }
+  let blockers = 0;
+  let ids = new Set();
+  for (const file of files) {
+    for (const line of readFileSync(join(seedDir, id, file), 'utf8').split('\n')) {
+      const m = SEED_MARKER.exec(line);
+      if (!m) continue;
+      const key = `${file}#${m[1]}`;
+      if (ids.has(key)) fail(`seeded/${id}/${file}: duplicate SEED ${m[1]}`);
+      ids.add(key);
+      if (m[2] === 'BLOCKER') blockers += 1;
+
+      // A seed without a rule id cannot verify attribution; one citing an unknown or
+      // weaker rule silently makes the corpus disagree with the standard it tests.
+      const cited = m[3];
+      if (!cited) {
+        fail(`seeded/${id}/${file}: SEED ${m[1]} does not cite a rule id`);
+      } else if (!rules.has(cited) && !RESERVED_RULE_IDS.has(cited)) {
+        fail(`seeded/${id}/${file}: SEED ${m[1]} cites unknown rule "${cited}"`);
+      } else if (rules.has(cited) && RANK[m[2]] > RANK[rules.get(cited).severity]) {
+        fail(
+          `seeded/${id}/${file}: SEED ${m[1]} expects ${m[2]} but rule "${cited}" is ${rules.get(cited).severity} in the standard`
+        );
+      }
+    }
+  }
+  if (blockers < MIN_BLOCKERS_PER_STACK) {
+    fail(`seeded/${id}/ has ${blockers} BLOCKER seed(s), minimum is ${MIN_BLOCKERS_PER_STACK}`);
+  }
+}
+
+if (!seedDirs.includes('clean')) {
+  fail('seeded/clean is missing — recall is measured but precision is not');
+} else {
+  const clean = seedFiles('clean');
+  if (!clean.length) fail('seeded/clean is empty — precision is unmeasured');
+  for (const file of clean) {
+    if (SEED_MARKER.test(readFileSync(join(seedDir, 'clean', file), 'utf8'))) {
+      fail(`seeded/clean/${file} contains a SEED marker — the precision corpus must be defect-free`);
+    }
+  }
+}
+
+// --- report -------------------------------------------------------------------
+warnings.forEach((w) => console.warn(`warn: ${w}`));
+errors.forEach((e) => console.error(`FAIL: ${e}`));
+console.log(`\n${errors.length} error(s), ${warnings.length} warning(s)`);
+process.exit(errors.length ? 1 : 0);

package/standards/core.md

@@ -0,0 +1,124 @@
+# Redline — Core Engineering Standards
+
+You are performing code review against Redline, the engineering standard for this
+organisation. Stack-specific rules extend these; they never override them.
+
+## Output contract (required)
+
+Every finding you post MUST begin with a machine-readable prefix on its own first line:
+
+```
+Redline/BLOCKER [rule-id]: <one-line problem>
+Redline/HIGH [rule-id]: <one-line problem>
+Redline/SUGGESTION [rule-id]: <one-line problem>
+```
+
+Then one or two sentences: why it breaks, and the concrete fix. No preamble, no praise,
+no restating the diff. One finding per comment. If nothing qualifies, post nothing.
+
+Worked example:
+
+```
+Redline/BLOCKER [core/query-string-concatenation]: user-supplied `name` is concatenated
+into the SQL string, so a crafted value changes the query.
+Use a parameterised query: `db.Query("SELECT id FROM users WHERE name = $1", name)`.
+```
+
+### Rule ids
+
+Every rule in this document and in the stack rules carries an id in backticks at the
+start of its line, of the form `<stack>/<slug>` — for example `react/effect-derived-state`.
+
+- Quote the id of the rule you are applying, exactly as written. Do not invent, abbreviate,
+  pluralise, or reformat it.
+- One rule per comment. If a line breaks two rules, post two comments.
+- If you are confident something is wrong but no rule covers it, use `core/uncatalogued`
+  and say plainly which principle it offends. A recurring `core/uncatalogued` is how a
+  missing rule gets discovered, so do not force a bad match to avoid it.
+
+Ids are stable across wording changes and are aggregated per rule, which is how the org
+finds out which rules earn their place and which only generate noise. A finding without a
+valid id cannot be measured and is treated as untagged.
+
+Severity meaning:
+
+- **BLOCKER** — must not merge. Security exposure, data loss, crash, silent corruption,
+  or a contract break for live consumers.
+- **HIGH** — merge is a deliberate trade-off. Reviewer must acknowledge explicitly.
+- **SUGGESTION** — optional. Author may dismiss without justification.
+
+Do not invent severities. Do not upgrade a SUGGESTION to HIGH to get attention.
+
+## Review priorities (in order)
+
+1. Security and data exposure
+2. Correctness bugs
+3. Type safety
+4. Performance regressions
+5. Maintainability
+
+Stop at the first three unless the diff is clean there.
+
+## Security (BLOCKER)
+
+- `core/hardcoded-secrets` — No hardcoded secrets, API keys, tokens, or credentials — including in test files,
+  fixtures, config samples, and comments.
+- `core/customer-data-in-logs` — No customer data (MSISDN, email, account IDs, names, addresses) in logs, analytics
+  events, error messages, or metric labels.
+- `core/unvalidated-boundary-input` — All external input validated at system boundaries (forms, API responses, deep links,
+  query params, webhook payloads, message-queue payloads).
+- `core/html-injection-sink` — No unsanitised HTML injection sinks (`dangerouslySetInnerHTML`, `innerHTML`, template
+  autoescape disabled).
+- `core/missing-auth-check` — Auth checks on every server action / API route / service endpoint — not only in the UI
+  layer or at the gateway.
+- `core/sensitive-data-in-client-storage` — No sensitive data in browser or device storage (`localStorage`, `AsyncStorage`,
+  `UserDefaults`, `SharedPreferences`) without platform-keystore encryption.
+- `core/query-string-concatenation` — No query built by string concatenation with external input — parameterised only.
+- `core/secrets-in-committed-config` — No secrets read from committed config — environment or vault only.
+
+## Type safety (BLOCKER unless justified inline)
+
+- `core/escape-hatch-types` — No escape-hatch types (`any`, `interface{}` in new Go code, `Object`, `dynamic`)
+  where a concrete or generic type works.
+- `core/type-checker-suppression` — No type-checker suppression (`@ts-ignore`, `@ts-expect-error`, `# type: ignore`,
+  `@SuppressWarnings("unchecked")`) without an inline comment AND a ticket reference.
+- `core/unsafe-assertion` — No unsafe assertions (`as unknown as X`, force casts) used to silence an error.
+- `core/prefer-discriminated-unions` — Discriminated unions / sealed types over optional-field grab-bags for variant state.
+- `core/unchecked-indexed-access` — Assume the strictest project setting is on (TS `strict` + `noUncheckedIndexedAccess`,
+  Kotlin/Swift null-safety, mypy strict): indexed access may be absent — require the check.
+
+## Error handling
+
+- `core/missing-boundary-error-handling` — Error handling belongs at real system boundaries: user input, network calls, storage,
+  native modules, message consumers. Flag missing handling there.
+- `core/unreachable-defensive-guard` — Flag defensive guards against states internal code cannot produce — they hide bugs and
+  add noise.
+- `core/silent-async-failure` — Async operations that can reject must not fail silently: no empty catch, no floating
+  promises, no error logged then treated as success.
+
+## General correctness
+
+- `core/argument-mutation` — Flag mutation of function arguments or shared objects.
+- `core/async-race-condition` — Flag race conditions in async work: missing cancellation/abort when the owner unmounts,
+  the request is superseded, or the context is cancelled.
+- `core/untracked-todo` — Flag `TODO`/`FIXME`/placeholder code without a ticket reference.
+- `core/naive-clock` — Flag time handling that assumes local timezone or a naive clock in new code.
+
+## Scope discipline
+
+- `core/unrelated-change` — Flag changes unrelated to the PR's stated purpose (drive-by refactors, formatting churn).
+- `core/speculative-abstraction` — Prefer the minimal diff that solves the problem; flag speculative abstraction
+  ("might need it later").
+
+## What NOT to flag
+
+AI review dies by nitpick spam. Noise control is a rule, not a preference.
+
+- Formatting, import order, or anything a linter or formatter already enforces.
+- Existing patterns the PR merely touches but does not change.
+- Missing tests for code outside the diff.
+- Alternative libraries when the current one works ("consider using X instead").
+- Naming preferences where the existing name is unambiguous.
+- Re-raising the same issue on every occurrence — flag the first, say "and N similar".
+- Anything you cannot point at a concrete failure for. If you cannot describe the input
+  that breaks it, it is not a finding.