An open source design system that's fully customizable and agent ready
TypeScript
ci: one list of record paths for check:knowledge, change classification and the spec-owner gate (#9469)
Cindy Zhang326614a7be99
diff --git a/.github/scripts/change-scope.cjs b/.github/scripts/change-scope.cjsindex 26440243d6..e3f302320c 100644--- a/.github/scripts/change-scope.cjs+++ b/.github/scripts/change-scope.cjs@@ -6,8 +6,7 @@// eslint-disable-next-line @typescript-eslint/no-require-importsconst {isComponentSpecRecordPath,- isLegacyComponentSpecPath,- isPackageArchitectureRecordPath,+ isOwnerGatedPath,isPlatformComponentSpecPath,} = require('./knowledge-paths.cjs');@@ -105,18 +104,6 @@ function isSharedInfraPath(filePath) {);}-const THEME_DOC_CANDIDATE = /^docs\/themes\/(?!README\.md$)[^/]+\.md$/;-const THEME_PACKAGE_CANDIDATE =- /^packages\/themes\/[^/]+\/(?:.*\/)?[^/]+\.spec\.md$/;--const KNOWLEDGE_RECORD_PATTERNS = [- ...SPEC_RECORD_PATTERNS,- THEME_DOC_CANDIDATE,- THEME_PACKAGE_CANDIDATE,- /^docs\/architecture\/(?!README\.md$)[^/]+\.md$/,- /^docs\/design\/assets\//,-];-function isSpecRecordPath(filePath) {return (isComponentSpecRecordPath(filePath) ||@@ -143,15 +130,13 @@ function isPackageReleasePath(filePath) {return true;}+/**+ * A path the spec-owner gate decides (knowledge-paths.cjs's owner-gated+ * paths): every record, every Markdown file in a record location, and the+ * normative design assets.+ */function isKnowledgeRecordPath(filePath) {- return (- isSpecRecordPath(filePath) ||- // Not a record and never spec-only, but the owner gate must still see it.- isLegacyComponentSpecPath(filePath) ||- // A package's architecture record, owner-gated like docs/architecture/.- isPackageArchitectureRecordPath(filePath) ||- KNOWLEDGE_RECORD_PATTERNS.some(pattern => pattern.test(filePath))- );+ return isOwnerGatedPath(filePath);}function isNodeToolingPath(filePath) {@@ -307,25 +292,55 @@ function parseNameStatus(input) {});}+/**+ * Each path's record classes, for a caller outside this workflow: whether it+ * counts toward a spec-only change (`specRecord`) and whether its change needs+ * a spec owner's approval (`ownerGatedRecord`). Reads the paths alone.+ *+ * @param {string[]} paths+ * @returns {Record<string, {specRecord: boolean, ownerGatedRecord: boolean}>}+ */+function classifyPaths(paths) {+ return Object.fromEntries(+ paths.map(filePath => [+ filePath,+ {+ specRecord: isSpecRecordPath(filePath),+ ownerGatedRecord: isOwnerGatedPath(filePath),+ },+ ]),+ );+}+if (require.main === module) {// eslint-disable-next-line @typescript-eslint/no-require-importsconst fs = require('node:fs');- const result = classifyChanges(parseNameStatus(fs.readFileSync(0, 'utf8')));- if (result.specChangesetConflict) {- console.error(- 'Pure spec-record changes must not add a Changeset; they do not release packages.',- );- process.exitCode = 1;- } else if (process.argv.includes('--github-output')) {- const outputPath = process.env.GITHUB_OUTPUT;- if (!outputPath)- throw new Error('GITHUB_OUTPUT is required with --github-output.');- fs.appendFileSync(- outputPath,- `spec_only=${result.specOnly}\ndocsite_only=${result.docsiteOnly}\ntooling_only=${result.toolingOnly}\nlab_only=${result.labOnly}\nfull_suite=${result.fullSuite}\n`,- );+ // `--classify-paths`: newline-separated paths on stdin, JSON on stdout.+ if (process.argv.includes('--classify-paths')) {+ const paths = fs+ .readFileSync(0, 'utf8')+ .split(/\r?\n/)+ .map(line => line.trim())+ .filter(Boolean);+ process.stdout.write(`${JSON.stringify(classifyPaths(paths))}\n`);} else {- process.stdout.write(`${JSON.stringify(result)}\n`);+ const result = classifyChanges(parseNameStatus(fs.readFileSync(0, 'utf8')));+ if (result.specChangesetConflict) {+ console.error(+ 'Pure spec-record changes must not add a Changeset; they do not release packages.',+ );+ process.exitCode = 1;+ } else if (process.argv.includes('--github-output')) {+ const outputPath = process.env.GITHUB_OUTPUT;+ if (!outputPath)+ throw new Error('GITHUB_OUTPUT is required with --github-output.');+ fs.appendFileSync(+ outputPath,+ `spec_only=${result.specOnly}\ndocsite_only=${result.docsiteOnly}\ntooling_only=${result.toolingOnly}\nlab_only=${result.labOnly}\nfull_suite=${result.fullSuite}\n`,+ );+ } else {+ process.stdout.write(`${JSON.stringify(result)}\n`);+ }}}@@ -334,6 +349,7 @@ module.exports = {NODE_TOOLING_PATHS,SURFACES,classifyChanges,+ classifyPaths,isKnowledgeRecordPath,isNodeToolingPath,isPackageReleasePath,diff --git a/.github/scripts/change-scope.test.mjs b/.github/scripts/change-scope.test.mjsindex 36e888d2b6..d1cb036530 100644--- a/.github/scripts/change-scope.test.mjs+++ b/.github/scripts/change-scope.test.mjs@@ -71,10 +71,13 @@ describe('spec-only change scope', () => {]);expect(result.touchesKnowledgeRecords).toBe(true);expect(result.specOnly).toBe(false);- expect(- classifyChanges([{filename: 'packages/native/specs/README.md'}])- .touchesKnowledgeRecords,- ).toBe(false);+ // Every Markdown file under a package's specs/ is owner-gated, a README+ // too, though only records count toward a spec-only change.+ const readme = classifyChanges([+ {filename: 'packages/native/specs/README.md'},+ ]);+ expect(readme.touchesKnowledgeRecords).toBe(true);+ expect(readme.specOnly).toBe(false);});it('owner-gates architecture records without granting the spec-only fast path', () => {diff --git a/.github/scripts/knowledge-paths.cjs b/.github/scripts/knowledge-paths.cjsindex 5b37061f85..902904ebed 100644--- a/.github/scripts/knowledge-paths.cjs+++ b/.github/scripts/knowledge-paths.cjs@@ -378,6 +378,86 @@ function componentSpecPathForSource(packageName, relativePath) {return `${COMPONENT_SPEC_ROOT}/${segments.join('/')}`;}+/**+ * A knowledge record `check:knowledge` discovers and validates: a system spec+ * or plan, a family, architecture or design record, a theme record, a+ * package's own architecture record, or a component or module record.+ * `scripts/check-knowledge.mjs` reads records through this predicate, and its+ * test pins it to the tool's discovery.+ */+function isKnowledgeRecordPath(filePath) {+ const normalized = normalizePath(filePath);+ if (/^docs\/(?:architecture|design|families)\/[^/]+\.md$/.test(normalized)) {+ return !normalized.endsWith('/README.md');+ }+ if (/^docs\/specs\/[^/]+\/(?:spec|plan)\.md$/.test(normalized)) {+ return true;+ }+ const themeMatch = /^packages\/themes\/([^/]+)\/([^/]+)\.spec\.md$/.exec(+ normalized,+ );+ if (themeMatch) return themeMatch[1] === themeMatch[2];+ if (classifyPackageArchitectureRecordPath(normalized)) return true;+ return isComponentSpecRecordPath(normalized);+}++/**+ * A file `check:knowledge` validates as a record of its own: a knowledge+ * record or a platform component record. Its front matter states its+ * authority.+ */+function isValidatedRecordPath(filePath) {+ return (+ isKnowledgeRecordPath(filePath) || isPlatformComponentSpecPath(filePath)+ );+}++/**+ * A path whose change needs a spec owner's approval: every validated record;+ * every Markdown file in a record location, whether a record or not (a+ * generated table beside a spec, a draft or README under a package's+ * `specs/`); theme record candidates `check:knowledge` rejects as misplaced;+ * a component spec at a legacy location; and the normative design assets.+ * Ignored locations (isIgnoredKnowledgeLocation) stay ignored.+ */+const OWNER_GATED_PATTERNS = Object.freeze([+ /^docs\/specs\/.+\.md$/,+ /^docs\/(?:architecture|design|families)\/(?!README\.md$)[^/]+\.md$/,+ /^docs\/design\/assets\//,+ /^docs\/themes\/(?!README\.md$)[^/]+\.md$/,+ /^packages\/themes\/[^/]+\/(?:.*\/)?[^/]+\.spec\.md$/,+ /^packages\/[^/]+\/specs\/.+\.md$/,+ /^packages\/[^/]+\/docs\/architecture\/.+\.md$/,+]);++/**+ * A hidden, fixture, test, generated, build-output, coverage or dependency+ * path, or a `*.generated.spec.md`: discovery and pull-request routing ignore+ * it everywhere (`architecture:knowledge-contracts`).+ */+function isIgnoredKnowledgeLocation(filePath) {+ const segments = normalizePath(filePath).split('/');+ const fileName = segments.pop();+ return (+ fileName.startsWith('.') ||+ fileName.endsWith('.generated.spec.md') ||+ segments.some(+ segment =>+ segment.startsWith('.') || isIgnoredComponentKnowledgeSegment(segment),+ )+ );+}++function isOwnerGatedPath(filePath) {+ const normalized = normalizePath(filePath);+ return (+ isValidatedRecordPath(normalized) ||+ isLegacyComponentSpecPath(normalized) ||+ (!isIgnoredKnowledgeLocation(normalized) &&+ OWNER_GATED_PATTERNS.some(pattern => pattern.test(normalized)))+ );+}+module.exports = {COMPONENT_PACKAGE_NAMES,COMPONENT_SPEC_ROOT,@@ -390,9 +470,12 @@ module.exports = {componentSpecPathForSource,isComponentSpecRecordPath,isIgnoredComponentKnowledgeSegment,+ isKnowledgeRecordPath,isLegacyComponentSpecPath,+ isOwnerGatedPath,isPackageArchitectureRecordPath,isPlatformComponentSpecPath,+ isValidatedRecordPath,locateComponentKnowledgePath,locatePlatformComponentSource,resolveComponentPackage,diff --git a/.github/scripts/knowledge-paths.test.mjs b/.github/scripts/knowledge-paths.test.mjsindex a9cc948d34..c0cc32c628 100644--- a/.github/scripts/knowledge-paths.test.mjs+++ b/.github/scripts/knowledge-paths.test.mjs@@ -281,3 +281,150 @@ describe('component record location', () => {).toBeNull();});});++describe('record paths: one list for check:knowledge, change classification and the owner gate', () => {+ const {+ isKnowledgeRecordPath,+ isOwnerGatedPath,+ } = require('./knowledge-paths.cjs');+ const {+ classifyPaths,+ isKnowledgeRecordPath: gatedByScope,+ } = require('./change-scope.cjs');+ const root = path.resolve(import.meta.dirname, '../..');+ const tracked = require('node:child_process')+ .execFileSync('git', ['ls-files', '-z'], {+ cwd: root,+ encoding: 'utf8',+ maxBuffer: 256 * 1024 * 1024,+ })+ .split('\0')+ .filter(Boolean);+ const relative = files =>+ files.map(file => path.relative(root, file).split(path.sep).join('/'));++ it('names exactly the records check:knowledge discovers, and gates every one', async () => {+ const {discoverKnowledgeRecords, discoverPlatformComponentRecords} =+ await import('../../scripts/check-knowledge.mjs');+ const discovered = relative(discoverKnowledgeRecords(root)).sort();+ expect(tracked.filter(file => isKnowledgeRecordPath(file)).sort()).toEqual(+ discovered,+ );+ const platform = relative(discoverPlatformComponentRecords(root)).sort();+ expect(+ tracked.filter(file => isPlatformComponentSpecPath(file)).sort(),+ ).toEqual(platform);+ for (const record of [...discovered, ...platform]) {+ expect(isOwnerGatedPath(record), record).toBe(true);+ }+ });++ it('the spec-owner gate decides exactly the owner-gated paths', () => {+ for (const file of tracked) {+ expect(gatedByScope(file), file).toBe(isOwnerGatedPath(file));+ }+ });++ it.each([+ // A generated record table beside a spec, with the code that writes it.+ [+ 'a generated table beside a spec',+ [+ 'docs/specs/AST-094-touch-presentations/motion-roles.md',+ 'package.json',+ 'packages/core/src/motion/roles.test.ts',+ 'scripts/generate-motion-roles.mjs',+ 'scripts/motion-roles-table.d.mts',+ 'scripts/motion-roles-table.mjs',+ ],+ {+ 'docs/specs/AST-094-touch-presentations/motion-roles.md': {+ specRecord: false,+ ownerGatedRecord: true,+ },+ },+ ],+ // A platform record with its Swift view and tests.+ [+ 'a platform record',+ [+ 'docs/specs/components/Avatar/Avatar.swift.spec.md',+ 'packages/native/apple/Sources/Astryx/Avatar/Avatar.swift',+ 'packages/native/apple/Tests/AstryxTests/AvatarTests.swift',+ ],+ {+ 'docs/specs/components/Avatar/Avatar.swift.spec.md': {+ specRecord: true,+ ownerGatedRecord: true,+ },+ },+ ],+ ])('%s needs a spec owner, and its code does not', (_, files, records) => {+ const classified = classifyPaths(files);+ for (const file of files) {+ expect(classified[file], file).toEqual(+ records[file] ?? {specRecord: false, ownerGatedRecord: false},+ );+ }+ });++ it.each([+ 'docs/specs/AST-030/spec.md',+ 'docs/specs/AST-030/plan.md',+ 'docs/specs/AST-094-touch-presentations/motion-roles.md',+ 'docs/specs/README.md',+ 'docs/specs/components/Button/Button.spec.md',+ 'docs/specs/components/Button/notes.md',+ 'docs/families/action-groups.md',+ 'docs/design/motion.md',+ 'docs/design/assets/selector/alignment.png',+ 'docs/architecture/knowledge-contracts.md',+ 'docs/themes/neutral.md',+ 'packages/themes/neutral/neutral.spec.md',+ 'packages/themes/neutral/subdir/neutral.spec.md',+ 'packages/native/specs/README.md',+ 'packages/native/specs/TEMPLATE.md',+ 'packages/native/specs/swift/library/accessibility.md',+ 'packages/native/specs/swift/library/tooltip.spec.md',+ 'packages/core/docs/architecture/runtime.md',+ 'packages/core/src/Selector/Selector.spec.md',+ ])('gates %s', file => {+ expect(isOwnerGatedPath(file)).toBe(true);+ });++ it.each([+ 'docs/architecture/README.md',+ 'docs/families/README.md',+ 'docs/design/README.md',+ 'docs/themes/README.md',+ 'docs/specs/components/__tests__/TopLevel.spec.md',+ 'docs/specs/components/Selector/__fixtures__/fixture.spec.md',+ 'docs/specs/components/Selector/.hidden/Hidden.spec.md',+ 'docs/specs/components/Selector/generated/fake.spec.md',+ 'docs/specs/components/Selector/plugins/fake.generated.spec.md',+ 'docs/contributing/spec-writing.md',+ 'docs/schemas/knowledge/component.schema.json',+ 'packages/core/src/Button/Button.tsx',+ ])('leaves %s ungated', file => {+ expect(isOwnerGatedPath(file)).toBe(false);+ });++ it('classifies paths from the command line for callers outside the workflow', () => {+ const output = require('node:child_process').execFileSync(+ process.execPath,+ [path.join(root, '.github/scripts/change-scope.cjs'), '--classify-paths'],+ {+ input:+ 'docs/specs/AST-094-touch-presentations/motion-roles.md\npackage.json\n',+ encoding: 'utf8',+ },+ );+ expect(JSON.parse(output)).toEqual({+ 'docs/specs/AST-094-touch-presentations/motion-roles.md': {+ specRecord: false,+ ownerGatedRecord: true,+ },+ 'package.json': {specRecord: false, ownerGatedRecord: false},+ });+ });+});diff --git a/.github/scripts/spec-owner-decision.cjs b/.github/scripts/spec-owner-decision.cjsindex dac446a798..2334f136a9 100644--- a/.github/scripts/spec-owner-decision.cjs+++ b/.github/scripts/spec-owner-decision.cjs@@ -242,6 +242,89 @@ function approvalGroupFor(content, filePath) {return 'spec';}+/**+ * The `authority` the file's leading fields state, or null: the front-matter+ * block when there is one, else the `key: value` lines it opens with. A+ * README may show a front-matter example in its body; that never counts.+ */+function leadingAuthority(content) {+ if (content == null) return null;+ const block = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(content);+ let lines;+ if (block) {+ lines = block[1].split(/\r?\n/);+ } else {+ const all = content.split(/\r?\n/);+ const end = all.findIndex(line => !/^[a-z_]+:\s/.test(line));+ lines = end === -1 ? all : all.slice(0, end);+ }+ for (const line of lines) {+ const match = /^authority:\s*['"]?([a-z-]+)['"]?\s*$/.exec(line);+ if (match) return match[1];+ }+ return null;+}++/**+ * The owner groups one changed record or owner-gated file needs: a set of+ * `spec`, `design` and `theme`, empty when none (a draft record, a design+ * asset whose group comes from the change's own flag).+ */+function recordApprovalGroups(record) {+ const groups = new Set();+ const versions = [+ {content: record.baseContent, path: record.previousPath ?? record.path},+ {content: record.headContent, path: record.path},+ ];+ // An owner-gated Markdown file with no authority of its own (a generated+ // table beside a spec, a README or draft note in a record location) has+ // nothing for the gate to read, so an engineering owner decides it.+ if (+ versions.some(+ version =>+ typeof version.path === 'string' &&+ version.path.endsWith('.md') &&+ !version.path.startsWith('docs/design/assets/'),+ ) &&+ versions.every(version => leadingAuthority(version.content) == null) &&+ versions.some(version => version.content != null)+ ) {+ groups.add('spec');+ return groups;+ }+ const currentVersions = versions.filter(+ version => parseAuthority(version.content, version.path) === 'current',+ );+ if (currentVersions.length === 0) return groups;++ const touchesComponentOrModule = versions.some(version => {+ const kind = parseKind(version.content, version.path);+ return kind === 'component' || kind === 'module';+ });+ if (touchesComponentOrModule) {+ const change = classifyDesignDecisionChange({+ basePath: record.previousPath ?? record.path,+ headPath: record.path,+ baseContent: record.baseContent,+ headContent: record.headContent,+ });+ if (change.classification === 'dd-only') {+ groups.add('design');+ } else if (change.classification === 'mixed') {+ groups.add('spec');+ groups.add('design');+ } else {+ groups.add('spec');+ }+ return groups;+ }++ for (const version of currentVersions) {+ groups.add(approvalGroupFor(version.content, version.path));+ }+ return groups;+}+function requiredApprovalGroups(records,{complete = true, touchesDesignAssets = false} = {},@@ -249,40 +332,7 @@ function requiredApprovalGroups(if (!complete) return {spec: true, design: true, theme: true};const groups = {spec: false, design: touchesDesignAssets, theme: false};for (const record of records) {- const versions = [- {content: record.baseContent, path: record.previousPath ?? record.path},- {content: record.headContent, path: record.path},- ];- const currentVersions = versions.filter(- version => parseAuthority(version.content, version.path) === 'current',- );- if (currentVersions.length === 0) continue;-- const touchesComponentOrModule = versions.some(version => {- const kind = parseKind(version.content, version.path);- return kind === 'component' || kind === 'module';- });- if (touchesComponentOrModule) {- const change = classifyDesignDecisionChange({- basePath: record.previousPath ?? record.path,- headPath: record.path,- baseContent: record.baseContent,- headContent: record.headContent,- });- if (change.classification === 'dd-only') {- groups.design = true;- } else if (change.classification === 'mixed') {- groups.spec = true;- groups.design = true;- } else {- groups.spec = true;- }- continue;- }-- for (const version of currentVersions) {- groups[approvalGroupFor(version.content, version.path)] = true;- }+ for (const group of recordApprovalGroups(record)) groups[group] = true;}return groups;}@@ -400,6 +450,8 @@ module.exports = {parseOwnerCommandIntent,parseOwnerCommandTarget,parseOwnerFile,+ leadingAuthority,+ recordApprovalGroups,requiredApprovalGroups,requiresOwnerApproval,resolveOwnerDecision,diff --git a/.github/scripts/spec-owner-decision.test.mjs b/.github/scripts/spec-owner-decision.test.mjsindex 410fe2805a..d8b9ae1cab 100644--- a/.github/scripts/spec-owner-decision.test.mjs+++ b/.github/scripts/spec-owner-decision.test.mjs@@ -87,6 +87,79 @@ describe('spec owner decision', () => {expect(requiresOwnerApproval([], {complete: false})).toBe(true);});+ it('requires an engineering owner for an owner-gated file with no authority of its own', () => {+ const {+ requiredApprovalGroups: groupsFor,+ } = require('./spec-owner-decision.cjs');+ // A generated table beside a spec: no front matter, so an engineering+ // owner decides it.+ expect(+ groupsFor([+ {+ path: 'docs/specs/AST-094-touch-presentations/motion-roles.md',+ previousPath:+ 'docs/specs/AST-094-touch-presentations/motion-roles.md',+ baseContent: '# Motion roles\n',+ headContent: '# Motion roles\n\n| role |\n',+ },+ ]),+ ).toEqual({spec: true, design: false, theme: false});+ // A README whose body shows a front-matter example still has no+ // authority of its own, even with two example lines.+ const example = [+ '# Native specs',+ '',+ '```md',+ '---',+ 'authority: draft',+ '---',+ '```',+ '',+ '```md',+ '---',+ 'authority: current',+ '---',+ '```',+ '',+ ].join('\n');+ expect(+ groupsFor([+ {+ path: 'packages/native/specs/README.md',+ previousPath: 'packages/native/specs/README.md',+ baseContent: example,+ headContent: `${example}More.\n`,+ },+ ]),+ ).toEqual({spec: true, design: false, theme: false});+ // Added, too.+ expect(+ groupsFor([+ {+ path: 'packages/native/specs/swift/library/notes.md',+ baseContent: null,+ headContent: '# Notes\n',+ },+ ]).spec,+ ).toBe(true);+ // A draft record still needs no approval, and a design asset goes to the+ // design group through its own flag.+ expect(+ groupsFor([+ {+ path: 'docs/specs/AST-999/spec.md',+ baseContent: null,+ headContent: 'authority: draft\n',+ },+ {+ path: 'docs/design/assets/x.png',+ baseContent: null,+ headContent: null,+ },+ ]),+ ).toEqual({spec: false, design: false, theme: false});+ });+it('requires an engineering owner when a platform record becomes current', () => {const swiftRecord = authority =>[diff --git a/.github/scripts/spec-owner-reconcile.cjs b/.github/scripts/spec-owner-reconcile.cjsindex bf2fcf7edf..787f75a52a 100644--- a/.github/scripts/spec-owner-reconcile.cjs+++ b/.github/scripts/spec-owner-reconcile.cjs@@ -17,8 +17,8 @@ const {describeOwnerCommandProblem,newestGateRun,parseOwnerCommandIntent,- parseAuthority,- parseKind,+ leadingAuthority,+ recordApprovalGroups,parseOwnerFile,requiredApprovalGroups,resolveOwnerDecision,@@ -455,31 +455,23 @@ async function reconcileWithinBudget({commandProblem,}) {if (typeof core.summary?.addRaw !== 'function') return;+ // The same per-record rule the decision uses, so the two never disagree.const groupFor = record => {- const current =- parseAuthority(record.headContent, record.path) === 'current' ||- parseAuthority(record.baseContent, record.previousPath) === 'current';- if (!current) return 'none (draft)';- const kind = parseKind(- record.headContent ?? record.baseContent,- record.path,- );- return kind === 'design' || kind === 'theme'- ? 'design or eng owner'- : 'eng owner';+ const groups = recordApprovalGroups(record);+ if (groups.size === 0) return 'none (draft)';+ return groups.has('spec') ? 'eng owner' : 'design or eng owner';};+ const authorityOf = content => leadingAuthority(content) ?? 'no authority';const rows = changedRecords.map(record => {const text = record.headContent ?? record.baseContent ?? '';const id = text.match(/^id:\s*(.+)$/m)?.[1]?.trim() ?? record.path;const title = text.match(/^#\s+(.+)$/m)?.[1]?.trim() ?? '';const before =- record.baseContent == null- ? 'new'- : (parseAuthority(record.baseContent, record.previousPath) ?? '?');+ record.baseContent == null ? 'new' : authorityOf(record.baseContent);const after =record.headContent == null? 'removed'- : (parseAuthority(record.headContent, record.path) ?? '?');+ : authorityOf(record.headContent);const change = before === after ? after : `${before} → ${after}`;return `| \`${id}\` | ${title} | ${change} | ${groupFor(record)} |`;});diff --git a/.github/scripts/spec-owner-reconcile.test.mjs b/.github/scripts/spec-owner-reconcile.test.mjsindex 93dce03125..7c7f910126 100644--- a/.github/scripts/spec-owner-reconcile.test.mjs+++ b/.github/scripts/spec-owner-reconcile.test.mjs@@ -378,6 +378,53 @@ function createDesignHarness(options = {}) {}describe('spec owner workflow reconciliation', () => {+ it.each([+ [+ 'a generated table beside a spec',+ 'docs/specs/AST-094-touch-presentations/motion-roles.md',+ '<!-- Generated. Do not edit. -->\n\n# Motion roles\n\n| role |\n',+ ],+ [+ 'a README that shows front-matter examples',+ 'packages/native/specs/README.md',+ [+ '# Native specs',+ '',+ '```md',+ '---',+ 'authority: draft',+ '---',+ '```',+ '',+ '```md',+ '---',+ 'authority: current',+ '---',+ '```',+ '',+ ].join('\n'),+ ],+ ])(+ 'waits for an engineering owner on %s, and its details say so',+ async (_, filename, headContent) => {+ const harness = createHarness({+ changedFile: {filename, status: 'modified'},+ baseContent: '# Before\n',+ headContent,+ });++ await run(harness, context({runId: 100n, action: 'synchronize'}));++ expect(latestGateStatus(harness.state)).toMatchObject({+ state: 'pending',+ description: 'Mirrors review-required · spec waiting (eng)',+ });+ expect(harness.state.summary).toContain('| eng owner |');+ expect(harness.state.summary).toContain('no authority');+ expect(harness.state.summary).not.toContain('none (draft)');+ },+ );+it('skips the owner reads and the label call for a pull request that changes no records', async () => {const harness = createHarness({changedFile: {filename: 'README.md', status: 'modified'},diff --git a/docs/architecture/knowledge-contracts.md b/docs/architecture/knowledge-contracts.mdindex 270ac01abd..71a1994b57 100644--- a/docs/architecture/knowledge-contracts.md+++ b/docs/architecture/knowledge-contracts.md@@ -864,14 +864,25 @@ this flow passes the historical review benchmark and is enforced on pull requestcomponent/module changes as no DD change, DD-only, or mixed from trusted baseand head bytes. DD-only requires unchanged path, kind, authority, and every byteoutside a valid optional block.-- `.github/scripts/change-scope.cjs` identifies pure spec-record changes.+- `.github/scripts/knowledge-paths.cjs` holds the one list of record paths.+ It names the records `check:knowledge` discovers and the owner-gated paths:+ every record; every Markdown file under `docs/specs/` or a package's+ `specs/` or `docs/architecture/`, READMEs included; every Markdown file in+ the family, design, architecture and theme-docs folders except each+ folder's `README.md` index; every `*.spec.md` in a theme package; and the+ normative design assets. Ignored locations stay ignored.+- `.github/scripts/change-scope.cjs` identifies pure spec-record changes and+ the owner-gated paths a change touches, and classifies paths for callers+ outside the workflow (`--classify-paths`).- `.github/workflows/review-signal.yml` publishes the one review gate,`review-required`, which carries spec-owner approval too (DEC-14). One owner approval covers every knowledge-record change in the pullrequest and binds the approved spec content, not a commit. Approval for everyrecord kind derives from `.github/ENGOWNERS`; current design and theme records,normative design assets, and DD-only current component/module changesadditionally accept `.github/DESIGNOWNERS`. A mixed DD plus other- component/module edit requires both groups. Record metadata never+ component/module edit requires both groups. An owner-gated Markdown file with+ no authority of its own, such as a generated table beside a spec, requires an+ engineering owner. Record metadata neverself-authorizes. The gate decides approval only; it never enables auto-merge.- `.github/workflows/review-signal.yml` lets a DESIGNOWNER author bypass theengineering gate only when trusted-base code verifies every changed Core line@@ -1146,12 +1157,12 @@ checks, the owner gate, and path routing.A spec owner reviews a pull request's knowledge-record changes together andapproves or reworks them as a whole. The approval binds the **spec content**:-one fingerprint over every changed knowledge-record and normative design-asset-path, each read at a commit. In Markdown records the fingerprint omits the-front-matter `authority`, `approved_by`, and `approved_at` values, so recording-an approval and moving a record from `draft` to `current` never change it. The-workflow computes every fingerprint from the pull request's files; no comment,-label, or status supplies it.+one fingerprint over every changed owner-gated path, each read at a commit. In+Markdown records the fingerprint omits the front-matter `authority`,+`approved_by`, and `approved_at` values, so recording an approval and moving a+record from `draft` to `current` never change it. The workflow computes every+fingerprint from the pull request's files; no comment, label, or status+supplies it.- **Approving acts.** Each of these, by an eligible owner, approves the contentof the commit it names, and counts while that commit's fingerprint equals the@@ -1253,22 +1264,22 @@ because the reader never sees the hook wired.## Verification-| Invariant | Evidence | Failure signal |-| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| INV1, INV6 | `scripts/check-knowledge.test.mjs` | An unapproved current record or unmigrated active record passes |-| INV5, INV7 | `.github/scripts/change-scope.test.mjs` | A template, schema, guidance, architecture, code change, unsafe rename, or truncated list qualifies as spec-only |-| Approval follows the spec content | `.github/scripts/spec-owner-decision.test.mjs` | An approval of other spec content clears the gate, a self-declared owner becomes an approver, or the wrong owner group approves a current record |-| INV3, INV4, INV11 | Blinded historical review benchmark | Reviewer re-asks a settled decision, invents a new one, approves an unsettled public delta, or treats a contradiction as preserves |-| INV10 | Record-content and review-disposition fixtures | A spec assigns a PR verdict, or a reviewer treats a PR link as authority |-| INV13 | Blinded spec-authorship fixture plus overlap-search receipt | An author creates parallel authority, searches only landed records or filenames, misses open work on the canonical owner, or treats an open PR as authority |-| INV14, INV15 | Narrow-decision and mixed-intent review fixtures | A current visual slice is forced to contract its whole module, a separable tagalong blocks a repair, or review reports a gap without a landing-ready remedy |-| INV16, INV17 | Spec-first review and missing-context fixtures | Generated checklist completeness overrides authority, review invents product direction, restates supplied context, or fails to identify an unrelated tagalong or affected caller state |-| INV18 | Spec-review mechanism analysis plus owner migration receipt | A new/amended product spec requires a private mechanism without proving it is public, silently invalidates an existing current record, or leaves touched architecture wording in the product contract |-| INV19 | Spec-review ownership-collision receipt and human decision | Automated review approves a product contract, omits current/open owner overlap, misses a collision or architecture leak, or returns only a human hold without actionable written analysis |-| INV20, DEC-9 | `scripts/check-knowledge.test.mjs` and `scripts/review-global-baselines.mjs` | A matching review misses a current global claim, loads a draft/nonmatching claim, loses base-commit provenance, or treats the rest of a routed record as authority |-| INV21, DEC-10 | `.github/scripts/component-design-decisions.test.mjs`, `.github/scripts/review-signal-decision.test.mjs`, `.github/scripts/spec-owner-decision.test.mjs`, and `.github/scripts/lib/classify-visual.test.mjs` | A malformed/local DD escapes validation, stale approval clears a new head, owner routing loses mixed-change gates, or executable/API/unknown runtime code is misclassified as appearance-only |-| DEC-14 | `.github/scripts/spec-owner-reconcile.test.mjs`, `.github/scripts/spec-owner-decision.test.mjs`, and `.github/scripts/spec-owner-workflow.test.mjs` | A non-spec commit, base merge, rebase, or status flip resets approval; changed spec text or a new spec path keeps it; a command naming other spec content, a reaction, a non-owner act, or an author review approves; `review-required` succeeds while spec approval is missing or before the spec decision is published; a revoke or request for changes naming other spec content is ignored; a missing approval reports failure; or an evaluation leaves its head without a terminal state |-| DEC-11 | `.github/scripts/review-signal-decision.test.mjs`, `.github/scripts/review-clear-workflow.test.mjs`, and `.github/scripts/review-signal-workflow.test.mjs` | An app approval clears a read-only or fork author or an earlier head; a later app request for changes or dismissal leaves the gate clear; an app approval overrides an ENGOWNER request for changes; or an unset app or unreadable permission clears the gate |+| Invariant | Evidence | Failure signal |+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| INV1, INV6 | `scripts/check-knowledge.test.mjs` | An unapproved current record or unmigrated active record passes |+| INV5, INV7 | `.github/scripts/change-scope.test.mjs` | A template, schema, guidance, architecture, code change, unsafe rename, or truncated list qualifies as spec-only |+| Approval follows the spec content | `.github/scripts/spec-owner-decision.test.mjs` | An approval of other spec content clears the gate, a self-declared owner becomes an approver, or the wrong owner group approves a current record |+| INV3, INV4, INV11 | Blinded historical review benchmark | Reviewer re-asks a settled decision, invents a new one, approves an unsettled public delta, or treats a contradiction as preserves |+| INV10 | Record-content and review-disposition fixtures | A spec assigns a PR verdict, or a reviewer treats a PR link as authority |+| INV13 | Blinded spec-authorship fixture plus overlap-search receipt | An author creates parallel authority, searches only landed records or filenames, misses open work on the canonical owner, or treats an open PR as authority |+| INV14, INV15 | Narrow-decision and mixed-intent review fixtures | A current visual slice is forced to contract its whole module, a separable tagalong blocks a repair, or review reports a gap without a landing-ready remedy |+| INV16, INV17 | Spec-first review and missing-context fixtures | Generated checklist completeness overrides authority, review invents product direction, restates supplied context, or fails to identify an unrelated tagalong or affected caller state |+| INV18 | Spec-review mechanism analysis plus owner migration receipt | A new/amended product spec requires a private mechanism without proving it is public, silently invalidates an existing current record, or leaves touched architecture wording in the product contract |+| INV19 | Spec-review ownership-collision receipt and human decision | Automated review approves a product contract, omits current/open owner overlap, misses a collision or architecture leak, or returns only a human hold without actionable written analysis |+| INV20, DEC-9 | `scripts/check-knowledge.test.mjs` and `scripts/review-global-baselines.mjs` | A matching review misses a current global claim, loads a draft/nonmatching claim, loses base-commit provenance, or treats the rest of a routed record as authority |+| INV21, DEC-10 | `.github/scripts/component-design-decisions.test.mjs`, `.github/scripts/review-signal-decision.test.mjs`, `.github/scripts/spec-owner-decision.test.mjs`, and `.github/scripts/lib/classify-visual.test.mjs` | A malformed/local DD escapes validation, stale approval clears a new head, owner routing loses mixed-change gates, or executable/API/unknown runtime code is misclassified as appearance-only |+| DEC-14 | `.github/scripts/spec-owner-reconcile.test.mjs`, `.github/scripts/spec-owner-decision.test.mjs`, `.github/scripts/spec-owner-workflow.test.mjs`, and `.github/scripts/knowledge-paths.test.mjs` | A non-spec commit, base merge, rebase, or status flip resets approval; changed spec text or a new spec path keeps it; a command naming other spec content, a reaction, a non-owner act, or an author review approves; `review-required` succeeds while spec approval is missing or before the spec decision is published; a revoke or request for changes naming other spec content is ignored; a missing approval reports failure; an evaluation leaves its head without a terminal state; or a current record `check:knowledge` discovers, or an owner-gated Markdown file with no authority of its own, changes without an owner |+| DEC-11 | `.github/scripts/review-signal-decision.test.mjs`, `.github/scripts/review-clear-workflow.test.mjs`, and `.github/scripts/review-signal-workflow.test.mjs` | An app approval clears a read-only or fork author or an earlier head; a later app request for changes or dismissal leaves the gate clear; an app approval overrides an ENGOWNER request for changes; or an unset app or unreadable permission clears the gate || Invariant | Evidence | Failure signal || -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |diff --git a/scripts/check-knowledge.mjs b/scripts/check-knowledge.mjsindex 427e509297..d486d78f7f 100644--- a/scripts/check-knowledge.mjs+++ b/scripts/check-knowledge.mjs@@ -37,6 +37,7 @@ const {componentSpecPathForSource,isComponentSpecRecordPath,isIgnoredComponentKnowledgeSegment,+ isKnowledgeRecordPath,isPlatformComponentSpecPath,locateComponentKnowledgePath,} = require('../.github/scripts/knowledge-paths.cjs');@@ -528,21 +529,6 @@ function repositoryFileList(root) {}}-function isKnowledgeRecordPath(filePath) {- if (/^docs\/(?:architecture|design|families)\/[^/]+\.md$/.test(filePath)) {- return !filePath.endsWith('/README.md');- }- if (/^docs\/specs\/[^/]+\/(?:spec|plan)\.md$/.test(filePath)) {- return true;- }- const themeMatch = /^packages\/themes\/([^/]+)\/([^/]+)\.spec\.md$/.exec(- filePath,- );- if (themeMatch) return themeMatch[1] === themeMatch[2];- if (classifyPackageArchitectureRecordPath(filePath)) return true;- return isComponentSpecRecordPath(filePath);-}-const REVIEW_CONCERN_NAME_PATTERN = REVIEW_TRIGGER_PATTERN;const IDENTIFIER_PATTERN = /^[A-Za-z_$][\w$]*$/;