Skip to content

Commit 093341a

Browse files
thymikeeclaude
andauthored
test(repo-guards): fail when an ADR cites a missing repository file (#4336)
* test(repo-guards): fail when an ADR cites a missing repository file Closes the last #4205 completion condition. The guard checks every backticked repository path and bare test file name in docs/adr against the tracked tree, and skips device paths, globs and runtime state names. Also fixes the follow-ups from the slimming reviews: ADR 0005's stale test name, ADR 0012's linkSync rule with --force/--overwrite, ADR 0019's test-IME startup gap, ADR 0024's perf-capture status, and the platform-plugin contract comment that credited ADR 0009. * test(repo-guards): cover Markdown, plist and + paths in the ADR citation guard Address review: scan .md and .plist citations and paths with +, state the guard's exact scope in FORMAT.md, qualify ADR 0012's in-place overwrite rule with --force, and keep perf capture's missing failed-finish test listed in ADR 0024. * 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]> * test(repo-guards): extract the ADR citation token scan Keep findStaleAdrCitations under the complexity gate. Co-Authored-By: Claude Opus 5.5 <[email protected]> * docs(adr): state exactly what the citation guard checks Co-Authored-By: Claude Opus 5.5 <[email protected]> --------- Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent d4eb753 commit 093341a

12 files changed

Lines changed: 159 additions & 10 deletions

‎.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/0005-ios-runner-interaction-lifecycle.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -103,7 +103,7 @@ The cost of a `RUNNER_BUSY` refusal to the caller depends on the daemon's own pe
103103
It does not depend on any runner-side classification of the command.
104104
The trait is `RUNNER_COMMAND_TRAITS` in `packages/apple-runner/src/runner-command-traits.ts`.
105105
`runAppleRunnerCommand` reads it through `isReadOnlyRunnerCommand` when it decides whether to wrap the send in a resend loop.
106-
This asymmetry is shipped, and `runner-client-busy-resend.test.ts` asserts it:
106+
This asymmetry is shipped, and `index-busy-resend.test.ts` in the Apple runner package asserts it:
107107

108108
- A read-only command treats the refusal as *not yet*.
109109
It waits for the drain on the busy-specific budget sized to outlast the drain.

‎docs/adr/0012-interactive-replay.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -152,8 +152,8 @@ Seven normative rules govern it:
152152
Every teardown commits if and only if the state is `COMPLETE`.
153153
Before `COMPLETE`, teardown publishes nothing, and idle-reap or shutdown leaves a `REPAIR_SESSION_EXPIRED` tombstone.
154154
An armed replay skips a terminal source `close` and marks the transaction `COMPLETE`.
155-
Publication writes `<original-stem>.healed.ad` beside the original unless the caller names a path. The original is never overwritten in place.
156-
One exclusive `linkSync` publishes the file and refuses every pre-existing target, for repair and ordinary `--save-script` recording alike.
155+
Publication writes `<original-stem>.healed.ad` beside the original unless the caller names a path. The original is never overwritten in place unless the caller names it as the target with `--force`/`--overwrite`.
156+
Without `--force`/`--overwrite`, one exclusive `linkSync` publishes the file and refuses a pre-existing target, for repair and ordinary `--save-script` recording alike; with the flag, publication replaces the target atomically.
157157

158158
Inside an armed repair segment, out-of-band observation-only commands are excluded from the healed script by default.
159159
Plan-step provenance (`internal.replayPlanStep`) keeps authored observations.

‎docs/adr/0019-request-bound-platform-runtime.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -220,7 +220,7 @@ Startup recovery is triggered only by persisted durable manifests or platform-ow
220220
Daemon shutdown first detaches helper managers for handoff, then stops each still-owned generation at most once after session resources finalize.
221221
Each domain owns its isolated session-teardown step; there is no generic lifecycle-hook API.
222222
Test-IME restoration is durable device state with marker recovery; helper stops follow platform policy; close-time cleanup uses neutral owner services.
223-
Android test-IME marker and web browser orphan startup recovery still need to move to the evidence-triggered pattern when their owning domains migrate.
223+
Android test-IME marker recovery already runs only on recovery evidence; web browser orphan startup cleanup still needs to move to the evidence-triggered pattern when its owning domain migrates.
224224

225225
### 11. The platform-services port carries host asks that bind no device
226226

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Proposed (2026-09-14).
66
This ADR amends ADR 0019 section 5 and the capture-kit recovery contracts for the `screen-recording` resource kind only.
77
ADR 0019 receives a short pointer paragraph, which section 2.7 of this ADR describes.
88
ADR 0022 and ADR 0023 have the same relationship to ADR 0019.
9-
App-log, audio-probe, and perf-capture keep the ADR 0019 contract unchanged.
9+
App-log and audio-probe keep the ADR 0019 contract unchanged; perf capture already preserves retry material after a failed finish.
1010
The shared mechanism of rule 6 reaches each of these kinds only through the own failed-finish test of that kind.
1111

1212
Completed rollout history is in git history.
@@ -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.
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

@@ -322,7 +322,7 @@ This kind would remove the `cleanup-pending` phase and admission ledger.
322322
It would record the recorder observation and native-path disposition beside the committed export.
323323
A manifest would remain archived by fence generation until both are settled.
324324
For each durable kind, failed finish would no longer imply forced cleanup once its failed-finish test states its retry requirements.
325-
App-log, audio-probe, and perf-capture would retain the ADR 0019 contract unchanged.*
325+
App-log and audio-probe would retain the ADR 0019 contract unchanged.*
326326

327327
### 2.8 Android duration (separate decision)
328328

‎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. 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 checks each backticked token with an extension that `test/repo-guards/adr-citations.test.ts` lists. A token that contains `/` must be a tracked path. A bare test file name must be the name of a tracked file. The guard skips absolute paths, home paths, globs, and other bare file names. 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",

‎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);

0 commit comments

Comments
 (0)