promote: 17 memory updates from 2026-05-26 scan

[gyulsbox]

Summary

promote-cli detected 17 repeated AI review pattern(s) across 65 PR(s) over the last 90 days and is proposing the corresponding memory updates. See Memory promotion details below for evidence and reasoning per candidate.

Why

Repeated review comments often encode implicit conventions that future agents and contributors should already know. This PR promotes 17 such pattern(s) into durable repository memory so the same review feedback doesn't have to be re-issued PR after PR.

Changes

• docs/test-stubs/test-files-must-import-all-vitest-functions-before.md — Test files must import all Vitest functions (beforeAll, describe, expect, it) that are used to avoid runtime errors. (candidate_014, confidence 0.95)
• .claude/rules/multiple-packages-declare-cli-entrypoints-in-bin-b.instructions.md — Multiple packages declare CLI entrypoints in bin/ but fail to include bin/ in their files allowlist, causing broken binaries on npm publish. (candidate_018, confidence 0.95)
• .claude/rules/test-files-should-use-the-standard-testserverandcl.instructions.md — Test files should use the standard testServerAndClientResource pattern instead of manually managing server lifecycle and client setup. (candidate_031, confidence 0.85)
• AGENTS.md — Avoid non-null assertions (!) in TypeScript code; use explicit type guards or optional chaining instead. (candidate_035, confidence 0.85)
• .claude/rules/eslint-rules-and-suppressions-must-be-migrated-to.instructions.md — ESLint rules and suppressions must be migrated to Oxlint equivalents before Oxlint is enabled in a package. (candidate_037, confidence 0.75)
• .claude/rules/test-files-should-use-await-using-pattern-with-tes.instructions.md — Test files should use await using pattern with testServerAndClientResource directly instead of run(...) wrapper, and configure client behavior via callback pattern. (candidate_038, confidence 0.85)
• .claude/rules/typesnode-major-version-must-align-with-enginesnod.instructions.md — @types/node major version must align with engines.node specification across package.json files. (candidate_041, confidence 0.85)
• AGENTS.md — Avoid destructuring directly in function parameter declarations; use property access instead. (candidate_049, confidence 0.85)
• .claude/rules/directory-read-error-handling-in-wwwscriptscheck-t.instructions.md — Directory-read error handling in www/scripts/check-twoslash.ts should only suppress ENOENT errors, not all filesystem errors. (candidate_058, confidence 0.85)
• .claude/rules/multiple-packagejson-files-incorrectly-reference-n.instructions.md — Multiple package.json files incorrectly reference non-existent ./bin/intent.js entry points, and workflow paths reference incorrect documentation directory structure. (candidate_060, confidence 0.85)
• .claude/rules/the-maxbatchsize-parameter-must-be-validated-as-a.instructions.md — The maxBatchSize parameter must be validated as a finite positive integer to prevent runtime bugs from NaN, Infinity, and invalid values. (candidate_061, confidence 0.85)
• .claude/rules/server-sent-events-retry-logic-should-not-consume.instructions.md — Server-sent events retry logic should not consume retry budget on initial connection and should exclude AbortError from retryable conditions. (candidate_062, confidence 0.85)
• .claude/rules/github-actions-workflows-using-lerna-publish-must.instructions.md — GitHub Actions workflows using lerna publish must either grant permissions.contents: write or explicitly use --no-push and --no-git-tag-version flags to avoid permission failures. (candidate_064, confidence 0.85)
• .claude/rules/multiple-trpc-packages-expose-a-generic-intent-bin.instructions.md — Multiple @trpc/* packages expose a generic intent binary that causes node_modules/.bin collisions and shadows @tanstack/intent; use namespaced binary names instead. (candidate_065, confidence 0.85)
• .claude/rules/multiple-packages-incorrectly-declare-binintent-en.instructions.md — Multiple packages incorrectly declare bin.intent entries pointing to non-existent ./bin/intent.js files, breaking CLI executables in published packages. (candidate_070, confidence 0.85)
• docs/test-stubs/test-helpers-must-avoid-temporal-dead-zone-errors.md — Test helpers must avoid temporal dead zone errors by declaring subscription variables before subscribe() calls to handle synchronous onError callbacks safely. (candidate_071, confidence 0.85)
• .claude/rules/tanstack-react-query-test-files-must-use-namespace.instructions.md — TanStack React Query test files must use namespace imports for React (import * as React) rather than named imports. (candidate_072, confidence 0.85)
• docs/promote/digests/2026-05-26.md — full scan digest (included for traceability)

Testing

• Each draft was generated by LLM and requires human review before merge — read the appended content in each affected file.
• Compare against the reasoning and evidence in Memory promotion details below.
• For the full picture (including skipped / needs_human_decision candidates), see docs/promote/digests/2026-05-26.md.

Memory promotion details

Generated by promote-cli v0.7.1 from scan run on 2026-05-26.

Bundled candidates

1. Test files must import all Vitest functions (beforeAll, describe, expect, it) that are used to avoid runtime errors. (target: test, confidence: 0.95)

• File: docs/test-stubs/test-files-must-import-all-vitest-functions-before.md
• Evidence: #7283 packages/openapi/test/cyclicTypes.test.ts, #7252 packages/client/skills/links/references/link-options.md, #7231 packages/openapi/test/edgeCases.test.ts, #7231 packages/openapi/test/edgeCases.test.ts, #7283 packages/openapi/test/cyclicTypes.test.ts, …and 1 more
• Reasoning: This is a testable runtime invariant: test files that use Vitest functions without importing them will fail at runtime. This is a mechanical check that should be enforced across all test files in the repository. The pattern appears consistently across multiple test files (cyclicTypes.test.ts, edgeCases.test.ts, next-app-dir.test.ts) and represents a class of errors that can be prevented with proper linting or test setup validation.
• Alternatives considered: agents: Could be documented as a coding convention for test files, but the runtime failure aspect makes it more of a testable invariant than a style guide.; path_scoped_rule: Could apply specifically to test files (*.test.ts), but the issue is fundamental to how Vitest works rather than path-specific.

2. Multiple packages declare CLI entrypoints in bin/ but fail to include bin/ in their files allowlist, causing broken binaries on npm publish. (target: path_scoped_rule, confidence: 0.95)

• File: .claude/rules/multiple-packages-declare-cli-entrypoints-in-bin-b.instructions.md
• Evidence: #7252 packages/next/package.json, #7252 packages/server/package.json, #7252 packages/tanstack-react-query/package.json, #7252 packages/next/package.json, #7252 packages/client/package.json, …and 3 more
• Reasoning: This is a repeated structural issue across 4 specific packages (next, client, server, tanstack-react-query) in the same monorepo. The pattern is: declared bin entry + missing files allowlist = broken published binary. This is a path-scoped rule that should apply to all packages/* that declare bin entries, ensuring they include bin/ in files. It's not a one-off PR issue—it's a systemic packaging misconfiguration that will recur unless documented.
• Alternatives considered: adr: Could document the architectural decision about why bin entries should be included in files, but the issue is primarily mechanical/structural rather than about design rationale.; test: Could be enforced as a test that validates: if package.json declares bin entries, files array must include bin/. However, this is more of a linting rule than a runtime invariant.

3. Test files should use the standard testServerAndClientResource pattern instead of manually managing server lifecycle and client setup. (target: path_scoped_rule, confidence: 0.85)

• File: .claude/rules/test-files-should-use-the-standard-testserverandcl.instructions.md
• Evidence: #7304 packages/tests/server/httpSubscriptionLink.fetch.test.ts, #7231 packages/openapi/test/generate.test.ts
• Reasoning: This is a repeated pattern specific to test files (*.test.ts) across multiple packages. The comments consistently recommend replacing manual server/client setup with a standardized helper pattern. This is a path-scoped rule because it applies specifically to test files and involves a testing convention, not a general coding practice.
• Alternatives considered: agents: Could be promoted to general AI instructions if this pattern should apply to all test writing across the repo; test: Could be framed as a testable invariant that integration tests must use the standard pattern

4. Avoid non-null assertions (!) in TypeScript code; use explicit type guards or optional chaining instead. (target: agents, confidence: 0.85)

• File: AGENTS.md
• Evidence: #7176 packages/client/src/createTRPCClient.ts, #7195 www/scripts/check-twoslash.ts
• Reasoning: This is a repeated cross-cutting coding convention appearing in multiple files and PRs. The pattern reflects a deliberate choice to enforce strict TypeScript safety practices repo-wide, not a one-off issue. Future code reviews will benefit from having this guideline documented in agent instructions.
• Alternatives considered: path_scoped_rule: Could be scoped to packages/client and www/scripts, but the pattern is general TypeScript practice applicable everywhere; test: Could be enforced via a linter rule (e.g., @typescript-eslint/no-non-null-assertion), but the comments focus on the guideline itself rather than a testable invariant

5. ESLint rules and suppressions must be migrated to Oxlint equivalents before Oxlint is enabled in a package. (target: path_scoped_rule, confidence: 0.75)

• File: .claude/rules/eslint-rules-and-suppressions-must-be-migrated-to.instructions.md
• Evidence: #7205 packages/tanstack-react-query/package.json, #7206 packages/react-query/src/internals/context.tsx
• Reasoning: This is a repeated pattern specific to the linting infrastructure transition from ESLint to Oxlint. It applies to packages that declare both eslintConfig and use Oxlint in their lint scripts. The pattern is actionable and scoped to packages undergoing this migration, making it a path-scoped rule rather than a general agent instruction.
• Alternatives considered: adr: If the decision to migrate to Oxlint and the rationale for requiring complete migration before enablement is important to document; agents: If this becomes a repo-wide policy that all packages must follow during Oxlint adoption

6. Test files should use await using pattern with testServerAndClientResource directly instead of run(...) wrapper, and configure client behavior via callback pattern. (target: path_scoped_rule, confidence: 0.85)

• File: .claude/rules/test-files-should-use-await-using-pattern-with-tes.instructions.md
• Evidence: #7207 packages/tests/server/httpSubscriptionLink.test.ts, #7262 packages/tests/server/regression/batchStreamErrorCallIndex.test.ts
• Reasoning: This is a repeated pattern specific to test files (*.test.ts) in the packages/tests directory. The comments address both a preferred initialization pattern (await using over run()) and a consistent configuration approach (callback pattern). These are conventions that apply across multiple test files in the same domain.
• Alternatives considered: agents: Could be promoted to general AI instructions if this pattern applies beyond just the test suite to all test files repo-wide; none: If these are one-off refactoring suggestions specific to those two PRs rather than a durable pattern

7. @types/node major version must align with engines.node specification across package.json files. (target: path_scoped_rule, confidence: 0.85)

• File: .claude/rules/typesnode-major-version-must-align-with-enginesnod.instructions.md
• Evidence: #7210 package.json, #7200 package.json
• Reasoning: This is a repeated pattern specific to dependency management in package.json files. The rule applies consistently: @types/node's major version should match the Node.js major version specified in engines.node. This is a structural constraint that applies to all package.json files in the monorepo and should be enforced as a path-scoped rule rather than a general agent instruction, since it's specifically about package.json configuration.
• Alternatives considered: agents: Could be a repo-wide convention if this applies to all packages, but it's more precisely a package.json-specific constraint; adr: Could document the architectural decision to keep types and runtime in sync, but the pattern is primarily a structural rule rather than a rationale

8. Avoid destructuring directly in function parameter declarations; use property access instead. (target: agents, confidence: 0.85)

• File: AGENTS.md
• Evidence: #7283 packages/openapi/test/types.ts, #7199 packages/tests/server/transformer.test.ts
• Reasoning: This is a repeated cross-cutting coding convention that appears in multiple packages and test files. The pattern is consistent enough to warrant documentation as a repo-wide AI instruction to prevent future violations across the codebase.
• Alternatives considered: path_scoped_rule: Could be scoped to test files (packages/tests/, packages/*/test/) if the rule is only enforced in test code; none: If this is already documented in existing style guides or linters, promotion may be redundant

9. Directory-read error handling in www/scripts/check-twoslash.ts should only suppress ENOENT errors, not all filesystem errors. (target: path_scoped_rule, confidence: 0.85)

• File: .claude/rules/directory-read-error-handling-in-wwwscriptscheck-t.instructions.md
• Evidence: #7195 www/scripts/check-twoslash.ts, #7196 www/scripts/check-twoslash.ts
• Reasoning: This is a specific, repeated pattern in a single file (www/scripts/check-twoslash.ts) where overly broad error suppression masks real failures. The pattern appears twice in consecutive PRs affecting the same code path, indicating a genuine issue that needs to be enforced for this particular script. It's not a cross-cutting convention but rather a specific rule for this directory-scanning utility.
• Alternatives considered: test: Could be enforced as a runtime test that verifies permission/IO errors are not silently swallowed; adr: If there's architectural reasoning about why this script specifically needs strict error handling, that context could be documented

10. Multiple package.json files incorrectly reference non-existent ./bin/intent.js entry points, and workflow paths reference incorrect documentation directory structure. (target: path_scoped_rule, confidence: 0.85)

• File: .claude/rules/multiple-packagejson-files-incorrectly-reference-n.instructions.md
• Evidence: #7252 packages/client/package.json, #7252 packages/openapi/package.json, #7252 packages/tanstack-react-query/package.json, #7252 packages/next/package.json, #7252 .github/workflows/notify-intent.yml, …and 1 more
• Reasoning: This is a systematic issue affecting multiple packages in the monorepo (client, openapi, tanstack-react-query, next) plus a workflow configuration. The pattern is specific to the monorepo's package structure and bin/ directory conventions. It's not a one-off issue but a repeated misconfiguration across multiple package.json files that needs to be caught and prevented. This is best captured as a path-scoped rule for packages/* that validates bin entry points exist before publishing.
• Alternatives considered: adr: Could document the decision to use intent shims and why they should exist, but the core issue is a missing file, not a design decision.; test: Could create a test that validates all bin entry points in package.json files actually exist, but this is more of a linting/validation concern than a runtime invariant.

11. The maxBatchSize parameter must be validated as a finite positive integer to prevent runtime bugs from NaN, Infinity, and invalid values. (target: path_scoped_rule, confidence: 0.85)

• File: .claude/rules/the-maxbatchsize-parameter-must-be-validated-as-a.instructions.md
• Evidence: #7191 packages/server/src/unstable-core-do-not-import/http/types.ts, #7191 packages/server/src/unstable-core-do-not-import/http/contentType.ts
• Reasoning: This is a specific validation rule for the maxBatchSize parameter that appears in multiple files within the http package. It's not a general coding convention but rather a domain-specific validation requirement for this particular parameter across the http module. The pattern shows the same underlying issue (insufficient input validation) in related files, making it suitable for a path-scoped rule.
• Alternatives considered: test: This could be enforced as a runtime test invariant to ensure maxBatchSize validation is mechanically checked; agents: Could be promoted as a general AI instruction about validating numeric configuration parameters; adr: Could document the architectural decision to validate numeric limits rather than rely on runtime comparison behavior

12. Server-sent events retry logic should not consume retry budget on initial connection and should exclude AbortError from retryable conditions. (target: path_scoped_rule, confidence: 0.85)

• File: .claude/rules/server-sent-events-retry-logic-should-not-consume.instructions.md
• Evidence: #7231 packages/openapi/test/routers/errorFormatterRouter-heyapi/core/serverSentEvents.gen.ts, #7231 packages/openapi/test/routers/appRouter-heyapi/core/serverSentEvents.gen.ts
• Reasoning: This is a specific bug pattern in SSE retry handling that appears in multiple generated serverSentEvents files. It's scoped to the SSE implementation path and describes a concrete behavioral rule about when retries should be attempted. The pattern is repeated across similar files in the same domain (errorFormatterRouter and appRouter variants), indicating a systematic issue in how retry logic is implemented.
• Alternatives considered: test: This could be enforced as a test invariant: verify that AbortError does not trigger retries and that sseMaxRetryAttempts correctly reflects actual retry count.; adr: If there is architectural reasoning about why initial connects should not consume budget or why aborts are special, that rationale could be documented.

13. GitHub Actions workflows using lerna publish must either grant permissions.contents: write or explicitly use --no-push and --no-git-tag-version flags to avoid permission failures. (target: path_scoped_rule, confidence: 0.85)

• File: .claude/rules/github-actions-workflows-using-lerna-publish-must.instructions.md
• Evidence: #7247 .github/workflows/release-tmp.yml, #7247 .github/workflows/release-canary.yml
• Reasoning: This is a specific constraint that applies to all GitHub Actions workflows in .github/workflows/ that use Lerna for publishing. The pattern identifies a concrete incompatibility between read-only content permissions and Lerna's default git operations. It's not a general coding convention (agents) but rather a path-scoped rule for workflow files that use this tool.
• Alternatives considered: adr: Could document the architectural decision about why these workflows need specific permission levels and when git operations are necessary; test: Could be enforced as a CI check that validates workflow files don't have this permission/lerna mismatch

14. Multiple @trpc/* packages expose a generic intent binary that causes node_modules/.bin collisions and shadows @tanstack/intent; use namespaced binary names instead. (target: path_scoped_rule, confidence: 0.85)

• File: .claude/rules/multiple-trpc-packages-expose-a-generic-intent-bin.instructions.md
• Evidence: #7252 packages/server/package.json, #7252 packages/server/package.json, #7252 packages/server/package.json, #7252 packages/client/package.json, #7252 packages/next/package.json
• Reasoning: This is a specific, repeated issue affecting multiple package.json files in the packages/* directory. The pattern is consistent across @trpc/server, @trpc/client, and @trpc/next packages, making it a path-scoped rule for the packages/* directory. The issue involves both missing bin files and naming collisions that need to be prevented across this specific path scope.
• Alternatives considered: adr: The architectural decision to avoid generic binary names in favor of namespaced ones could be documented as a design rationale; agents: Could be promoted to general guidance if this pattern applies beyond just @trpc packages

15. Multiple packages incorrectly declare bin.intent entries pointing to non-existent ./bin/intent.js files, breaking CLI executables in published packages. (target: path_scoped_rule, confidence: 0.85)

• File: .claude/rules/multiple-packages-incorrectly-declare-binintent-en.instructions.md
• Evidence: #7252 packages/server/package.json, #7252 packages/client/package.json, #7252 packages/tanstack-react-query/package.json, #7252 packages/client/package.json, #7252 packages/next/package.json, …and 5 more
• Reasoning: This is a repeated pattern across multiple package.json files in different packages (server, client, next, tanstack-react-query) within the same PR. It's a structural/configuration issue specific to how bin entries are declared in package.json files across the packages/ directory. A path-scoped rule would prevent future occurrences by enforcing that bin entries must reference files that actually exist and are included in the package's files array.
• Alternatives considered: adr: If the decision to have a shared CLI entry across multiple packages has architectural significance, an ADR explaining the intended design would be valuable.; test: A test could verify that all bin entries in package.json files reference files that exist and are included in the files array.

16. Test helpers must avoid temporal dead zone errors by declaring subscription variables before subscribe() calls to handle synchronous onError callbacks safely. (target: test, confidence: 0.85)

• File: docs/test-stubs/test-helpers-must-avoid-temporal-dead-zone-errors.md
• Evidence: #7279 packages/tests/server/websockets.test.ts, #7279 packages/tests/server/httpSubscriptionLink.test.ts, #7279 packages/tests/server/websockets.test.ts
• Reasoning: This describes a testable runtime invariant specific to subscription test helpers: synchronous error callbacks must not reference uninitialized variables. The pattern appears across multiple test files in the same PR and describes behavior that causes flaky tests when not handled correctly. This is a mechanical invariant that should be enforced in test code.
• Alternatives considered: path_scoped_rule: Could be scoped to packages/tests/** since it only affects test helpers, but the underlying issue (TDZ with async callbacks) is a general JavaScript pattern worth documenting broadly.; agents: Could be a general coding convention, but the issue is specific enough to subscription testing patterns that test-scoped documentation is more appropriate.

17. TanStack React Query test files must use namespace imports for React (import * as React) rather than named imports. (target: path_scoped_rule, confidence: 0.85)

• File: .claude/rules/tanstack-react-query-test-files-must-use-namespace.instructions.md
• Evidence: #7362 packages/tanstack-react-query/test/client.test.tsx, #7362 packages/tanstack-react-query/test/polymorphism.test.tsx
• Reasoning: This is a consistent pattern specific to the packages/tanstack-react-query/test/ directory. The comments appear in multiple test files within this path and establish a local convention for that package's test suite. It's not a repo-wide convention (agents) but rather a path-scoped requirement for this specific package's tests.
• Alternatives considered: agents: Could be promoted if this namespace import convention applies across all test files repo-wide, but evidence suggests it's specific to TanStack React Query tests; none: If this is merely a style preference without documented rationale, it might not warrant preservation
• Human signal: 1 agreed

Safety

• This PR was generated. Each draft requires human review before merge.
• Full digest (skipped + needs_human_decision candidates included) is committed at docs/promote/digests/2026-05-26.md.