Skip to content

Commit 7f5136d

Browse files
thymikeeclaude
andcommitted
test(repo-guards): give the ADR citation guard an owner in selection
ci.yml ignores docs paths and the selector treated an ADR as docs-only, so a PR that added a stale citation got no signal. Add the adr-citations gate, select it for docs/adr/NNNN-*.md, and run it in docs.yml. Scan every token in a backticked span so a path inside a longer span is checked, and inline the single-use tracked-file listing. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent e11d901 commit 7f5136d

11 files changed

Lines changed: 58 additions & 21 deletions

File tree

‎.github/workflows/docs.yml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ on:
99
- 'website/**'
1010
- 'server.json'
1111
- 'README.md'
12+
- 'docs/adr/*.md'
13+
- 'test/repo-guards/adr-citations.test.ts'
1214
- 'scripts/check-doc-links.ts'
1315
- 'scripts/__tests__/check-doc-links.test.ts'
1416
- 'scripts/check-doc-prose.ts'
@@ -28,6 +30,8 @@ on:
2830
- 'website/**'
2931
- 'server.json'
3032
- 'README.md'
33+
- 'docs/adr/*.md'
34+
- 'test/repo-guards/adr-citations.test.ts'
3135
- 'scripts/check-doc-links.ts'
3236
- 'scripts/__tests__/check-doc-links.test.ts'
3337
- 'scripts/check-doc-prose.ts'
@@ -66,6 +70,11 @@ jobs:
6670
uses: ./.github/actions/run-gate
6771
with: { gate: docs-prose }
6872

73+
# ci.yml ignores docs paths, so an ADR-only PR never reaches the unit lane.
74+
- name: Check ADR citations
75+
uses: ./.github/actions/run-gate
76+
with: { gate: adr-citations }
77+
6978
# The page's cells are generated from runtime facts; the guard regenerates,
7079
# diffs, and proves its own negative cases before anything reads the page.
7180
- name: Check the capabilities page against runtime facts

‎docs/adr/0024-screen-recording-provable-signal.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,7 @@ Six rules make the table operational:
7070
Forced cleanup is never inferred from "finish threw".
7171
The mechanism is in the shared coordinator (`packages/capture-kit/src/durable-capture/transitions.ts`).
7272
But each kind must earn its scope.
73-
Each of app-log, audio-probe, and perf-capture gets its own failed-finish test that proves what its retry needs; perf capture already preserves retry material but has no such test yet.
73+
Each of app-log and audio-probe gets its own failed-finish test that proves what its retry needs; perf capture already has one (`session-capture-binding.test.ts`).
7474
A kind whose retry needs nothing keeps its current disposal explicitly.
7575
The Android data loss alone establishes the rule for recording only.
7676

‎docs/adr/0032-layering-graph-engine.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ Thus, `typeof import('./x').f` and `await import('./x')` retain whichever appear
6565

6666
Fallow agrees with custom on value/type classification for every pair but has no dynamic kind.
6767
Its boundary check follows `export type *` barrels to the declaring module.
68-
`src/commands/cli-runner.ts → src/agent-device-client.ts` therefore counts as `commands → client`. This adds one more R6 finding.
68+
The edge from `src/commands/cli-runner.ts` to the retired src/agent-device-client.ts therefore counts as `commands → client`. This adds one more R6 finding.
6969
Clean-tree findings are custom 0, depcruise 10, and fallow 11.
7070
Depcruise's ten are three R6 survivors and seven recorded R78 edges.
7171

‎docs/adr/FORMAT.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ Do not repeat general repo guidance that `AGENTS.md` already gives.
4444

4545
## The record stays current
4646

47-
An ADR states the current truth. It is not a log of the discussion around the decision. A repo guard fails when a backticked repository path or test file name in an ADR does not match a tracked file. An optional dated "Decision history" line records a real change of direction. If the direction really changed, you may add one such line with its reason and a link.
47+
An ADR states the current truth. It is not a log of the discussion around the decision. A repo guard fails when a backticked repository path or test file name in an ADR does not match a tracked file. To name a retired path, write the path in prose without backticks. An optional dated "Decision history" line records a real change of direction. If the direction really changed, you may add one such line with its reason and a link.
4848

4949
## Before you amend
5050

‎package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -167,6 +167,7 @@
167167
"check:bundle-owner-files": "node --experimental-strip-types scripts/check-bundle-owner-files.ts",
168168
"check:package": "node --experimental-strip-types scripts/check-package.ts",
169169
"check:command-docs": "vitest run --project unit-core test/repo-guards/command-doc-coverage.test.ts",
170+
"check:adr-citations": "vitest run --project unit-core test/repo-guards/adr-citations.test.ts",
170171
"check:capabilities-matrix": "vitest run --project unit-core test/repo-guards/capability-matrix.test.ts",
171172
"generate:capabilities": "node --experimental-strip-types scripts/capability-matrix/generate.ts --write",
172173
"check:doc-links": "node --experimental-strip-types scripts/node-test-tmpdir.ts --experimental-strip-types --test scripts/__tests__/check-doc-links.test.ts && pnpm --dir website build && node --experimental-strip-types scripts/check-doc-links.ts",

‎packages/contracts/src/platform-plugin.ts‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,7 @@ import type { PlatformGatedProviderResolverKey } from './platform-providers.ts';
44
import type { Interactor, RunnerContext } from './interactor-types.ts';
55

66
/**
7-
* The platform-plugin contract. ADR 0009 owns the Apple family decision; ADR 0019 replaced the
8-
* original shallow `PlatformPlugin` shape with the request-bound runtime seam.
7+
* The platform-plugin contract (ADR-0009).
98
*
109
* One plugin owns one platform FAMILY: a plugin may cover several leaf
1110
* {@link Platform} literals (the Apple plugin owns both `ios` and `macos`,

‎scripts/check-affected/checks.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -135,6 +135,7 @@ export const CHECK_CATALOG: readonly CheckSpec[] = [
135135
gate('fixture-cache', 'Trusted fixture-artifact selection', 'test:fixture-cache'),
136136
gate('fixture-fallback', 'Fixture-app cache-failure fallback', 'test:fixture-fallback'),
137137
gate('command-docs', 'Command reference doc coverage', 'check:command-docs'),
138+
gate('adr-citations', 'ADR citations name tracked files', 'check:adr-citations'),
138139
// The docs page's cells are generated from the runtime facts, so the check is
139140
// the guard over that generation: it regenerates and diffs, proves the drift
140141
// report fires on a changed cell, and proves every qualified cell still names

‎scripts/check-affected/model.test.ts‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -231,7 +231,7 @@ test('public package surface change selects the build and the published-package
231231
});
232232

233233
test('docs-only change selects no checks and records the docs paths', () => {
234-
const result = plan(['docs/adr/0011.md', 'LICENSE', 'website/page.mdx.md']);
234+
const result = plan(['docs/adr/README.md', 'LICENSE', 'website/page.mdx.md']);
235235
assert.equal(result.failOpen, false);
236236
assert.deepEqual(result.checks, []);
237237
assert.equal(result.docsOnlyPaths.length, 3);
@@ -278,6 +278,12 @@ test('agent guidance owns its focused contract instead of disappearing as docs-o
278278
}
279279
});
280280

281+
test('an ADR record owns the citation guard instead of disappearing as docs-only', () => {
282+
const result = plan(['docs/adr/0011-interactive-replay.md']);
283+
assert.deepEqual(result.checks, ['adr-citations']);
284+
assert.deepEqual(result.docsOnlyPaths, []);
285+
});
286+
281287
test('test app source selects root lint and format plus its isolated typecheck', () => {
282288
const result = plan(['examples/test-app/app/index.tsx']);
283289
assert.equal(result.failOpen, false);

‎scripts/check-affected/model.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,7 @@ export const ALL_CHECKS = [
7878
'fixture-cache',
7979
'fixture-fallback',
8080
'command-docs',
81+
'adr-citations',
8182
'capabilities-matrix',
8283
'docs-links',
8384
'docs-prose',
@@ -587,6 +588,8 @@ const buildOwnership: OwnershipRule = ({ file }, input) => {
587588
const COMMAND_DOCS = 'website/docs/docs/commands.md';
588589
const AGENT_GUIDANCE = new Set(['AGENTS.md', 'CONTEXT.md', 'docs/adr/FORMAT.md']);
589590

591+
const ADR_RECORD = /^docs\/adr\/\d{4}-.*\.md$/;
592+
590593
function isAgentGuidance(file: string): boolean {
591594
return AGENT_GUIDANCE.has(file) || file.startsWith('docs/agents/');
592595
}
@@ -628,6 +631,16 @@ const docsOwnership: OwnershipRule = ({ file }) => {
628631
),
629632
);
630633
}
634+
if (ADR_RECORD.test(file)) {
635+
selections.push(
636+
reason(
637+
'adr-citations',
638+
file,
639+
'own:adr-citations',
640+
'every repository file an ADR cites must exist',
641+
),
642+
);
643+
}
631644
if (file === CAPABILITIES_PAGE) {
632645
selections.push(
633646
reason(

‎scripts/layering/tracked-sources.ts‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -57,11 +57,6 @@ export function listTrackedSrcUtilsFiles(repoRoot: string): string[] {
5757
return listTrackedFilesUnderRoot(repoRoot, 'src/utils');
5858
}
5959

60-
/** Every tracked path in the repository. */
61-
export function listTrackedRepoFiles(repoRoot: string): string[] {
62-
return listTrackedFiles(repoRoot, []);
63-
}
64-
6560
function listTrackedFilesUnderRoot(repoRoot: string, root: string): string[] {
6661
return listTrackedFiles(repoRoot, [root]);
6762
}

0 commit comments

Comments
 (0)