Skip to content

Commit f0aab48

Browse files
Merge main into agent-name ranking (#370 monorepo scope)
Both branches rewrote the same detection surface, so the conflicts were semantic rather than textual. The two features are orthogonal and now compose: #370 answers *which directory* one manifest describes, this branch answers *which agent* it names once the directory is settled. Resolutions that were more than "keep both": - `_PyFacts.agent_name_literals` (a `list[str]`) no longer exists on this branch; names are `_AgentNameEvidence` records that may hold a literal or a symbol needing cross-module resolution. #370's project scoping reads literals to group evidence by project, so it now goes through a `name_literals()` helper. Literals only, deliberately: a boundary is about *where* agents live, and a resolved constant is not per-file evidence. The same adaptation applies to `literals_by_path` in the zero-install detector, where the untranslated version raised `TypeError: unhashable type: 'dict'` on every workspace. - #370 kept a 5000-file inventory cap in the zero-install walk and worked around it by always collecting project markers, so a truncated inventory could not truncate the scope verdict. This branch removed that cap outright — the bound belongs on Python parses, not the inventory — and added the Git fast path, so the workaround is dead code: with no cap every marker is collected anyway. Took the uncapped, containment-checked walk and kept #370's reasoning in its docstring. - #370's script docstring claimed "No git-ls-files fast path; os.walk only", which this branch made false. Dropped that line; kept its `agent_scope` parity note. `init` now has two independent reasons to refuse to guess — an ambiguous manifest scope and an unresolvable agent identity — and they report separately. Verified across all eight reproducers: CLI verdicts unchanged, and byte parity with the standalone detector holds for both `agent_name_candidates` and `agent_scope`. Full suite green, ruff clean, compileall clean, llms-full.txt regenerated. Co-Authored-By: Claude Opus 5 <[email protected]>
2 parents 27e14fa + ec75e80 commit f0aab48

40 files changed

Lines changed: 3759 additions & 134 deletions

‎.cursor/rules/agents-shipgate.mdc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
description: Run Agents Shipgate as the deterministic merge gate for AI-generated agent capability changes.
33
globs:
44
- "shipgate.yaml"
5+
- "**/shipgate.yaml"
56
- "**/*openapi*.yaml"
67
- "**/*openapi*.yml"
78
- "**/*openapi*.json"

‎.pre-commit-hooks.yaml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@
5353
stages: [pre-commit, pre-push]
5454
files: |
5555
(?ix)^(
56-
shipgate\.yaml|
56+
(.*/)?shipgate\.yaml|
5757
.*tools.*\.json|
5858
.*mcp.*\.json|
5959
.*n8n.*\.json|
@@ -101,7 +101,7 @@
101101
stages: [pre-push]
102102
files: |
103103
(?ix)^(
104-
shipgate\.yaml|
104+
(.*/)?shipgate\.yaml|
105105
.*tools.*\.json|
106106
.*mcp.*\.json|
107107
.*n8n.*\.json|

‎AGENTS.md‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -233,7 +233,12 @@ agents-shipgate bootstrap --json
233233
`bootstrap` runs `detect → init --write --ci → scan --suggest-patches → apply-patches --confidence high` against the current workspace, stopping on the first non-recoverable error and emitting a structured per-step summary. Use it for first-time adoption; for ongoing CI keep using the GitHub Action. Flags: `--workspace`, `--confidence`, `--no-ci`, `--no-apply`, `--json`.
234234

235235
- **`detect`** — read-only; classifies the workspace. `is_agent_project: false`
236-
means stop early.
236+
means stop early. `agent_scope` says whether one manifest can describe this
237+
workspace at all: `"ambiguous"` means agents live in several self-contained
238+
projects (`agent_project_candidates[]` lists them, and the manifest belongs
239+
in one of them rather than at the workspace root); `"unknown"` means
240+
discovery was capped before it could tell, so raise `--max-python-files` or
241+
name the project directly.
237242
- **`init`** — auto-detects by default. `--ci` writes
238243
`.github/workflows/agents-shipgate.yml`; orthogonal to `--write`. Use
239244
`--minimal` for the pre-v0.6 CHANGE_ME-heavy template.
@@ -249,6 +254,19 @@ agents-shipgate bootstrap --json
249254
bundles under `.agents/skills/agents-shipgate/` and
250255
`.claude/skills/agents-shipgate/` respectively. Strict CI and baselines remain
251256
opt-in human decisions; generated CI stays advisory by default.
257+
`--write` **refuses** a workspace whose manifest scope is unresolved —
258+
`manifest_status: "refused_unresolved_scope"`, exit `2`, nothing written at
259+
all (no manifest, no workflow, no snippets, no `.gitignore` block) — rather
260+
than adopting the first `Agent(name=…)` literal it parsed for a manifest that
261+
would cover unrelated agents. That covers both `agent_scope` values that are
262+
not `"single"`. Re-run with `--workspace` pointed at one of
263+
`auto_detected.agent_project_candidates[].path` (the emitted
264+
`next_actions[]` commands carry the setup flags you passed);
265+
`--allow-unresolved-scope` overrides when one agent surface genuinely spans
266+
the workspace, and `--minimal` (which adopts no detected name or tool
267+
surface) is never scope-gated. With `--ci`, the workflow is written at the
268+
repository root with a repo-relative `config:` — GitHub loads workflows from
269+
nowhere else — so a scoped adoption still gets a gate that runs.
252270
- **`scan --suggest-patches`** — attaches Patch objects to every active
253271
finding. `Finding.patches` is absent without the flag.
254272
- **`apply-patches`** — file-grouped, dry-run by default. Containment-
@@ -349,6 +367,8 @@ One known gap in the Google ADK row: an edit that *modifies* a tools list on the
349367

350368
`prompts/` and `policies/` in that row match at any depth and case-insensitively: an edit under `services/foo/policies/` or `enterprise/lib/captain/Prompts/` routes exactly like a repo-root one. That is parity with the verifier, whose trust-root classification has always read those two surfaces as `**/policies/**` and `**/prompts/**` and has always tolerated the case variant a case-insensitive filesystem resolves to the canonical name. The catalog's `glob` and `none_match_glob` predicates match the same way, so a path cannot be a trust root to the verifier and a `no_match` to the router; the Tier B checks (`SHIP-VERIFY-POLICY-WEAKENED`, `SHIP-VERIFY-CI-GATE-REMOVED`, agent-instruction weakening, trigger-catalog drift) select their changed files the same way too, so a case variant cannot be a trust root in Tier A and invisible to the specialized check that carries the severity. `every_file_matches` is deliberately the exception and stays case-sensitive: it is the docs-only rule's own classifier, and `skip_shipgate` beats `run_shipgate`, so folding it would read `src/TEST_agent.py` — a production module on a case-sensitive filesystem — as a test file and skip a PR that adds a tool beside it. The rule is to fold the predicates that can only add evaluation, never the one that can subtract it. The three surfaces that copy this routing — the pre-commit `files:` regex, the `.cursor/rules/agents-shipgate.mdc` activation globs, and the documented copy-paste hook snippets — follow, so a nested governance edit also activates the host instructions and stages the local hook.
351369

370+
`shipgate.yaml` matches at any depth for the same reason. A monorepo keeps one manifest per project directory, so an edit to `services/refund/shipgate.yaml` — the file that declares that project's agent, purpose, and tool surface — routes exactly like a root-level one; a root-only rule reported it as `no_match`. A nested manifest is also an opt-in: `verify --preview` treats the changed project's own `shipgate.yaml` as the repo-already-adopted signal and routes verification to that manifest rather than to a root one governing a different boundary.
371+
352372
Two implicit triggers also fire even when no row above matches:
353373

354374
- **Repo already opted in (shipgate.yaml present in the workspace)** — run on every PR; the manifest's existence is the opt-in.

‎CHANGELOG.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,132 @@
9292
rather than buffered whole and measured afterwards, and overrunning it
9393
exits non-zero exactly as canonical discovery raises — falling back to a
9494
walk would do the work the bound exists to refuse.
95+
- **First adoption inside a monorepo no longer starts by writing the wrong
96+
manifest.** `verify --preview` routed setup to the workspace root, so on a
97+
repository holding many self-contained agent projects the command it handed
98+
back produced a manifest covering all of them: on `google/adk-samples` that
99+
was 252 `tool_sources` and an `agent.name` taken from the first of 160+
100+
`Agent(name=…)` literals, unrelated to the pull request under review. Nothing
101+
in the output said so — the JSON reported `manifest_status: "written"`,
102+
`is_agent_project: true`, `confidence: "high"`, and a *higher* framework
103+
score than the correct sub-directory — and the alignment layer that compares
104+
a declared purpose against the observed capability surface has nothing left
105+
to compare when one declaration covers many agents. The changed paths already
106+
answer the question, so preview now derives `--workspace` from them: each is
107+
attributed to the nearest directory at or above it carrying a project marker
108+
(`pyproject.toml`, `package.json`, `go.mod`, `Cargo.toml`, …), and the scope
109+
is that project when exactly one is claimed **and** every capability-bearing
110+
changed path was claimed by it. A capability path no project owns — a root
111+
`prompts/system.md` travelling with a change to `services/b` — vetoes the
112+
answer rather than being dropped, because "this change belongs to
113+
`services/b`" would then be a false statement about the diff. The workspace
114+
root is likewise left unchanged whenever the paths do not narrow it — a
115+
root-level change, or one spanning two projects, which narrows to *nothing*
116+
rather than to their common parent, because the parent of two projects is not
117+
itself a project. Documentation and tests cannot outvote code: when more than
118+
one project is claimed, the projects claimed *only* by documentation or test
119+
paths drop out, and the trigger catalog's own docs-only rule decides which
120+
paths those are so the two surfaces cannot drift. That leg is load-bearing —
121+
the reported PR edits `python/agents/README.md` one directory above the
122+
project it adds, and counting that README as a competing claim sends the
123+
answer straight back to the repository root. Base detection now runs in
124+
preview exactly as it does in `verify` (honoring `--no-base`), because the
125+
promoted adoption command is the bare `verify --preview --json`: without it
126+
the preview every first adoption runs evaluates an empty change set and
127+
nothing below it can fire. Markers are read from the working tree — what
128+
`init` will run against — so a preview of a head that is not the current
129+
checkout claims no scope at all rather than recommending a directory that
130+
depends on what happens to be checked out. When the changed project already
131+
carries its own `shipgate.yaml`, preview routes to `verify` **there**, ahead
132+
of any root manifest, which governs a different boundary; that also stops the
133+
next preview from looping against a manifest that now exists. A change
134+
spanning several projects routes to `detect` instead of to an `init` that
135+
would deterministically refuse.
136+
137+
`init --write` closes the same gap from the other side: a workspace whose
138+
manifest scope is unresolved reports
139+
`manifest_status: "refused_unresolved_scope"` (exit 2) with
140+
`auto_detected.agent_scope` and `agent_project_candidates[]`, rather than
141+
adopting the first agent name it parsed. Two things make a scope unresolved.
142+
`agent_scope: "ambiguous"` is agents in several self-contained projects —
143+
evidenced by everything `init` would turn into a manifest, so an
144+
OpenAPI-only or MCP-only project with no Python at all counts, as does a
145+
nested `shipgate.yaml` somebody already scoped by hand. `agent_scope:
146+
"unknown"` is discovery capped before it could tell: Python parsing stops at
147+
`--max-python-files`, and in a workspace with several project roots a
148+
"single project" verdict would just be whichever files were read first.
149+
Truncation alone is not enough to withhold an answer — a repository with one
150+
project root has nowhere for a second project to hide, so large
151+
single-project repositories keep their verdict and their working `init`. A
152+
refused run writes *nothing* — not the manifest, not the CI workflow, not the
153+
agent-instruction snippets, not the reports `.gitignore` block — so a
154+
workspace Shipgate declined to adopt carries no Shipgate edits into the diff.
155+
Rank 1 of the emitted recovery is deliberately not a command: promoting one
156+
candidate would make the same arbitrary pick the refusal exists to prevent,
157+
and the refused workspace itself is never offered back. The per-candidate
158+
commands repeat the setup flags the caller passed, so a recovery cannot
159+
silently complete with less than `--ci` or an agent-instruction selection
160+
asked for. `--minimal` adopts no detected name or tool surface and is
161+
unaffected; a repository that really is one agent surface across several
162+
projects passes `--allow-unresolved-scope`; and re-running `init --write
163+
--agent-instructions=…` on an adopted repository is untouched, because its
164+
scope was settled when its manifest was written.
165+
166+
Two surfaces around it were wrong in the same direction. `init --ci` scoped
167+
to a sub-directory wrote `<project>/.github/workflows/agents-shipgate.yml`,
168+
which GitHub never loads — a gate reported as written that could not run; the
169+
workflow now lands at the repository root with a `config:` naming the
170+
manifest relative to that root. And `TRIGGER-SHIPGATE-MANIFEST` matched
171+
`shipgate.yaml` only at the repository root, so an edit to
172+
`services/refund/shipgate.yaml` — the file that declares that project's
173+
agent, purpose, and tool surface — reported `no_match`; it now matches at any
174+
depth, as do the pre-commit `files:` regex and the Cursor activation globs
175+
that copy the catalog, and a nested manifest counts as the repo-already-opted-in
176+
signal. `tools/shipgate-detect.py` (`script_version` `0.3.0`) carries
177+
`agent_scope` and `agent_project_candidates[]` too, pinned against the CLI by
178+
the parity test: an agent that consults the zero-install path must not adopt
179+
a scope the CLI refuses.
180+
181+
Review found the routing could still be spent on evidence that did not
182+
support it, so three things changed shape. Preview now evaluates the same
183+
effective change set the full verifier does — committed range unioned with
184+
uncommitted and untracked work — because the command it emits runs against
185+
the working tree: an uncommitted-only capability change previously read as an
186+
empty diff, and an empty diff read as "nothing narrows the scope". "Scope not
187+
established" is now a state of its own rather than an absence: a head that is
188+
not checked out, a capability path no project claims, or a change spanning
189+
several projects each route to discovery or to human review, and never to
190+
initializing the repository root, which would turn "Shipgate could not tell"
191+
into a manifest for whichever agent the current checkout happens to hold.
192+
When the contested projects are already configured, each is its own gate and
193+
a human decides — a root manifest is not a substitute for either boundary.
194+
195+
Three more surfaces followed the same distinction. Reports now default to the
196+
workspace the caller named, so `verify --workspace apps/a` writes
197+
`apps/a/agents-shipgate-reports/` — the directory that project's managed
198+
`.gitignore` block actually covers, and one that two projects cannot
199+
overwrite for each other; an explicit `--out` still resolves against the
200+
repository root. `--ci` writes one workflow per gated manifest
201+
(`agents-shipgate-<project>.yml` beside the root's `agents-shipgate.yml`),
202+
because the action takes a single `config` scalar and one shared file gated
203+
whichever project initialized first while reporting a skip for the rest; that
204+
scalar is now YAML-quoted when the path needs it, so a directory named
205+
`apps/agent #1` no longer renders a comment. And the `trigger` command reads
206+
the nested-manifest opt-in through the same resolver preview uses, so
207+
`apps/a/README.md` beside `apps/a/shipgate.yaml` stops reporting a docs-only
208+
skip.
209+
210+
Detection got two corrections in opposite directions. A bare
211+
`requirements.txt` still is not a project boundary, but one sitting beside an
212+
agent is the only boundary that layout has — two sibling ADK agents were
213+
reported as one root scope, and `init` picked one of their names. And an
214+
`Agent(name=…)` literal only draws a boundary when its file carries a
215+
supported framework import: an unrelated module defining its own `Agent`
216+
class made a single-agent repository refuse. Those literals remain name
217+
suggestions. `tools/shipgate-detect.py` keeps its marker census complete
218+
rather than truncating it with the general file cap, so heavy filler no
219+
longer hides the projects it is supposed to find.
220+
([#363](https://github.com/ThreeMoonsLab/agents-shipgate/issues/363))
95221

96222
- **The recommended next command now runs where it was recommended.** Every
97223
emitted command was written as the console script the wheel installs

‎adoption-kits/claude-code-skill/.agents-shipgate-kit-metadata.json‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,10 @@
5656
"b5df3ae9ee09b2bfc62d2989673c592e28d866486f722e858f539c5b77285640",
5757
"53296f41b7c2bc8538555a4361707de8b990748b7a5d80ae4ce066af83af8fa7",
5858
"63dfb5f850c23009d5059a909bdd88bf35c57a77ab21a75aaa010f382945ef34",
59-
"514d8312f6edeed5007179bf6e7173da74cf526171da9ccf090fac9bb8f8f447"
59+
"514d8312f6edeed5007179bf6e7173da74cf526171da9ccf090fac9bb8f8f447",
60+
"44606ff86cc48c6532b5503a479a8a821874246b47b7abd54a23ffd280e0caba",
61+
"0f1ff58bb69a680a380d40a370c4066910e389b42b1421de31164e7676d179ed",
62+
"5eb0ad816983cad7ee669027b6168d9db60d26303306141d13f164a705f736c6"
6063
],
6164
"prompts/stabilize-strict-mode.md": [
6265
"ac9a176738ab2538d725c29ba302637bac6b287588e07d952aae352f85ab98cc",

0 commit comments

Comments
 (0)