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

[gyulsbox]

Summary

promote-cli detected 11 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 11 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_057, confidence 0.95)
• .claude/rules/test-files-should-use-the-standard-testserverandcl.instructions.md — Test files should use the standard testServerAndClientResource pattern with await using for server and client setup instead of manual lifecycle management or helper wrapping. (candidate_059, confidence 0.85)
• .claude/rules/documentation-code-examples-must-be-complete-and-r.instructions.md — Documentation code examples must be complete and runnable, with all referenced functions/options defined or explicitly marked as omitted. (candidate_072, confidence 0.85)
• AGENTS.md — Avoid non-null assertions (!) in TypeScript code; use explicit type guards or optional chaining instead. (candidate_079, confidence 0.85)
• AGENTS.md — Avoid destructuring directly in function parameter declarations; use property access instead. (candidate_094, confidence 0.85)
• .claude/rules/avoid-broad-eslint-disable-comments-and-console-us.instructions.md — Avoid broad eslint-disable comments and console usage in packages/** modules; use explicit logging mechanisms instead. (candidate_099, confidence 0.85)
• docs/adr/001-core-error-metadata-must-be-kept-separate-from-use.md — Core error metadata must be kept separate from user-declared payload data to prevent runtime desynchronization in tRPC error handling. (candidate_107, confidence 0.85)
• .claude/rules/packagejson-bin-entries-must-include-bin-directory.instructions.md — Package.json bin entries must include bin/ directory in files array and ensure the referenced script exists. (candidate_108, confidence 0.85)
• docs/adr/002-multiple-trpc-packages-should-not-expose-generic-b.md — Multiple @trpc/* packages should not expose generic binary names like 'intent' in their bin field, as this causes node_modules/.bin collisions and breaks installations; use namespaced names (e.g., trpc-intent) or avoid re-exporting. (candidate_113, 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_114, confidence 0.85)
• .claude/rules/packagejson-bin-entries-must-reference-executable.instructions.md — Package.json bin entries must reference executable files that actually exist in the package directory, or publishing will create broken executables on install. (candidate_118, 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 through linting or test execution validation.
• Alternatives considered: agents: Could be documented as a coding convention for test file setup, 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 across all test files, not specific to a particular domain.

2. Test files should use the standard testServerAndClientResource pattern with await using for server and client setup instead of manual lifecycle management or helper wrapping. (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, #7207 packages/tests/server/httpSubscriptionLink.test.ts
• Reasoning: This is a repeated refactoring suggestion across multiple test files in the packages/ directory. The pattern is specific to test infrastructure and applies consistently to **/*.test.ts files. It describes a standardized testing convention that should be enforced across the test suite to maintain consistency and proper resource lifecycle management.
• Alternatives considered: agents: Could be documented as a cross-cutting testing convention for all AI agents to follow when reviewing test code; pr_only: If this is a temporary refactoring initiative specific to these PRs rather than a permanent testing standard

3. Documentation code examples must be complete and runnable, with all referenced functions/options defined or explicitly marked as omitted. (target: path_scoped_rule, confidence: 0.85)

• File: .claude/rules/documentation-code-examples-must-be-complete-and-r.instructions.md
• Evidence: #7191 www/docs/client/links/httpBatchLink.md, #7299 www/docs/client/openapi.md, #7252 packages/server/skills/server-side-calls/SKILL.md
• Reasoning: All three examples involve incomplete or non-runnable code snippets in documentation files across different paths. The pattern is specific to documentation (www/docs and SKILL.md files) where readers expect copy-paste-ready examples. This is a documentation quality rule that should apply consistently across all doc files.
• Alternatives considered: agents: Could be a general AI instruction to always provide complete, runnable examples in documentation, but the pattern is more specific to documentation files than a cross-cutting coding convention.; none: If treating each as a one-off documentation issue rather than a systematic pattern requiring enforcement.

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. Documenting this in AGENTS.md will help future code reviewers and AI agents consistently apply the same standard.
• Alternatives considered: path_scoped_rule: Could be scoped to packages/client and www/scripts, but the principle applies broadly across the repo; none: If the repo already has TypeScript strict mode enabled, this might be redundant

5. 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. It represents a consistent style guideline that should be enforced repo-wide to maintain code consistency. The pattern is clear and actionable, and documenting it in AGENTS.md will help both human reviewers and AI agents apply this rule consistently across the codebase.
• Alternatives considered: path_scoped_rule: Could be scoped to packages/openapi/** and packages/tests/** if this convention only applies to test files, but the pattern suggests it is a repo-wide preference.; none: If this is already documented in existing style guides or linting rules, it may not need additional preservation.

6. Avoid broad eslint-disable comments and console usage in packages/** modules; use explicit logging mechanisms instead. (target: path_scoped_rule, confidence: 0.85)

• File: .claude/rules/avoid-broad-eslint-disable-comments-and-console-us.instructions.md
• Evidence: #7296 packages/openapi/test/scripts/codegen.ts, #7242 packages/openapi/src/generate.ts
• Reasoning: Both examples occur in packages/** paths where no-console is enforced. The pattern is about enforcing a specific linting rule across a path scope rather than a one-off code issue. This is a path-scoped convention that should be documented to prevent future violations.
• Alternatives considered: agents: Could be a repo-wide convention if console restrictions apply beyond packages/**, but evidence suggests it's path-specific.; adr: Could document the architectural decision to restrict console logging in library modules, but the primary value is the enforcement rule itself.

7. Core error metadata must be kept separate from user-declared payload data to prevent runtime desynchronization in tRPC error handling. (target: adr, confidence: 0.85)

• File: docs/adr/001-core-error-metadata-must-be-kept-separate-from-use.md
• Evidence: #7279 packages/server/src/unstable-core-do-not-import/error/TRPCDeclaredError.ts, #7279 packages/server/src/unstable-core-do-not-import/error/TRPCDeclaredError.ts, #7279 packages/server/src/adapters/ws.ts
• Reasoning: This pattern describes the architectural rationale behind a critical design decision: why error metadata (code, cause, name, stack) must not be overwritten by user payload. The comments explain the 'why' (preventing desync between runtime error state and declared shape) rather than just the 'what' (don't use Object.assign). This is a trade-off decision about error object design that future maintainers need to understand to avoid regressions.
• Alternatives considered: path_scoped_rule: Could be scoped to packages/server/src/unstable-core-do-not-import/error/ since it's specific to TRPCDeclaredError implementation; agents: Could be a general coding convention about not mutating error objects, but the pattern is too specific to tRPC's error architecture

8. Package.json bin entries must include bin/ directory in files array and ensure the referenced script exists. (target: path_scoped_rule, confidence: 0.85)

• File: .claude/rules/packagejson-bin-entries-must-include-bin-directory.instructions.md
• Evidence: #7252 packages/next/package.json, #7252 packages/server/package.json
• Reasoning: This is a repeated structural issue across multiple packages in the monorepo where bin entries are declared but the bin/ directory is not included in the files allowlist, causing broken CLI entrypoints on installation. It's specific to package.json configuration patterns and applies to all packages that declare bin entries.
• Alternatives considered: agents: Could be a cross-cutting convention if all packages should follow this pattern, but it's more of a structural validation rule specific to package.json files.; test: Could be enforced as a test that validates bin entries exist and are included in files array, but the pattern is about configuration correctness rather than runtime behavior.

9. Multiple @trpc/* packages should not expose generic binary names like 'intent' in their bin field, as this causes node_modules/.bin collisions and breaks installations; use namespaced names (e.g., trpc-intent) or avoid re-exporting. (target: adr, confidence: 0.85)

• File: docs/adr/002-multiple-trpc-packages-should-not-expose-generic-b.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 fundamentally an architectural decision about how to structure CLI entry points across a monorepo. The comments explain both the immediate problem (missing files, collisions) and the underlying rationale (namespace pollution, shadowing real binaries). This is a design pattern that should be documented as a decision for future package additions to the monorepo, not just a one-off fix.
• Alternatives considered: path_scoped_rule: Could be a rule scoped to packages/*/package.json to enforce namespaced binary names, but the decision rationale (why namespacing matters) is more important than the mechanical rule.; agents: Could be added to coding guidelines if this is a cross-cutting convention, but it's specific enough to package.json structure that an ADR better captures the trade-offs.

10. 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.

11. Package.json bin entries must reference executable files that actually exist in the package directory, or publishing will create broken executables on install. (target: path_scoped_rule, confidence: 0.85)

• File: .claude/rules/packagejson-bin-entries-must-reference-executable.instructions.md
• Evidence: #7252 packages/tanstack-react-query/package.json, #7252 packages/next/package.json
• Reasoning: This is a repeated validation rule specific to package.json files in monorepo packages. The pattern appears in multiple packages (tanstack-react-query, next) and describes a concrete, testable constraint that should be enforced across all package directories to prevent broken installations.
• Alternatives considered: test: This could be a runtime/installation test that verifies all bin entries reference existing files before publishing; agents: Could be a general instruction for all package.json modifications, though it's more specific to bin field validation

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.