Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
Record never-runs exclusions and report gate expiry, not fail (#6266)
Nick Gomezc4d446848793
diff --git a/packages/desktop/playwright.capture.config.ts b/packages/desktop/playwright.capture.config.tsnew file mode 100644index 000000000..b4bcb8389--- /dev/null+++ b/packages/desktop/playwright.capture.config.ts@@ -0,0 +1,10 @@+import { defineConfig } from '@playwright/test';+import smoke from './playwright.config.ts';++export default defineConfig({+ ...smoke,+ testDir: './tests/smoke',+ testMatch: /.*\.capture\.ts$/,+ retries: 0,+ reporter: [['list']],+});diff --git a/packages/desktop/playwright.config.ts b/packages/desktop/playwright.config.tsindex ab16aec2c..e73420734 100644--- a/packages/desktop/playwright.config.ts+++ b/packages/desktop/playwright.config.ts@@ -24,12 +24,6 @@ import { ONE_LAUNCH_AND_ITS_READINESS_VERDICT_MS } from './tests/smoke/_helpers/export default defineConfig({testDir: './tests/smoke',testMatch: /.*\.e2e\.ts$/,- // Underscore-prefixed `_*.e2e.ts` are dev-only screenshot/utility scripts- // (opt-in via OK_DESKTOP_E2E_SMOKE=1). They produce no assertions and exist- // to capture rendered Electron output for visual comparison during design- // iteration. Excluding them at the matcher level codifies the convention:- // CI never runs them even if the smoke env var leaks in.- testIgnore: ['**/_*.e2e.ts'],timeout: process.env.CI ? 150_000 : ONE_LAUNCH_AND_ITS_READINESS_VERDICT_MS,// Retries for CI macOS runner flake. Tests that hang or time out from// runner-load contention (Electron Helper XPC delays, slow loadFilediff --git a/packages/desktop/tests/smoke/_helpers/platform-gate.ts b/packages/desktop/tests/smoke/_helpers/platform-gate.tsindex 4afafd82f..046807382 100644--- a/packages/desktop/tests/smoke/_helpers/platform-gate.ts+++ b/packages/desktop/tests/smoke/_helpers/platform-gate.ts@@ -23,8 +23,6 @@ export function userDataDirFor(tmpHome: string): string {}export const SPEC_PLATFORM_GATES = {- '_nav-empty-840x600.e2e.ts': ['!PLATFORM_SUPPORTED'],- '_nav-size-screenshots.e2e.ts': ['!PLATFORM_SUPPORTED'],'agent-patch-divergence-probe.e2e.ts': ['!PLATFORM_SUPPORTED'],'background-throttle.e2e.ts': ['!PLATFORM_SUPPORTED'],'cold-single-file-launch.e2e.ts': ['!DARWIN'],diff --git a/packages/desktop/tests/smoke/_nav-empty-840x600.e2e.ts b/packages/desktop/tests/smoke/_nav-empty-840x600.capture.tssimilarity index 100%rename from packages/desktop/tests/smoke/_nav-empty-840x600.e2e.tsrename to packages/desktop/tests/smoke/_nav-empty-840x600.capture.tsdiff --git a/packages/desktop/tests/smoke/_nav-size-screenshots.e2e.ts b/packages/desktop/tests/smoke/_nav-size-screenshots.capture.tssimilarity index 100%rename from packages/desktop/tests/smoke/_nav-size-screenshots.e2e.tsrename to packages/desktop/tests/smoke/_nav-size-screenshots.capture.tsdiff --git a/scripts/check-known-reds.uncached.test.mjs b/scripts/check-known-reds.uncached.test.mjsindex 934871ff1..a282a56d1 100644--- a/scripts/check-known-reds.uncached.test.mjs+++ b/scripts/check-known-reds.uncached.test.mjs@@ -6,11 +6,14 @@ import { fileURLToPath } from 'node:url';import { afterAll, describe, expect, test } from 'vitest';import { configureTestGitRepository } from '../test-support/configure-git-fixture.test-helper.ts';import { okVitestBase } from '../test-support/vitest.base.ts';+import { ISSUE_URL_RULE } from './deviations/contract.mjs';import { gitCleanEnv } from './git-clean-env.mjs';import {+ ALLOWANCE_FIELDS,ALLOWLIST_PATH,CONVENTION_DOC,EXPIRY_WARNING_DAYS,+ expired,expiringSoon,KNOWN_BUG_TAG,listTestFiles,@@ -1024,15 +1027,20 @@ describe('known-reds validation', () => {{ owner: 'someone-else' },`known-bug pin has owner "someone-else", which is not one of ${OWNERS.join(', ')}`,],- [{ issue: undefined }, 'known-bug pin has no issue link'],+ [{ issue: undefined }, 'known-bug pin has no issue'],[{ issue: 'inkeep/agents-private#1056' },- 'known-bug pin has issue "inkeep/agents-private#1056", which is not a GitHub or Linear issue URL',+ `known-bug pin has issue "inkeep/agents-private#1056", which is not ${ISSUE_URL_RULE}`,+ ],+ [{ until: undefined }, 'known-bug pin has no until'],+ [+ { until: '15/10/2026' },+ 'known-bug pin has until "15/10/2026", which is not a YYYY-MM-DD date',+ ],+ [+ { until: '2026-02-30' },+ 'known-bug pin has until "2026-02-30", which is not a YYYY-MM-DD date',],- [{ until: undefined }, 'known-bug pin has no until date'],- [{ until: '15/10/2026' }, 'known-bug pin has until "15/10/2026", which is not YYYY-MM-DD'],- [{ until: '2026-02-30' }, 'known-bug pin has until "2026-02-30", which is not a date'],- [{ until: '2026-09-30' }, 'known-bug pin expired on 2026-09-30'],[{ until: '2026-12-31' },`known-bug pin has until 2026-12-31, beyond the ${MAX_HORIZON_DAYS}-day horizon (2026-12-30)`,@@ -1041,6 +1049,62 @@ describe('known-reds validation', () => {expect(messages(pinReport(fields))).toEqual([message]);});+ test('reports a pin past its until date instead of refusing it', () => {+ const report = pinReport({ until: '2026-09-30' });+ expect(messages(report)).toEqual([]);+ expect(expired(report, { today: TODAY, allowlist: NO_ALLOWLIST })).toEqual([+ {+ kind: 'pin',+ path: 'a.test.ts',+ line: 1,+ owner: 'get-main-green',+ issue: ISSUE,+ until: '2026-09-30',+ },+ ]);+ expect(expired(pinReport({}), { today: TODAY, allowlist: NO_ALLOWLIST })).toEqual([]);+ });++ test('a pin dated its own day is neither expired nor refused', () => {+ const report = pinReport({ until: TODAY });+ expect(messages(report)).toEqual([]);+ expect(expired(report, { today: TODAY, allowlist: NO_ALLOWLIST })).toEqual([]);+ });++ test('an expired pin with a malformed issue is still refused for the issue', () => {+ expect(messages(pinReport({ until: '2026-09-30', issue: 'PRD-1' }))).toEqual([+ `known-bug pin has issue "PRD-1", which is not ${ISSUE_URL_RULE}`,+ ]);+ });++ test('reports an expired quarantine and an expired allowlist entry the same way', () => {+ const report = {+ ...pinReport({}),+ quarantines: [+ { path: 'q.test.ts', line: 4, issue: ISSUE, owner: 'get-main-green', until: '2026-09-01' },+ ],+ };+ const allowlist = {+ ciSkips: [+ {+ path: 'd.test.ts',+ condition: 'CI',+ issue: ISSUE,+ owner: 'known-reds',+ until: '2026-09-02',+ reason: 'r',+ exit: 'e',+ },+ ],+ };+ expect(+ expired(report, { today: TODAY, allowlist }).map((row) => `${row.kind} ${row.until}`),+ ).toEqual(['quarantine 2026-09-01', 'ci-skip-entry 2026-09-02']);+ expect(+ validate(report, { today: TODAY, allowlist }).map((violation) => violation.rule),+ ).toEqual(['allowlist-stale']);+ });+test(`lists what expires within ${EXPIRY_WARNING_DAYS} days, without failing it`, () => {const report = {...pinReport({}),@@ -1054,13 +1118,28 @@ describe('known-reds validation', () => {ciSkips: [{ path: 'd.test.ts', condition: 'CI', owner: 'known-reds', until: '2026-10-02' }],};expect(expiringSoon(report, { today: TODAY, allowlist })).toEqual([- { kind: 'pin', path: 'a.test.ts', line: 1, owner: 'get-main-green', until: '2026-10-08' },- { kind: 'pin', path: 'b.test.ts', line: 2, owner: 'get-main-green', until: '2026-10-15' },+ {+ kind: 'pin',+ path: 'a.test.ts',+ line: 1,+ owner: 'get-main-green',+ issue: null,+ until: '2026-10-08',+ },+ {+ kind: 'pin',+ path: 'b.test.ts',+ line: 2,+ owner: 'get-main-green',+ issue: null,+ until: '2026-10-15',+ },{kind: 'ci-skip-entry',path: 'd.test.ts',line: null,owner: 'known-reds',+ issue: null,until: '2026-10-02',},]);@@ -1164,7 +1243,7 @@ describe('known-reds validation', () => {{ path: 'a.test.ts', line: 1, title: 't', issue: ISSUE, owner: 'get-main-green' },],};- expect(messages(report)).toEqual(['quarantine has no until date']);+ expect(messages(report)).toEqual(['quarantine has no until']);});test('refuses an environment early return', () => {@@ -1191,9 +1270,11 @@ describe('known-reds validation', () => {const entry = {path: skip.path,condition: skip.condition,+ issue: ISSUE,owner: 'known-reds',until: '2026-11-01',reason: 'skips the whole file on CI',+ exit: 'run the file on CI, then delete this entry',};const report = { ...pinReport({}), pins: [], ciSkips: [skip] };const ruleNames = (allowlist) =>@@ -1203,10 +1284,20 @@ describe('known-reds validation', () => {expect(ruleNames(NO_ALLOWLIST)).toEqual(['ci-skip']);});- test('accepts a listed, owned, dated CI skip', () => {+ test('accepts a listed CI skip that carries all five fields', () => {+ expect(ALLOWANCE_FIELDS).toEqual(['issue', 'owner', 'until', 'reason', 'exit']);expect(ruleNames({ ciSkips: [entry] })).toEqual([]);});+ test.each(ALLOWANCE_FIELDS)('refuses an entry without %s, by exactly that field', (field) => {+ const { [field]: _dropped, ...missing } = entry;+ expect(+ validate(report, { today: TODAY, allowlist: { ciSkips: [missing] } }).map(+ (violation) => violation.message,+ ),+ ).toEqual([`entry ${entry.path} has no ${field}`]);+ });+test('permits exactly one site per entry', () => {const twice = { ...report, ciSkips: [skip, { ...skip, line: 40 }] };expect(@@ -1222,17 +1313,24 @@ describe('known-reds validation', () => {).toEqual(['ci-skip', 'allowlist-stale']);});- test('refuses a stale, expired, unowned or unexplained entry', () => {+ test('refuses a stale, unowned or unexplained entry, a whitespace-only reason included', () => {expect(validate({ ...report, ciSkips: [] }, { today: TODAY, allowlist: { ciSkips: [entry] } }).map((violation) => violation.rule,),).toEqual(['allowlist-stale']);- expect(ruleNames({ ciSkips: [{ ...entry, until: '2026-09-01' }] })).toEqual([- 'allowlist-fields',- ]);expect(ruleNames({ ciSkips: [{ ...entry, owner: 'nobody' }] })).toEqual(['allowlist-fields']);expect(ruleNames({ ciSkips: [{ ...entry, reason: '' }] })).toEqual(['allowlist-fields']);+ expect(ruleNames({ ciSkips: [{ ...entry, reason: ' \t ' }] })).toEqual(['allowlist-fields']);+ expect(ruleNames({ ciSkips: [{ ...entry, exit: ' ' }] })).toEqual(['allowlist-fields']);+ });++ test('reports an expired entry and still consumes its site', () => {+ const lapsed = { ...entry, until: '2026-09-01' };+ expect(ruleNames({ ciSkips: [lapsed] })).toEqual([]);+ expect(+ expired(report, { today: TODAY, allowlist: { ciSkips: [lapsed] } }).map((row) => row.kind),+ ).toEqual(['ci-skip-entry']);});});});@@ -1325,7 +1423,8 @@ describe('known-reds through its real invocation', () => {});expect(run.status).toBe(1);const feed = JSON.parse(run.stdout);- expect(feed.schemaVersion).toBe(3);+ expect(feed.schemaVersion).toBe(4);+ expect(feed.expired).toEqual([]);expect(feed.files).toBe(4);expect(feed.violations.map((violation) => violation.rule)).toEqual(expect.arrayContaining(['pin-retries', 'ci-skip', 'early-return']),@@ -1353,6 +1452,7 @@ describe('known-reds through its real invocation', () => {path: 'packages/server/src/expiring.test.ts',line: 4,owner: 'get-main-green',+ issue: ISSUE,until: soon,},]),@@ -1404,6 +1504,75 @@ describe('known-reds through its real invocation', () => {});});+describe('an expired date through the real invocation', () => {+ const yesterday = new Date(Date.parse(`${todayUtc()}T00:00:00Z`) - 86_400_000)+ .toISOString()+ .slice(0, 10);+ const treeWith = (until) => {+ const root = mkdtempSync(join(tmpdir(), 'ok-known-reds-expiry-'));+ const file = join(root, 'packages/server/src/lapsed.test.ts');+ mkdirSync(dirname(file), { recursive: true });+ writeFileSync(+ file,+ vitestPin({ meta: `{ issue: '${ISSUE}', owner: 'get-main-green', until: '${until}' }` }),+ );+ const init = spawnSync('git', ['init', '-q'], {+ cwd: root,+ env: gitCleanEnv(),+ windowsHide: true,+ encoding: 'utf8',+ });+ if (init.status === 0) configureTestGitRepository(root);+ return { root, init };+ };+ const roots = [];+ afterAll(() => {+ for (const root of roots) rmSync(root, { recursive: true, force: true });+ });+ const run = (until, args) => {+ const { root, init } = treeWith(until);+ roots.push(root);+ expect(init.status).toBe(0);+ return spawnSync(process.execPath, [SCRIPT, ...args, '--root', root], {+ encoding: 'utf8',+ env: gitCleanEnv(),+ windowsHide: true,+ });+ };++ test('a pin past its until exits 0, and the feed and the listing report it', () => {+ const json = run(yesterday, ['--json']);+ expect(json.status, json.stderr).toBe(0);+ const feed = JSON.parse(json.stdout);+ expect(feed.files).toBe(1);+ expect(feed.pins.map((pin) => pin.until)).toEqual([yesterday]);+ expect(feed.violations).toEqual([]);+ expect(feed.expired).toEqual([+ {+ kind: 'pin',+ path: 'packages/server/src/lapsed.test.ts',+ line: 4,+ owner: 'get-main-green',+ issue: ISSUE,+ until: yesterday,+ },+ ]);+ const listing = run(yesterday, []);+ expect(listing.status, listing.stderr).toBe(0);+ expect(listing.stdout).toContain(+ `Expired, reported and not failed (1)\n pin packages/server/src/lapsed.test.ts:4 owner get-main-green, until ${yesterday}, issue ${ISSUE}`,+ );+ });++ test('the same pin with a date that is not a real day exits 1', () => {+ const json = run('2026-02-30', ['--json']);+ expect(json.status).toBe(1);+ expect(JSON.parse(json.stdout).violations.map((violation) => violation.message)).toEqual([+ 'known-bug pin has until "2026-02-30", which is not a YYYY-MM-DD date',+ ]);+ });+});+describe('known-reds on this tree', () => {const files = listTestFiles(OK_ROOT);let scanned;@@ -1466,6 +1635,7 @@ describe('known-reds on this tree', () => {`no more than ${MAX_HORIZON_DAYS} days away`,`at least ${MIN_SIGNATURE_LITERAL} literal characters in a row`,`Expiring within ${EXPIRY_WARNING_DAYS} days`,+ 'Expired, reported and not failed',`(\`schemaVersion\` ${SCHEMA_VERSION})`,]) {expect(doc, `${CONVENTION_DOC} must mention ${cited}`).toContain(cited);diff --git a/scripts/deviations/contract.mjs b/scripts/deviations/contract.mjsnew file mode 100644index 000000000..31c6de213--- /dev/null+++ b/scripts/deviations/contract.mjs@@ -0,0 +1,77 @@+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;+const DAY_MS = 86_400_000;++const ISSUE_URL =+ /^https:\/\/(?:github\.com\/inkeep\/[\w.-]+\/issues\/\d+|linear\.app\/inkeep\/issue\/[A-Z]+-\d+(?:\/[\w-]*)?)$/;+export const ISSUE_URL_RULE =+ 'a GitHub issue URL in the inkeep organization or a Linear issue URL in the inkeep workspace';+export const HORIZON_DAYS = 90;++export function todayUtc(now = new Date()) {+ return now.toISOString().slice(0, 10);+}++export function isRealDate(value) {+ if (typeof value !== 'string' || !ISO_DATE.test(value)) return false;+ const time = Date.parse(`${value}T00:00:00Z`);+ return !Number.isNaN(time) && new Date(time).toISOString().slice(0, 10) === value;+}++function asOfDay(asOf) {+ if (!isRealDate(asOf)) {+ throw new TypeError(`the as-of day must be a YYYY-MM-DD UTC date, not ${JSON.stringify(asOf)}`);+ }+ return asOf;+}++export function addDays(day, days) {+ return new Date(Date.parse(`${asOfDay(day)}T00:00:00Z`) + days * DAY_MS)+ .toISOString()+ .slice(0, 10);+}++export function isNonBlank(value) {+ return typeof value === 'string' && value.trim() !== '';+}++export function isRecord(value) {+ return value !== null && typeof value === 'object' && !Array.isArray(value);+}++export function trackingProblems(entry, { required, optional = [], owners }) {+ if (!isRecord(entry)) return ['is not an object'];+ const problems = required+ .filter((field) => !isNonBlank(entry[field]))+ .map((field) => `has no ${field}`);+ for (const field of optional) {+ if (entry[field] !== undefined && !isNonBlank(entry[field])) {+ problems.push(`has a blank ${field}`);+ }+ }+ if (isNonBlank(entry.issue) && !ISSUE_URL.test(entry.issue)) {+ problems.push(`has issue ${JSON.stringify(entry.issue)}, which is not ${ISSUE_URL_RULE}`);+ }+ if (isNonBlank(entry.owner) && !owners.includes(entry.owner)) {+ problems.push(+ `has owner ${JSON.stringify(entry.owner)}, which is not one of ${owners.join(', ')}`,+ );+ }+ if (isNonBlank(entry.until) && !isRealDate(entry.until)) {+ problems.push(`has until ${JSON.stringify(entry.until)}, which is not a YYYY-MM-DD date`);+ }+ return problems;+}++export function horizonProblem(until, asOf) {+ const horizon = addDays(asOf, HORIZON_DAYS);+ if (!isRealDate(until) || until <= horizon) return null;+ return `has until ${until}, beyond the ${HORIZON_DAYS}-day horizon (${horizon})`;+}++export function reviewState(until, asOf, { soonDays = 0 } = {}) {+ asOfDay(asOf);+ if (!isRealDate(until)) return 'undated';+ if (until < asOf) return 'expired';+ if (soonDays > 0 && until <= addDays(asOf, soonDays)) return 'due-soon';+ return 'current';+}diff --git a/scripts/deviations/contract.test.mjs b/scripts/deviations/contract.test.mjsnew file mode 100644index 000000000..76ad5d539--- /dev/null+++ b/scripts/deviations/contract.test.mjs@@ -0,0 +1,169 @@+import { describe, expect, test } from 'vitest';+import {+ addDays,+ HORIZON_DAYS,+ horizonProblem,+ ISSUE_URL_RULE,+ isNonBlank,+ isRealDate,+ isRecord,+ reviewState,+ todayUtc,+ trackingProblems,+} from './contract.mjs';++const AS_OF = '2026-10-12';+const OWNERS = ['team-a', 'team-b'];+const complete = (overrides = {}) => ({+ issue: 'https://github.com/inkeep/agents-private/issues/1',+ owner: 'team-a',+ until: '2026-11-01',+ reason: 'a known gap',+ ...overrides,+});+const fields = (entry, options = {}) =>+ trackingProblems(entry, { required: ['issue', 'owner', 'until', 'reason'], owners: OWNERS, ...options });++describe('trackingProblems: timeless field checks, the same for every domain', () => {+ test('a complete record has no problem', () => {+ expect(fields(complete())).toEqual([]);+ });++ test.each(['issue', 'owner', 'until', 'reason'])(+ 'a missing, empty or whitespace-only %s is refused by exactly that field',+ (field) => {+ const { [field]: _dropped, ...missing } = complete();+ expect(fields(missing)).toEqual([`has no ${field}`]);+ expect(fields(complete({ [field]: '' }))).toEqual([`has no ${field}`]);+ expect(fields(complete({ [field]: ' \t' }))).toEqual([`has no ${field}`]);+ expect(fields(complete({ [field]: 7 }))).toEqual([`has no ${field}`]);+ },+ );++ test('an issue is a GitHub issue in the inkeep organization or a Linear issue in the inkeep workspace', () => {+ for (const issue of [+ 'https://github.com/inkeep/agents-private/issues/42',+ 'https://linear.app/inkeep/issue/PRD-1234',+ 'https://linear.app/inkeep/issue/PRD-1234/a-title-slug',+ ]) {+ expect(fields(complete({ issue })), issue).toEqual([]);+ }+ for (const issue of [+ 'https://github.com/inkeep/agents-private/pull/42',+ 'https://github.com/someone-else/agents-private/issues/42',+ 'https://linear.app/other/issue/PRD-1234',+ 'PRD-1234',+ ]) {+ expect(fields(complete({ issue })), issue).toEqual([+ `has issue ${JSON.stringify(issue)}, which is not ${ISSUE_URL_RULE}`,+ ]);+ }+ });++ test("an owner comes from the domain's own catalog", () => {+ expect(fields(complete({ owner: 'team-b' }))).toEqual([]);+ expect(fields(complete({ owner: 'team-c' }))).toEqual([+ 'has owner "team-c", which is not one of team-a, team-b',+ ]);+ });++ test('until is a real calendar date, checked without any as-of day', () => {+ expect(fields(complete({ until: '2024-02-29' }))).toEqual([]);+ for (const until of ['2026-02-30', '2026-13-01', '15/10/2026', 'soon']) {+ expect(fields(complete({ until })), until).toEqual([+ `has until ${JSON.stringify(until)}, which is not a YYYY-MM-DD date`,+ ]);+ }+ });++ test('an optional field may be absent, and is refused when present but blank', () => {+ const optional = (entry) =>+ trackingProblems(entry, { required: ['owner', 'reason'], optional: ['issue'], owners: OWNERS });+ const { issue: _issue, ...noIssue } = complete();+ expect(optional(noIssue)).toEqual([]);+ expect(optional(complete({ issue: ' ' }))).toEqual(['has a blank issue']);+ expect(optional(complete({ issue: 'PRD-1' }))).toEqual([+ `has issue "PRD-1", which is not ${ISSUE_URL_RULE}`,+ ]);+ });++ test('something that is not an object is refused as a whole', () => {+ for (const entry of [null, 'text', ['a'], 7]) {+ expect(fields(entry), JSON.stringify(entry)).toEqual(['is not an object']);+ }+ });+});++describe('horizonProblem: the admission rule, relative to one injected UTC day', () => {+ test(`day ${HORIZON_DAYS} is inside the horizon and day ${HORIZON_DAYS + 1} is not`, () => {+ const horizon = addDays(AS_OF, HORIZON_DAYS);+ expect(horizon).toBe('2027-01-10');+ expect(horizonProblem(horizon, AS_OF)).toBeNull();+ expect(horizonProblem(addDays(horizon, 1), AS_OF)).toBe(+ `has until 2027-01-11, beyond the ${HORIZON_DAYS}-day horizon (2027-01-10)`,+ );+ });++ test('the same date admitted on the next day: the horizon only relaxes as time passes', () => {+ expect(horizonProblem('2027-01-11', AS_OF)).not.toBeNull();+ expect(horizonProblem('2027-01-11', addDays(AS_OF, 1))).toBeNull();+ });++ test('a past date is no horizon problem, and a malformed date is left to the field check', () => {+ expect(horizonProblem('2026-01-01', AS_OF)).toBeNull();+ expect(horizonProblem('soon', AS_OF)).toBeNull();+ });++ test('an as-of day that is not a real date is refused rather than guessed', () => {+ expect(() => horizonProblem('2026-11-01', '2026-02-30')).toThrow(/as-of day/);+ expect(() => horizonProblem('2026-11-01', undefined)).toThrow(/as-of day/);+ });+});++describe('reviewState: expiry is a reported fact, never a field problem', () => {+ test('a record is current through its until day and expired from the day after', () => {+ expect(reviewState(AS_OF, AS_OF)).toBe('current');+ expect(reviewState(addDays(AS_OF, -1), AS_OF)).toBe('expired');+ expect(reviewState(addDays(AS_OF, 1), AS_OF)).toBe('current');+ });++ test('due-soon covers the as-of day through the window it is given, inclusive', () => {+ expect(reviewState(AS_OF, AS_OF, { soonDays: 14 })).toBe('due-soon');+ expect(reviewState(addDays(AS_OF, 14), AS_OF, { soonDays: 14 })).toBe('due-soon');+ expect(reviewState(addDays(AS_OF, 15), AS_OF, { soonDays: 14 })).toBe('current');+ });++ test('an expired record has no field problem', () => {+ expect(fields(complete({ until: addDays(AS_OF, -30) }))).toEqual([]);+ expect(reviewState(addDays(AS_OF, -30), AS_OF)).toBe('expired');+ });++ test('a record without a real date is undated', () => {+ expect(reviewState(undefined, AS_OF)).toBe('undated');+ expect(reviewState('2026-02-30', AS_OF)).toBe('undated');+ });+});++describe('the predicates the domain parsers share', () => {+ test('isNonBlank holds only for a string with a non-whitespace character', () => {+ expect(['x', ' x '].map(isNonBlank)).toEqual([true, true]);+ expect(['', ' \t\n', undefined, null, 7, ['x']].map(isNonBlank)).toEqual([false, false, false, false, false, false]);+ });++ test('isRecord holds for a plain object and not for null, an array or a scalar', () => {+ expect([{}, { a: 1 }].map(isRecord)).toEqual([true, true]);+ expect([null, [], 'x', 7, undefined].map(isRecord)).toEqual([false, false, false, false, false]);+ });+});++describe('dates', () => {+ test('todayUtc reads the UTC day of the instant it is given', () => {+ expect(todayUtc(new Date('2026-10-12T23:59:59Z'))).toBe('2026-10-12');+ expect(todayUtc(new Date('2026-10-13T00:00:00Z'))).toBe('2026-10-13');+ });++ test('isRealDate accepts a leap day and refuses an impossible one', () => {+ expect(isRealDate('2028-02-29')).toBe(true);+ expect(isRealDate('2027-02-29')).toBe(false);+ });+});diff --git a/scripts/known-reds.mjs b/scripts/known-reds.mjsindex 4bb530dcb..cdd024bc1 100644--- a/scripts/known-reds.mjs+++ b/scripts/known-reds.mjs@@ -3,19 +3,28 @@ import { existsSync, readFileSync } from 'node:fs';import { createRequire } from 'node:module';import { join, resolve } from 'node:path';import { fileURLToPath } from 'node:url';+import {+ HORIZON_DAYS,+ horizonProblem,+ reviewState,+ todayUtc,+ trackingProblems,+} from './deviations/contract.mjs';import { gitCleanEnv } from './git-clean-env.mjs';+export { todayUtc };+const ts = createRequire(import.meta.url)('typescript');export const OK_ROOT = fileURLToPath(new URL('..', import.meta.url));export const ALLOWLIST_PATH = fileURLToPath(new URL('./known-reds-allowlist.json', import.meta.url),);-export const SCHEMA_VERSION = 3;+export const SCHEMA_VERSION = 4;export const KNOWN_BUG_TAG = 'known-bug';export const QUARANTINE_TAG = 'quarantine';export const OWNERS = Object.freeze(['get-main-green', 'known-reds']);-export const MAX_HORIZON_DAYS = 90;+export const MAX_HORIZON_DAYS = HORIZON_DAYS;export const EXCLUDED_PREFIXES = Object.freeze(['reports/', 'specs/']);export const CONVENTION_DOC = 'test-support/KNOWN-REDS.md';export const MIN_SIGNATURE_LITERAL = 4;@@ -23,10 +32,6 @@ export const EXPIRY_WARNING_DAYS = 14;const TEST_FILE = /\.test\.[cm]?[jt]sx?$|\.e2e\.tsx?$|\.test-helper\.[cm]?[jt]sx?$/;const PLAYWRIGHT_FILE = /\.e2e\.tsx?$/;-const ISSUE_URL =- /^https:\/\/(?:github\.com\/inkeep\/[\w.-]+\/issues\/\d+|linear\.app\/inkeep\/issue\/[A-Z]+-\d+(?:\/[\w-]*)?)$/;-const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;-const DAY_MS = 86_400_000;const RUNNER_KINDS = new Map([['test', 'test'],['it', 'test'],@@ -58,6 +63,7 @@ const CI_IDENTIFIERS = new Set(['CI', 'IS_CI', 'isCI', 'isCi', 'ON_CI', 'onCI',const CI_INFO_MODULE = 'ci-info';const CI_INFO_FLAG = 'isCI';const FIELDS = ['issue', 'owner', 'until'];+export const ALLOWANCE_FIELDS = Object.freeze(['issue', 'owner', 'until', 'reason', 'exit']);function scriptKind(path) {if (path.endsWith('.tsx')) return ts.ScriptKind.TSX;@@ -1552,37 +1558,10 @@ export function scanTree(root) {return report;}-export function todayUtc(now = new Date()) {- return now.toISOString().slice(0, 10);-}--function addDays(day, days) {- return new Date(Date.parse(`${day}T00:00:00Z`) + days * DAY_MS).toISOString().slice(0, 10);-}--function dateProblem(until, today) {- if (!until) return 'has no until date';- if (!ISO_DATE.test(until)) return `has until "${until}", which is not YYYY-MM-DD`;- const time = Date.parse(`${until}T00:00:00Z`);- if (Number.isNaN(time) || new Date(time).toISOString().slice(0, 10) !== until)- return `has until "${until}", which is not a date`;- if (until < today) return `expired on ${until}`;- const horizon = addDays(today, MAX_HORIZON_DAYS);- if (until > horizon)- return `has until ${until}, beyond the ${MAX_HORIZON_DAYS}-day horizon (${horizon})`;- return null;-}--function trackedProblems(entry, today, { needsIssue }) {- const problems = [];- if (needsIssue && !entry.issue) problems.push('has no issue link');- if (entry.issue && !ISSUE_URL.test(entry.issue))- problems.push(`has issue "${entry.issue}", which is not a GitHub or Linear issue URL`);- if (!entry.owner) problems.push('has no owner');- else if (!OWNERS.includes(entry.owner))- problems.push(`has owner "${entry.owner}", which is not one of ${OWNERS.join(', ')}`);- const date = dateProblem(entry.until, today);- if (date) problems.push(date);+function trackedProblems(entry, today, required) {+ const problems = trackingProblems(entry, { required, owners: OWNERS });+ const beyond = horizonProblem(entry.until, today);+ if (beyond) problems.push(beyond);return problems;}@@ -1597,7 +1576,7 @@ export function loadAllowlist(path = ALLOWLIST_PATH) {export function validate(report, { today, allowlist }) {const violations = [...report.problems];for (const pin of report.pins) {- for (const message of trackedProblems(pin, today, { needsIssue: true })) {+ for (const message of trackedProblems(pin, today, FIELDS)) {violations.push({path: pin.path,line: pin.line,@@ -1607,7 +1586,7 @@ export function validate(report, { today, allowlist }) {}}for (const quarantine of report.quarantines) {- for (const message of trackedProblems(quarantine, today, { needsIssue: true })) {+ for (const message of trackedProblems(quarantine, today, FIELDS)) {violations.push({path: quarantine.path,line: quarantine.line,@@ -1651,13 +1630,7 @@ export function validate(report, { today, allowlist }) {message: `entry ${entry.path} (${entry.condition}) matches no CI-keyed skip; remove it`,});}- if (!entry.reason)- violations.push({- ...where,- rule: 'allowlist-fields',- message: `entry ${entry.path} has no reason`,- });- for (const message of trackedProblems(entry, today, { needsIssue: false })) {+ for (const message of trackedProblems(entry, today, ALLOWANCE_FIELDS)) {violations.push({...where,rule: 'allowlist-fields',@@ -1668,34 +1641,41 @@ export function validate(report, { today, allowlist }) {return violations;}-export function expiringSoon(report, { today, allowlist }) {- const limit = addDays(today, EXPIRY_WARNING_DAYS);- const due = (entry) =>- typeof entry.until === 'string' &&- ISO_DATE.test(entry.until) &&- entry.until >= today &&- entry.until <= limit;+function trackedRows(report, allowlist, keep) {const row = (kind) => (entry) => ({kind,path: entry.path,line: entry.line ?? null,owner: entry.owner ?? null,+ issue: entry.issue ?? null,until: entry.until,});return [- ...report.pins.filter(due).map(row('pin')),- ...report.quarantines.filter(due).map(row('quarantine')),- ...allowlist.ciSkips.filter(due).map(row('ci-skip-entry')),+ ...report.pins.filter(keep).map(row('pin')),+ ...report.quarantines.filter(keep).map(row('quarantine')),+ ...allowlist.ciSkips.filter(keep).map(row('ci-skip-entry')),];}+export function expiringSoon(report, { today, allowlist }) {+ return trackedRows(+ report,+ allowlist,+ (entry) => reviewState(entry.until, today, { soonDays: EXPIRY_WARNING_DAYS }) === 'due-soon',+ );+}++export function expired(report, { today, allowlist }) {+ return trackedRows(report, allowlist, (entry) => reviewState(entry.until, today) === 'expired');+}+const EXPIRING_KIND_LABELS = {pin: 'pin',quarantine: 'quarantine','ci-skip-entry': 'allowlisted CI skip',};-export function render(report, violations, upcoming, today, { all }) {+export function render(report, violations, upcoming, today, { all, lapsed = [] }) {const lines = [`Known reds in open-knowledge on ${today}: ${report.files} test files scanned.`,'',@@ -1753,6 +1733,12 @@ export function render(report, violations, upcoming, today, { all }) {(row) =>`${EXPIRING_KIND_LABELS[row.kind] ?? row.kind} ${row.path}${row.line === null ? '' : `:${row.line}`} owner ${row.owner ?? '?'}, until ${row.until}`,);+ section(+ 'Expired, reported and not failed',+ lapsed,+ (row) =>+ `${EXPIRING_KIND_LABELS[row.kind] ?? row.kind} ${row.path}${row.line === null ? '' : `:${row.line}`} owner ${row.owner ?? '?'}, until ${row.until}, issue ${row.issue ?? 'none'}`,+ );section('Violations',violations,@@ -1775,13 +1761,14 @@ function main(argv) {const allowlist = loadAllowlist();const violations = validate(report, { today, allowlist });const upcoming = expiringSoon(report, { today, allowlist });+ const lapsed = expired(report, { today, allowlist });if (argv.includes('--json')) {process.stdout.write(- `${JSON.stringify({ ...report, today, expiringSoon: upcoming, violations }, null, 2)}\n`,+ `${JSON.stringify({ ...report, today, expiringSoon: upcoming, expired: lapsed, violations }, null, 2)}\n`,);} else {process.stdout.write(- render(report, violations, upcoming, today, { all: argv.includes('--all') }),+ render(report, violations, upcoming, today, { all: argv.includes('--all'), lapsed }),);}process.exitCode = violations.length > 0 ? 1 : 0;diff --git a/test-support/KNOWN-REDS.md b/test-support/KNOWN-REDS.mdindex 2756effe4..fc4c6ffb0 100644--- a/test-support/KNOWN-REDS.md+++ b/test-support/KNOWN-REDS.md@@ -45,7 +45,7 @@ test(- `owner` is one of the owners listed in `scripts/known-reds.mjs`.- `until` is a date no more than 90 days away.-When the date passes, the guard fails. Either fix the bug, or move the date and record why on the issue. The listing shows every pin, quarantine and allowlist entry under "Expiring within 14 days" before that happens.+A date that has passed does not fail the guard: `pnpm known-reds` lists the entry under "Expired, reported and not failed" and in the feed's `expired`, and the owner either fixes the bug, or moves the date and records why on the issue. A missing or malformed field, or a date more than 90 days away on the day the guard runs, still fails. The listing shows every pin, quarantine and allowlist entry under "Expiring within 14 days" before its date passes.<br>_[Recorded 2026-10-12 post-ship: before 2026-10-12 this passage read "When the date passes, the guard fails", so a pin or quarantine past its `until` turned the guard red on that date alone; the owner's decisions Q52 and 8A made a passed date reported and not failed.]_**Never use** `test.fails`, `{ fails: true }` or Playwright's `test.fail()`. Each accepts any failure, including one that has nothing to do with the bug.@@ -75,7 +75,7 @@ Never `return` early from a test body on an environment condition, such as the pA test in the uncached tier (`*.uncached.test.*`) may not skip at all. That tier fails any run in which a test did not execute, and prints the rule for such tests (`test-support/uncached-tier-floor.ts`).-A skip keyed on CI (`process.env.CI`, `IS_CI` and the like) hides the test from the run that gates merges. It fails the guard unless `scripts/known-reds-allowlist.json` lists it with an owner, a date and a reason. Prefer to key the skip on the missing capability instead.+A skip keyed on CI (`process.env.CI`, `IS_CI` and the like) hides the test from the run that gates merges. It fails the guard unless `scripts/known-reds-allowlist.json` lists it with an `issue`, an `owner`, an `until` date, a `reason` and an `exit` (what removes it), each non-blank, the same five fields as any other temporary gate exception. An entry past its date is reported, not failed. Prefer to key the skip on the missing capability instead.<br>_[Recorded 2026-10-12 post-ship: before 2026-10-12 an allowlist entry needed only an owner, a date and a reason, with an optional `issue`, and one past its date failed the guard; the owner's decisions Q52 and 8A made a passed date reported and not failed, and 8A made `issue` required and added `exit`.]_The guard follows a condition through names declared in the same file: a renamed or destructured `process.env`, a destructured `CI`, a constant key, a helper that takes no arguments and whose body is a single return expression, and `isCI` from `ci-info`. Anything else, such as a helper imported from another file, a longer helper body, a rest element or a nested destructuring, is labelled `unknown` and listed under "Gates with a condition the scanner cannot read", where a reviewer has to check it.@@ -87,6 +87,9 @@ Use `test.todo('title')`.- `pnpm known-reds` prints the pins, the quarantines and the CI-keyed skips.- `--all` adds every test that does not run, every environment gate, and each gate whose condition the scanner cannot read. Without it, those groups show only their counts.-- `--json` prints the full feed (`schemaVersion` 3). Beyond the listing, it carries:+- `--json` prints the full feed (`schemaVersion` 4).<br>_[Recorded 2026-10-12 post-ship: before 2026-10-12 the feed was `schemaVersion` 3, carried no `expired` list and reported a passed date as a `violation`; the owner's decisions Q52 and 8A made a passed date reported and not failed, which version 4's `expired` carries.]_++ Beyond the listing, it carries:+ - `expired` and `expiringSoon`: each pin, quarantine and allowlist entry past its `until`, or due within 14 days, with its owner and issue. An expired date is never a `violation`.- `atoms` on each CI skip and environment gate: the facts its condition reads, following each name to the declaration visible where the gate sits. Each is `{ kind, name, text }`, and `kind` is `platform`, `arch`, `uid`, `env`, `ci`, `fs`, `import`, `runtime` or `unknown`. `runtime` is a resolved read of `process.versions` or `process.release`, which keeps its full name, or of an `os` function with no narrower kind. `unknown` is anything the scanner cannot resolve, such as a helper imported from another file; the receiver and arguments of an unresolved call are still read, so `isTerminalPlatform(process.platform)` yields `unknown` and `platform`, and `process.env.DIR?.trim()` yields `unknown` and `env`.- `titles` on every pin and quarantine, and on each other entry scoped to a test or describe: the enclosing describe titles, ending with the entry's own declaration title, so a describe-scoped gate ends with its describe's title. A title that is not a string literal appears as `{ nonLiteral: <source> }`.