Skip to content

Commit f10d0d3

Browse files
fix(init): resolve constructors and bindings, or decline
Addresses the six P1 and three P2 findings from the third review. Each reproduced against f0aab48 first, and each fix has a test that fails without it. Four of the six P1s were one gap: the model recorded assignments and trusted spellings, so any binding it could not see — and any name it could not attribute — produced a confident, wrong identity. **Constructors resolve through their bindings.** Recognition matched the terminal spelling, so a local `def Agent(...)` supplied `FabricatedRoot` while the real `RealApp(root_agent=RealAgent(name="ActualRoot"))` went unseen. The reaching binding decides instead: an import of a framework class under any alias is a constructor, a spelling bound to a local `def`/`class` is not. Aliases are only honoured from framework modules — `from mypkg.agents import Agent as Wrapped` renames somebody else's class, and my first attempt widened recognition to it. My own test caught that. **Every binding form is modelled, not just assignments.** `del`, `class`, `except … as`, and `case` all rebind or unbind a name without producing a Store `Name`, so a retired `root_agent` kept its role. `from x import *` binds an unknowable set, so a file carrying one can prove nothing about any of its names. **`global`/`nonlocal` are declarations, not writes.** Recorded as a local write, a `global root_agent` store was invisible to module-level resolution, so a stale `OldRoot` kept the role while the runtime exposed `NewRoot`. Writes are now routed to the scope they actually bind, and marked conditional: whether the function runs, and when relative to the module body, is not something the file says. **Enclosing writes are not ordered by the nested reference's line.** A function body executes when called, not where written, so a module-level rebinding *below* a nested reference still happens before the call. Only a single unconditional binding is provable in an enclosing scope. **Conditional provenance reaches inline roots.** `agent_calls` kept only `(call, scope)`, so two `App(root_agent=Agent(...))` constructions in `if`/`else` were both selectable roots and the first won. **The detector keeps the logical path of contained symlinks.** Returning the resolved path renamed the entry: with `agent.py -> source.txt` the `.py` suffix disappeared, the script reported zero Python files and `is_agent_project: false` where the CLI reported an agent project. That is the go/no-go verdict, not just the ranking. P2s: `DetectResult(agent_name_candidates=[NameCandidate(...)])` works again — both the instance and the legacy dict are upgraded at the model boundary with the rule that decided selection before ranking existed, instead of raising or silently landing on `selectable: false`. `tests.py`/`test.py` count as test code. The non-Git fallback walk has a documented ceiling that raises rather than truncating, because a partial inventory is a partial scope verdict. Two behaviour changes worth calling out, both consequences of resolving provenance rather than spellings: - `samples/_anti_patterns/dynamic_toolset_factory` defines a local `class Agent`; its literal is no longer offered as a name candidate. The fixture comment and README documented the old behaviour and are updated. - `test_an_unrelated_agent_class_does_not_define_a_project` (from #370) asserted the same literal stayed a "low-confidence name suggestion". It claimed a provenance it never had, and `init` could write it as the reviewed identity, so the assertion is inverted. The test's actual subject — that the module does not define a *project* — is unchanged. All of it is mirrored in `tools/shipgate-detect.py` and verified by byte parity across every reproducer. Sample selections are unchanged, and both originally reported repositories still resolve correctly. Co-Authored-By: Claude Opus 5 <[email protected]>
1 parent f0aab48 commit f10d0d3

11 files changed

Lines changed: 1054 additions & 153 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,6 +62,23 @@
6262
which one Python picks depends on `sys.path`, so the identity stays
6363
unresolved.
6464

65+
Provenance is resolved, never assumed. `Agent`/`LlmAgent`/`App` are read
66+
through the binding that reaches them, so a constructor imported under an
67+
alias counts and one shadowed by a local `def`/`class` does not — matching
68+
a terminal spelling let a decoy `def Agent(...)` supply a fabricated
69+
identity while the real aliased root went unseen. Every binding form is
70+
modelled, not just assignments: `del`, `class`, `except … as`, `case`, and
71+
a `global`/`nonlocal` store routed to the scope it actually rebinds all
72+
retire the agent a name used to hold, and a file carrying
73+
`from x import *` can prove nothing about any of its names. Lookups into
74+
an enclosing or module scope no longer compare writes against the nested
75+
reference's line number: a function body does not execute where it is
76+
written, so a module-level rebinding *below* a nested reference still
77+
happens before the call, and only a single unconditional binding there is
78+
provable. An `App(root_agent=Agent(…))` built inside a branch is
79+
unresolved rather than whichever arm came first, and `tests.py` / `test.py`
80+
now count as test code like every other conventional test module.
81+
6582
Origin now dominates the score rather than competing with it. The
6683
documented contract is that product code outranks test code, but additive
6784
scoring let a test fixture that builds an `App(root_agent=…)` outrank a
@@ -86,6 +103,22 @@
86103
invisible to `init`, so walking it anyway let the script name an agent
87104
`init` would never write; a symlink escaping the workspace both
88105
contributed a name and leaked its outside absolute path into the output.
106+
Two further detector fixes: a contained symlink keeps its *logical* path,
107+
because resolving `agent.py -> source.txt` renamed the entry, dropped the
108+
`.py` suffix, and reported zero Python files where the CLI reported an
109+
agent project — the go/no-go verdict, not just the ranking. And the
110+
non-Git fallback walk now has a documented ceiling that *raises* rather
111+
than truncating, so a downloaded tree of unrelated assets cannot consume
112+
unbounded time and memory before detection sees a single source file.
113+
114+
`DetectResult(agent_name_candidates=[NameCandidate(...)])` keeps working.
115+
`NameCandidate` is a public export and was the declared element type
116+
before ranking existed; narrowing the annotation turned working calls into
117+
a `ValidationError`, and a legacy dict parsed but silently landed on
118+
`selectable: false`, changing which name `init` writes. Both are now
119+
upgraded at the model boundary using the rule that decided selection
120+
before this change, so old callers keep the behaviour they had.
121+
89122
Its file bound also moved from the whole inventory onto Python parses, so
90123
an asset-heavy repository can no longer exhaust the budget before the walk
91124
reaches any source. Git's output is read incrementally against that bound

‎docs/agent-recipes.md‎

Lines changed: 16 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -112,15 +112,22 @@ Consume the response to decide whether to proceed. Key fields:
112112
visible in the output rather than silently changing what the manifest
113113
claims. `name=` values that come from a module constant or an
114114
`os.environ.get("…", "…")` default in the same package are resolved
115-
statically (one hop, no code executed) and say so in `rationale[]`. That
116-
resolution is deliberately conservative — it reads Python's binding rules
117-
or declines. A symbol bound more than once anywhere in the file, one
118-
assigned under an `if`/`try`/loop, one whose import could resolve to two
119-
different in-workspace modules, and an `os.getenv` spelling that is not a
120-
provably unshadowed stdlib import are all left unresolved rather than
121-
guessed. A reference resolves against enclosing function scopes before the
122-
module, and a `root_agent` later rebound to something that is not an agent
123-
construction retires the earlier one rather than keeping it.
115+
statically (one hop, no code executed) and say so in `rationale[]`.
116+
117+
All of this reads Python's binding rules or declines — a spelling is never
118+
taken as provenance. `Agent`/`LlmAgent`/`App` are resolved through the
119+
binding that reaches them, so a framework constructor imported under an
120+
alias is recognised and one shadowed by a local `def`/`class` is not.
121+
Left unresolved rather than guessed: a symbol bound more than once
122+
anywhere in the file; one assigned under an `if`/`try`/loop; one rebound
123+
in an enclosing scope (a function body executes when it is called, not
124+
where it is written);
125+
one whose import could resolve to two different in-workspace modules; an
126+
`os.getenv` spelling that is not a provably unshadowed stdlib import; and
127+
anything at all in a file carrying `from x import *`. Bindings that carry
128+
no assignment count too — `del`, `class`, `except … as`, `case`, and a
129+
`global`/`nonlocal` store routed to another scope all retire the agent a
130+
name used to hold.
124131
- `project_name_candidates[]` — `{value, source}` only. Project names have
125132
no hierarchy to rank, so they carry none of the fields above. The
126133
`pyproject` source seeds `project.name`, never `agent.name`.

‎llms-full.txt‎

Lines changed: 16 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -875,15 +875,22 @@ Consume the response to decide whether to proceed. Key fields:
875875
visible in the output rather than silently changing what the manifest
876876
claims. `name=` values that come from a module constant or an
877877
`os.environ.get("…", "…")` default in the same package are resolved
878-
statically (one hop, no code executed) and say so in `rationale[]`. That
879-
resolution is deliberately conservative — it reads Python's binding rules
880-
or declines. A symbol bound more than once anywhere in the file, one
881-
assigned under an `if`/`try`/loop, one whose import could resolve to two
882-
different in-workspace modules, and an `os.getenv` spelling that is not a
883-
provably unshadowed stdlib import are all left unresolved rather than
884-
guessed. A reference resolves against enclosing function scopes before the
885-
module, and a `root_agent` later rebound to something that is not an agent
886-
construction retires the earlier one rather than keeping it.
878+
statically (one hop, no code executed) and say so in `rationale[]`.
879+
880+
All of this reads Python's binding rules or declines — a spelling is never
881+
taken as provenance. `Agent`/`LlmAgent`/`App` are resolved through the
882+
binding that reaches them, so a framework constructor imported under an
883+
alias is recognised and one shadowed by a local `def`/`class` is not.
884+
Left unresolved rather than guessed: a symbol bound more than once
885+
anywhere in the file; one assigned under an `if`/`try`/loop; one rebound
886+
in an enclosing scope (a function body executes when it is called, not
887+
where it is written);
888+
one whose import could resolve to two different in-workspace modules; an
889+
`os.getenv` spelling that is not a provably unshadowed stdlib import; and
890+
anything at all in a file carrying `from x import *`. Bindings that carry
891+
no assignment count too — `del`, `class`, `except … as`, `case`, and a
892+
`global`/`nonlocal` store routed to another scope all retire the agent a
893+
name used to hold.
887894
- `project_name_candidates[]` — `{value, source}` only. Project names have
888895
no hierarchy to rank, so they carry none of the fields above. The
889896
`pyproject` source seeds `project.name`, never `agent.name`.

‎samples/_anti_patterns/dynamic_toolset_factory/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,6 @@ The agent-action-guide names the same recovery in its [`inventory` section](http
6767
## What you'll see
6868

6969
- `agents-shipgate doctor -c shipgate.yaml` reports `Total tools: 0` and surfaces `SHIP-DIAG-ZERO-TOOLS`. With `--json`, the payload includes `unresolved_sources: []` and `total_tools: 0`; the diagnostic's nested `next_actions[]` includes an edit recommendation to add an explicit MCP export, OpenAPI spec, or local tool inventory.
70-
- `agents-shipgate detect --json --workspace .` returns `is_agent_project: false` and `frameworks: []`. The fixture defines a local `class Agent` rather than importing `from agents import Agent`, so the AST walker sees no SDK import to detect. The `Agent(name="dynamic-toolset-agent")` call is still surfaced as an entry in `agent_name_candidates` (source: `Agent_name_literal`), but that's a weaker signal that doesn't flip `is_agent_project`. This is a deliberate detail of the fixture: anti-pattern samples shouldn't pretend to be real agent projects — they isolate one failure mode at a time, and the failure mode here is *inventory enumeration*, not *project detection*.
70+
- `agents-shipgate detect --json --workspace .` returns `is_agent_project: false` and `frameworks: []`. The fixture defines a local `class Agent` rather than importing `from agents import Agent`, so the AST walker sees no SDK import to detect. `agent_name_candidates` carries no `Agent_name_literal` entry either: name extraction resolves each callee through its binding, and a spelling bound to a local `class` in the same file is not a framework constructor — reading it as one is how a fabricated identity reaches a manifest. This is a deliberate detail of the fixture: anti-pattern samples shouldn't pretend to be real agent projects — they isolate one failure mode at a time, and the failure mode here is *inventory enumeration*, not *project detection*.
7171
- `report.json.findings[]` contains exactly one high-severity entry: `SHIP-INVENTORY-NOT-ENUMERABLE` with `tool_name: null`.
7272
- The Release Evidence Packet's §1 verdict is `REVIEW REQUIRED`; §2 shows `(no tools observed)`, and §9 lists the `SHIP-INVENTORY-NOT-ENUMERABLE` manual review item. §10 remains the standard "what this packet did NOT prove" section rather than a duplicate inventory summary.

‎samples/_anti_patterns/dynamic_toolset_factory/factory.py‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -48,10 +48,13 @@ def issue_refund(amount: int) -> dict:
4848
]
4949

5050

51-
# Pretend this is from `agents` (the OpenAI Agents SDK). The static
52-
# extractor sees `Agent(name="dynamic-toolset-agent")` and reports the
53-
# agent name candidate, but it can't follow the `tools=TOOLS` reference
54-
# back to the wrapped functions. Result: zero tools enumerated.
51+
# Pretend this is from `agents` (the OpenAI Agents SDK), but note that it
52+
# is a locally defined class, not an import. Name extraction resolves the
53+
# callee through its binding, so this `Agent` is *not* read as a framework
54+
# constructor and contributes no agent-name candidate. The failure this
55+
# fixture isolates is still the one below: nothing can follow the
56+
# `tools=TOOLS` reference back to the wrapped functions, so zero tools are
57+
# enumerated.
5558
class Agent:
5659
def __init__(self, name: str, tools: list) -> None:
5760
self.name = name

0 commit comments

Comments
 (0)