Merge upstream

.agents/skills/minimizing-ty-ecosystem-changes/SKILL.md

@@ -15,14 +15,16 @@ description: Use when a user says "minimize this ty ecosystem change", "reproduc
 
 Start each investigation from fresh artifacts. Do not trust retained memories, previous minimizations, current upstream project state, or the helper script's default lockfile.
 
+Prefix every direct or indirect `gh` invocation with `GH_TELEMETRY=false`; each Codex tool call may start a new shell.
+
 ## Collect Exact-Run Metadata
 
-If a primary agent supplied an existing run-metadata manifest, verify that its run ID and attempt match the frozen report and that it contains each assigned project. Reuse the manifest without modifying it.
+If the primary agent supplied an immutable `TY_ECOSYSTEM_RUN_METADATA` manifest, verify that its run ID and attempt match the frozen report and that it contains each assigned project. All subagents reuse the same read-only manifest; never modify it or generate another shared manifest.
 
-Otherwise, run the bundled helper with the Actions run ID or URL, matching attempt, and every affected mypy-primer project name:
+Otherwise, run the bundled helper once with the Actions run ID or URL, matching attempt, and every affected mypy-primer project name:
 
 ```bash
-scripts/collect_ty_ecosystem_run_metadata.py \
+GH_TELEMETRY=false uv run --script scripts/collect_ty_ecosystem_run_metadata.py \
   <actions-run> <project-name>... \
   --attempt <actions-attempt> \
   --output target/ty-ecosystem-run.json
@@ -34,36 +36,43 @@ The current workflow splits compilation into `Build ty (base)` and `Build ty (pr
 
 ## Prepare ty
 
-If a primary agent supplied freshly copied base and PR profiling binaries plus the PR ecosystem config, preserve their absolute paths as `TY_ECOSYSTEM_BASE_BINARY` and `TY_ECOSYSTEM_PR_BINARY`, verify they exist, and reuse them. Do not rebuild those binaries, switch shared Ruff refs, or overwrite the shared artifacts. An agent may build an exact-revision debug binary on demand to identify an ambiguous internal type, using an isolated worktree if necessary; the profiling binaries remain the behavioral oracle.
+If a primary agent supplied freshly copied base and PR profiling binaries plus the PR ecosystem config, preserve their absolute paths as `TY_ECOSYSTEM_BASE_BINARY` and `TY_ECOSYSTEM_PR_BINARY`, verify they exist, and reuse them. Do not rebuild those binaries, switch shared Ruff refs, or overwrite the shared artifacts. If an exact-revision debug binary is needed to identify an ambiguous internal type, request it from the primary agent; the profiling binaries remain the behavioral oracle.
 
-Otherwise, require a clean working tree, copy `.github/ty-ecosystem.toml` from the PR revision, and build ty on the manifest's merge base and PR revision:
+Otherwise, require a clean working tree, remember its original ref, and build both exact revisions before assigning any subagent work. Reuse the checkout's existing Cargo target directory, copy the profiling binaries and PR ecosystem config to `target/ty-ecosystem-bins`, and restore the original ref when finished:
 
 Fetch the PR revision explicitly because pull-request runs usually use a synthetic GitHub merge commit that a normal clone does not contain:
 
 ```bash
 set -euo pipefail
 
 test -z "$(git status --short)" || { git status --short; exit 1; }
-git fetch origin <pr-revision>
+original_ref="$(git symbolic-ref --quiet --short HEAD || git rev-parse HEAD)"
+GH_TELEMETRY=false git fetch https://github.com/astral-sh/ruff.git <pr-revision>
 mkdir -p target/ty-ecosystem-bins
+trap 'git checkout "$original_ref"' EXIT
+
+artifact_dir="$PWD/target/ty-ecosystem-bins"
+build_target_dir="${CARGO_TARGET_DIR:-target}"
 export CARGO_PROFILE_PROFILING_DEBUG=line-tables-only
 
-git checkout <merge-base>
+git checkout --detach <merge-base>
 cargo build --package ty --profile profiling
-cp target/profiling/ty target/ty-ecosystem-bins/ty-base
+cp "$build_target_dir/profiling/ty" "$artifact_dir/ty-base"
 
-git checkout <pr-revision>
-cp .github/ty-ecosystem.toml target/ty-ecosystem-bins/ty-ecosystem.toml
+git checkout --detach <pr-revision>
+cp .github/ty-ecosystem.toml "$artifact_dir/ty-ecosystem.toml"
 cargo build --package ty --profile profiling
-cp target/profiling/ty target/ty-ecosystem-bins/ty-pr
+cp "$build_target_dir/profiling/ty" "$artifact_dir/ty-pr"
 ```
 
+After restoring the original ref, inspect vendored definitions and Rust implementations with `git -C <ruff-checkout> show <exact-revision>:<repository-relative-path>`, selecting the merge-base or PR revision from the immutable manifest. Never assume working-tree files match either analyzed binary or switch the shared checkout's ref.
+
 ## Reproduce
 
-Create a unique temporary directory for each project and use its absolute path. Read its Python version and the pinned mypy-primer revision from the manifest. Obtain the project revision from the `/blob/<commit>/` component of the original diagnostic's source permalink, and check that links for the same project agree. If no diagnostic permalink exists, inspect the matching diagnostics shard or Actions logs; if the exact revision cannot be recovered, explicitly report that limitation. Then bypass the adjacent script lockfile:
+Create a unique temporary directory for each project and use its absolute path. Read its Python version and the pinned mypy-primer revision from the shared manifest. Obtain the project revision from the `/blob/<commit>/` component of the original diagnostic's source permalink, and check that links for the same project agree. If no diagnostic permalink exists, inspect the matching diagnostics shard or Actions logs; if the exact revision cannot be recovered, explicitly report that limitation. Then bypass the adjacent script lockfile:
 
 ```bash
-uv run \
+GH_TELEMETRY=false uv run \
   --python <project-python> \
   --with "mypy-primer @ git+https://github.com/hauntsaninja/mypy_primer@<mypy-primer-revision>" \
   --no-project \
@@ -73,7 +82,7 @@ uv run \
   --exclude-newer <EXCLUDE_NEWER>
 ```
 
-Use the ecosystem config as user-level configuration, matching CI without replacing project-level config discovery, and re-export `XDG_CONFIG_HOME` in each new shell. If a primary agent supplied `TY_ECOSYSTEM_CONFIG_HOME`, reuse its installed config without modifying it; otherwise, install the copied config locally. Read the project's `strict` or `non-strict` label from the frozen detailed report, or its `strict_settings` value from the matching diagnostics shard. Preserve that mode when running either binary:
+Use the ecosystem config as user-level configuration, matching CI without replacing project-level config discovery, and re-export `XDG_CONFIG_HOME` and `RUST_BACKTRACE=1` in each new shell. If a primary agent supplied `TY_ECOSYSTEM_CONFIG_HOME`, reuse its installed config without modifying it; otherwise, install the copied config locally. Read the project's `strict` or `non-strict` label from the frozen detailed report, or its `strict_settings` value from the matching diagnostics shard. Preserve that mode when running either binary:
 
 ```bash
 if [[ -n "${TY_ECOSYSTEM_CONFIG_HOME:-}" ]]; then
@@ -85,6 +94,7 @@ else
   cp "$PWD/target/ty-ecosystem-bins/ty-ecosystem.toml" "$XDG_CONFIG_HOME/ty/ty.toml"
 fi
 unset TY_CONFIG_FILE
+export RUST_BACKTRACE=1
 
 project_dir="<absolute-temporary-directory>"
 ty_base="${TY_ECOSYSTEM_BASE_BINARY:-$PWD/target/ty-ecosystem-bins/ty-base}"
@@ -116,16 +126,18 @@ pr_exit_status=0
 run_ecosystem_ty || pr_exit_status=$?
 ```
 
-Confirm the detailed report's difference exactly, including duplicate diagnostics and both exit statuses. Ordinary diagnostics can produce exit status 1; do not mistake that for a failed reproduction.
+Confirm the detailed report's difference exactly, including duplicate diagnostics and both exit statuses. When reproducing an intermittent severe failure, repeat each side using its reported run count. Ordinary diagnostics can produce exit status 1; do not mistake that for a failed reproduction. For panics, identify the stable fingerprint by comparing the Rust panic site or decisive causal frame and panic payload; ignore checked Python-file paths and incidental backtrace differences.
 
 ## Minimize
 
-Reduce the reproduced project toward a self-contained single-file reproducer with minimal code and dependencies. A reduction is trivial only when the difference already occurs in one self-contained file and can be preserved solely by deleting obviously unrelated code. Multiple files, imports or dependencies, inlining, replacing language constructs, ambiguous types such as `@Todo`, or an uncertain cause make a reduction nontrivial. Before attempting any nontrivial reduction, read and follow [references/advanced-minimization.md](references/advanced-minimization.md). If in doubt, treat the reduction as nontrivial.
+The target is a fully minimized, provenance-preserving reproducer: preferably one self-contained file, with no avoidable third-party or standard-library imports and no unnecessary definitions, annotations, branches, or advanced language features. Retain a third-party import only if identified ty behavior depends on that library's identity or third-party search-path classification.
+
+Before minimizing any ecosystem change, read and follow [references/advanced-minimization.md](references/advanced-minimization.md). Exhaust its complete reduction loop, including third-party dependency and standard-library inlining, and retain an import only after verifying that neither removing it nor inlining its definitions preserves the underlying behavior.
 
-Matching diagnostics or displayed types do not establish a shared cause. When the output is ambiguous, identify the original and minimized triggers using exact-revision debug output, a targeted `reveal_type`, or the producing Rust call site.
+Matching diagnostics or displayed types do not establish a shared cause. When the output is ambiguous, identify and compare the original and minimized triggers using exact-revision debug output, a targeted `reveal_type`, or the producing Rust call site from the matching analyzed revision.
 
-Record the original source permalink, accepted reductions, both binaries' results, and any causal fingerprint. If source provenance or a matching cause cannot be established, return the original project excerpt explicitly marked as unminimized.
+A minimization is complete only when a verified reduction chain connects the reproducer to the original ecosystem entry and an exhaustive pass finds no further reduction. If a genuine external blocker prevents completion, report the blocker and identify the minimization as incomplete; an original source excerpt is not a successfully minimized result.
 
 ## Return
 
-Provide the original permalinked report entry, exact base and PR behavior, minimal code, full diagnostic messages and error codes, and the manifest/commands needed to reproduce it. When called from the summary workflow, return import-audit and reduction notes separately from report-ready Markdown.
+Provide the original permalinked report entry, exact base and PR behavior, minimal code, full diagnostic messages and error codes or the panic fingerprint, and the manifest/commands needed to reproduce it. When called from the summary workflow, return import-audit and reduction notes separately from report-ready Markdown.

.agents/skills/minimizing-ty-ecosystem-changes/references/advanced-minimization.md

@@ -4,7 +4,7 @@ Use this reference after the reported difference reproduces against the copied b
 
 ## Target
 
-Prefer a single-file reproducer with no third-party imports, few definitions, and the least complex typing or language features that still demonstrate the difference. Keep special modules such as `typing`, `abc`, `enum`, `types`, and `typing_extensions` only when removing them changes the behavior.
+Prefer a single-file reproducer with no avoidable third-party imports, few definitions, and the least complex typing or language features that still demonstrate the difference. Keep special modules such as `typing`, `abc`, `enum`, `types`, and `typing_extensions` only when neither removing them nor inlining their definitions preserves the behavior; retain a third-party import only after identifying ty behavior that depends on that library's identity or third-party search-path classification.
 
 ## Reduction Loop
 
@@ -13,16 +13,16 @@ Work systematically from the reproduced project. NEVER skip ahead to an explanat
 1. Delete unrelated files.
 2. Remove imports, definitions, decorators, annotations, statements, and branches.
 3. Inline first-party definitions into the reproducer.
-4. For each required third-party dependency, copy the entire installed dependency into the source tree as first-party code, including every package directory and module it provides. Do this before attempting to minimize any part of the dependency. Adjust imports, verify that the difference still reproduces with the complete copy, and only then begin deleting files or definitions from it. Never start by copying only apparently relevant files or definitions. If cloning a dependency is unavoidable, use the exact installed revision or version and copy the complete dependency into the source tree before reducing it.
-5. Inline the relevant standard-library definitions from `crates/ty_vendored`, which is ty's source of truth for stdlib types.
+4. For each required third-party dependency, copy the entire installed dependency into the source tree as first-party code, including every package directory and module it provides. Do this before attempting to minimize any part of the dependency. Adjust imports, verify that the difference still reproduces with the complete copy, and only then begin deleting files or definitions from it. If the complete copy changes the behavior because ty special-cases that library or distinguishes first-party from third-party search paths, identify the relevant ty implementation at the matching analyzed Ruff revision before retaining the original import. Never start by copying only apparently relevant files or definitions. If cloning a dependency is unavoidable, use the exact installed revision or version and copy the complete dependency into the source tree before reducing it.
+5. Inline the relevant standard-library definitions from the analyzed revision of `crates/ty_vendored`, using `git -C <ruff-checkout> show <exact-revision>:crates/ty_vendored/<path>`; compare the merge-base and PR definitions when they differ.
 6. Replace complex constructs with simpler equivalents, such as removing a walrus expression or replacing a protocol when the difference survives.
 
 Repeat the full loop until an exhaustive pass through every stage finds no further reduction that preserves the difference. Do not stop merely because the likely cause is understood or the reproducer is already small.
 
 ## Final Audit
 
-Attempt to remove every remaining import and inline every remaining third-party definition. Record why any surviving import is essential. Keep these notes as working evidence; the caller decides whether they belong in its final artifact.
+Attempt to remove every remaining import and inline its definitions, including remaining third-party and standard-library definitions. Retain an import only after verifying that neither removal nor inlining preserves the underlying behavior. For a third-party import, additionally verify that its module identity or third-party search-path classification is essential and identify the relevant ty implementation. Convenience, familiar APIs, matching class names, or preserving the diagnostic's module spelling do not justify keeping an import. Record why any surviving import is essential and, for a third-party import, where ty implements the relevant behavior. Keep these notes as working evidence; the caller decides whether they belong in its final artifact.
 
-Verify that the recorded reduction chain connects the final reproducer to the original ecosystem entry and, when diagnostic output is ambiguous, preserves the original causal fingerprint. If either check fails, return the original project excerpt as unminimized instead of substituting an unrelated example.
+Verify that the recorded reduction chain connects the final reproducer to the original ecosystem entry and, when diagnostic output is ambiguous, preserves the original causal fingerprint. If a required check fails, continue investigating; if a genuine external blocker prevents completion, report the blocker and mark the minimization as incomplete instead of presenting an unrelated example or original excerpt as a minimized result.
 
 Delete transient project and dependency copies after the investigation.