Derive the application comparison scope from the change when --scope is omitted (#875)

[pengfei-threemoonslab]

Summary

Closes #875. Without --scope, diff --application now derives the comparison scope from the change instead of comparing the repository root.

Neither obvious scope works for someone reviewing a PR in an unfamiliar repository:

• The repository root is partial whenever any file anywhere uses another framework.
• The changed directory often holds no agent. On feat: Gmail API integration mezgoodle/Vesta#58, the PR changes backend/app/services/ and the agents live in backend/app/agents/, so --scope backend/app/services answers not_established.

What changed

Relating the change to agents. Each changed Python file is related to the OpenAI Agents SDK and Google ADK agent files that import it, or that it imports, within six import hops, on each side of the change.

• A package's __init__.py on the way counts, and so does a literal importlib.import_module(...).
• An agent file is one that does any of these:
  • constructs an agent class under any name it is imported as;
  • subclasses an agent class;
  • copies an agent with capabilities of its own;
  • changes an agent's capabilities after construction, counted with fix(diff --application): an unobserved agent is not "no change" (#876) #880's own _capability_changes predicate, so the scope and the reader agree;
  • builds its agent through another file's factory.
• A test file is related only when an agent imports it, and it never widens a scope.

Choosing the scope. Each related group is compared in the outermost package that holds the change, its agents and what they import. Vesta#58 derives backend/app.

• Independent applications in a monorepo are separate comparisons under comparisons, never the root.
• A relocated application is one comparison.
• A change that touches no supported agent is an explicit not_established answer naming the files considered.

Never a silent compared. Each of these is named in scope_selection.limits and makes the result partial:

• a changed file not related to a module that builds an agent, with why;
• a changed link or submodule;
• an agent outside the compared scopes that reaches the change;
• a consumer: a module that imports the change and a builder that builds on request, and builds, copies or rewires an agent, calls the repository's code with its own arguments, or sets its module state. It is exempt only when one compared scope holds all three.
• any bound reached: 6 hops, 2000 files to relate, 5000 files or 64 MB to find agent files.

Surface. --json records scope_selection: the mode (derived or explicit), the scopes, why, and each scope's relations. An explicit --scope always wins, --scope . keeps the root, and --base-scope needs --scope. Everything is read from the two commits' objects and never run. Partial clones are refused with the established hydration message.

Evidence (pinned 48-PR application corpus)

scope	rows established
derived (this PR)	296
repository root	296
common parent of the changed wiring files	18

• The derived scope is narrower than the root for 20 PRs.
• For 7 PRs it answers that the change touches no supported agent; the root reported unrelated agents there.
• Median run time is 13 s, the same as the root.

Review

Twelve adversarial review rounds, each with fixtures and a prior-engine comparison. Every fix has a test in tests/test_application_scope.py that fails on the commit before it.

Rounds 6–7 settled the design: a reverse import closure that walks through agent files, and builder qualification. Two rules were tried and reverted after regressing true consumers:

• skipping entry scripts whose imports are all in scope, which dropped FEDOT.MAS's examples;
• stopping the closure at agent files.

Round 11, after rebasing onto #880, replaced this module's own rewire predicate with #880's _capability_changes. A slice store into an agent's tools, or a change made through a handle to that list, now counts for the scope as it does for the reader.

• On the corpus, only alliance-genome Build(deps-dev): Bump platformdirs from 4.11.7 to 4.11.11 #842 and Route an enabled in-repository plugin's hook at a non-registry path to review (#809) #860 move. Each gains one "unrelated changed file" entry, and both were already partial. Corpus time went from 291 s to 278 s.
• Across 156 fixtures, only the four new round-11 fixtures move, each from compared to partial.

Round 12 found no P0/P1. It checked:

• 7,570 corpus files through the new predicate, with no exception and none over 1 s;
• 27 adversarial syntax snippets;
• every earlier round's fixtures, with no regression.

Known, non-blocking:

• fix(diff --application): an unobserved agent is not "no change" (#876) #880's census predicate treats rebinding a local handle (t = agent.tools; t = [...]) as a change. That adds the alliance-genome entry above.
• fix(diff --application): an unobserved agent is not "no change" (#876) #880's census does not read tuple or list targets (bot.tools, bot.name = ...), for/with attribute targets, or walrus/global handles. The derivation and the reader agree on these cases, since they now share one predicate. That belongs in a follow-up on fix(diff --application): an unobserved agent is not "no change" (#876) #880.
• Carried from earlier rounds, each named as a limit rather than hidden: noise from entry scripts that run an app's agents (pastoriza's probar_conversacion.py), and the unrelated-file limit on 21 of 48 corpus repos.

Verification

• Full suite after rebasing onto Read a Google ADK tool a local factory builds, and a tools list built in the agent's function (#865) #903 (pytest -n 8): 14,389 passed, 7 skipped. The only failures are the two environmental test_check_unmodelled_host_config_keys.py[local_settings_enabled_plugins-*] cases, which fail the same way on untouched main. Three Google ADK: trace bounded FunctionTool factories into agent tool bindings #865 cases that change only a README now pin --scope . (a README-only change derives no scope).
• Carries ci: balance test shards by measured time per file #905's shard-balance commit so CI fits its budget; it drops out on rebase once ci: balance test shards by measured time per file #905 merges.
• ruff check . passes.

🤖 Generated with Claude Code

[pengfei-threemoonslab]

The suite (3) cancellation was a shard-balance timeout, not a test failure: the three shards were balanced by test count, and this PR's new test file reshuffled 298 of 363 files, putting shards 1 and 3 at the 15-minute cap. The fix is #905 (balance shards by measured time per file), cherry-picked here as 5122984 so this PR's CI can pass now; it drops out on rebase once #905 merges.

🤖 Generated with Claude Code