Skip to content

Commit 505acb1

Browse files
fix(init): resolve manifest scope from evidence the caller can trust
Review follow-up on #363. Eight defects, six of which let the scoping either not fire at all or fire on evidence that did not support it. **Plain preview never activated the scoping.** `changed_files` was only collected when the caller passed `--base`, but the promoted adoption command is the bare `verify --preview --json`. In that flow the change set was empty, no scope could be derived, and the preview every first adoption runs recommended root `init` — then did it again after a scoped adoption. Preview now runs the verifier's own default-base discovery and honors `--no-base`. **An unclaimed capability path no longer disappears.** A changed path carrying a capability surface that sits under no project root — a root `prompts/system.md` travelling with a change to `services/b` — was silently dropped, so the emitted claim that every capability path belongs to `services/b` was false. It now vetoes the suggestion. Documentation and tests still cannot outvote code, which is the leg the reported PR needs. **Artifact-defined projects are visible to ambiguity detection.** Candidates were seeded from framework `candidate_files` and Python name literals only, so two OpenAPI-, MCP-, n8n- or Conductor-only projects reported `agent_scope: "single"` with no candidates and root `init` wrote one manifest covering both. Evidence is now everything `init` would turn into a manifest, including artifact sources, Codex plugin packages, and a nested `shipgate.yaml` somebody already scoped by hand. **Capped discovery no longer reports a complete answer.** Python parsing stops at `--max-python-files`; with projects `a` and `z` separated by 1,000 filler files, discovery saw only `a` and said `"single"`, making the refusal depend on filesystem ordering. Truncation in a workspace with several project roots now yields `agent_scope: "unknown"`, which refuses like `"ambiguous"`. Truncation alone does not: a repository with one project root has nowhere for a second project to hide, so large single-project repositories keep their verdict and their working `init`. **Scoped `--ci` wrote a workflow GitHub never loads.** With a nested manifest it wrote `<project>/.github/workflows/agents-shipgate.yml` and reported success although no gate could run. The workflow now lands at the repository root with `config:` naming the manifest relative to that root, which is where the action runs. **The changed project's manifest outranks a root one.** The scoped-verify branch was unreachable whenever a root manifest existed, so a change scoped to a nested project was told to verify the root config — a different governance boundary. **Marker evidence is bound to the evaluated head.** Markers are read from the working tree because that is what `init` runs against, so a preview of a head that is not the current checkout now claims no scope rather than recommending a directory that depends on what is checked out. **The zero-install detector carries the same verdict.** `tools/shipgate-detect.py` (`script_version` 0.3.0) emits `agent_scope` and `agent_project_candidates[]`, stops recommending root init on an unresolved scope, and the parity test pins both against the CLI: an agent that consults the zero-install path must not adopt a scope the CLI refuses. Also from the review: `TRIGGER-SHIPGATE-MANIFEST` matches `**/shipgate.yaml` so an edit to a nested manifest is no longer `no_match` (closing a gap `_TRUST_ROOT_TRIGGER_GAPS` had tracked by name), with the pre-commit regex, Cursor globs, and documented snippets that copy the catalog following; a nested manifest counts as the repo-already-opted-in signal; a diff spanning several projects routes to `detect` instead of to an `init` that would deterministically refuse; scope resolution no longer `.strip()`s paths, which changed legal Git paths with leading or trailing spaces; candidate recovery commands repeat the setup flags the caller passed; and the adoption prompt no longer says to preserve the emitted workspace and then hard-codes `--workspace .`. The refusal is renamed `refused_unresolved_scope` with `--allow-unresolved-scope`, because it now covers a scope that could not be established as well as one that is ambiguous. Re-verified on google/adk-samples PR #1917 at its head: the promoted `verify --preview --json` alone finds `origin/main`, reads all 15 changed paths, and routes to python/agents/crypto-payroll-agent; scoped `init --ci` writes the manifest in the project and the workflow at the repository root with a repo-relative config. Co-Authored-By: Claude Opus 5 <[email protected]>
1 parent e478909 commit 505acb1

33 files changed

Lines changed: 1422 additions & 371 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: 20 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -234,9 +234,11 @@ agents-shipgate bootstrap --json
234234

235235
- **`detect`** — read-only; classifies the workspace. `is_agent_project: false`
236236
means stop early. `agent_scope` says whether one manifest can describe this
237-
workspace at all: on `"ambiguous"`, `agent_project_candidates[]` lists each
238-
self-contained project that defines an agent, and the manifest belongs in one
239-
of them rather than at the workspace root.
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.
240242
- **`init`** — auto-detects by default. `--ci` writes
241243
`.github/workflows/agents-shipgate.yml`; orthogonal to `--write`. Use
242244
`--minimal` for the pre-v0.6 CHANGE_ME-heavy template.
@@ -252,15 +254,19 @@ agents-shipgate bootstrap --json
252254
bundles under `.agents/skills/agents-shipgate/` and
253255
`.claude/skills/agents-shipgate/` respectively. Strict CI and baselines remain
254256
opt-in human decisions; generated CI stays advisory by default.
255-
`--write` **refuses** a workspace whose agents live in more than one
256-
self-contained project — `manifest_status: "refused_ambiguous_scope"`, exit
257-
`2`, nothing written at all (no manifest, no workflow, no snippets, no
258-
`.gitignore` block) — rather than adopting the first `Agent(name=…)` literal
259-
it parsed for a manifest that would cover unrelated agents. Re-run with
260-
`--workspace` pointed at one of
261-
`auto_detected.agent_project_candidates[].path`; `--allow-ambiguous-scope`
262-
overrides when one agent surface genuinely spans them, and `--minimal`
263-
(which adopts no detected name or tool surface) is never scope-gated.
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.
264270
- **`scan --suggest-patches`** — attaches Patch objects to every active
265271
finding. `Finding.patches` is absent without the flag.
266272
- **`apply-patches`** — file-grouped, dry-run by default. Containment-
@@ -361,6 +367,8 @@ One known gap in the Google ADK row: an edit that *modifies* a tools list on the
361367

362368
`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.
363369

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+
364372
Two implicit triggers also fire even when no row above matches:
365373

366374
- **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: 69 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -16,35 +16,77 @@
1616
answer the question, so preview now derives `--workspace` from them: each is
1717
attributed to the nearest directory at or above it carrying a project marker
1818
(`pyproject.toml`, `package.json`, `go.mod`, `Cargo.toml`, …), and the scope
19-
is that project when exactly one is claimed. The workspace root is left
20-
unchanged whenever the paths do not narrow it — a root-level change, or one
21-
spanning two projects, which narrows to *nothing* rather than to their common
22-
parent, because the parent of two projects is not itself a project.
23-
Documentation and tests cannot outvote code: when more than one project is
24-
claimed, the projects claimed *only* by documentation or test paths drop out,
25-
and the trigger catalog's own docs-only rule decides which paths those are so
26-
the two surfaces cannot drift. That leg is load-bearing — the reported PR
27-
edits `python/agents/README.md` one directory above the project it adds, and
28-
counting that README as a competing claim sends the answer straight back to
29-
the repository root. When that project already carries its own
30-
`shipgate.yaml`, preview
31-
routes to `verify` there instead of to setup, so following the suggestion
32-
once does not turn the next preview into a loop against a manifest that now
33-
exists. `init --write` closes the same gap from the other side: a workspace
34-
whose agents live in more than one project reports
35-
`manifest_status: "refused_ambiguous_scope"` (exit 2) with
36-
`auto_detected.agent_scope` and `agent_project_candidates[]` naming each one,
37-
rather than adopting the first agent name it parsed. A refused run writes
38-
*nothing* — not the manifest, not the CI workflow, not the agent-instruction
39-
snippets, not the reports `.gitignore` block — so a workspace Shipgate
40-
declined to adopt carries no Shipgate edits into the diff. Rank 1 of the
41-
emitted recovery is deliberately not a command: promoting one candidate would
42-
make the same arbitrary pick the refusal exists to prevent. `--minimal`
43-
adopts no detected name or tool surface and is unaffected; a repository that
44-
really is one agent surface across several projects passes
45-
`--allow-ambiguous-scope`; and re-running `init --write
19+
is that project when exactly one is claimed **and** every capability-bearing
20+
changed path was claimed by it. A capability path no project owns — a root
21+
`prompts/system.md` travelling with a change to `services/b` — vetoes the
22+
answer rather than being dropped, because "this change belongs to
23+
`services/b`" would then be a false statement about the diff. The workspace
24+
root is likewise left unchanged whenever the paths do not narrow it — a
25+
root-level change, or one spanning two projects, which narrows to *nothing*
26+
rather than to their common parent, because the parent of two projects is not
27+
itself a project. Documentation and tests cannot outvote code: when more than
28+
one project is claimed, the projects claimed *only* by documentation or test
29+
paths drop out, and the trigger catalog's own docs-only rule decides which
30+
paths those are so the two surfaces cannot drift. That leg is load-bearing —
31+
the reported PR edits `python/agents/README.md` one directory above the
32+
project it adds, and counting that README as a competing claim sends the
33+
answer straight back to the repository root. Base detection now runs in
34+
preview exactly as it does in `verify` (honoring `--no-base`), because the
35+
promoted adoption command is the bare `verify --preview --json`: without it
36+
the preview every first adoption runs evaluates an empty change set and
37+
nothing below it can fire. Markers are read from the working tree — what
38+
`init` will run against — so a preview of a head that is not the current
39+
checkout claims no scope at all rather than recommending a directory that
40+
depends on what happens to be checked out. When the changed project already
41+
carries its own `shipgate.yaml`, preview routes to `verify` **there**, ahead
42+
of any root manifest, which governs a different boundary; that also stops the
43+
next preview from looping against a manifest that now exists. A change
44+
spanning several projects routes to `detect` instead of to an `init` that
45+
would deterministically refuse.
46+
47+
`init --write` closes the same gap from the other side: a workspace whose
48+
manifest scope is unresolved reports
49+
`manifest_status: "refused_unresolved_scope"` (exit 2) with
50+
`auto_detected.agent_scope` and `agent_project_candidates[]`, rather than
51+
adopting the first agent name it parsed. Two things make a scope unresolved.
52+
`agent_scope: "ambiguous"` is agents in several self-contained projects —
53+
evidenced by everything `init` would turn into a manifest, so an
54+
OpenAPI-only or MCP-only project with no Python at all counts, as does a
55+
nested `shipgate.yaml` somebody already scoped by hand. `agent_scope:
56+
"unknown"` is discovery capped before it could tell: Python parsing stops at
57+
`--max-python-files`, and in a workspace with several project roots a
58+
"single project" verdict would just be whichever files were read first.
59+
Truncation alone is not enough to withhold an answer — a repository with one
60+
project root has nowhere for a second project to hide, so large
61+
single-project repositories keep their verdict and their working `init`. A
62+
refused run writes *nothing* — not the manifest, not the CI workflow, not the
63+
agent-instruction snippets, not the reports `.gitignore` block — so a
64+
workspace Shipgate declined to adopt carries no Shipgate edits into the diff.
65+
Rank 1 of the emitted recovery is deliberately not a command: promoting one
66+
candidate would make the same arbitrary pick the refusal exists to prevent,
67+
and the refused workspace itself is never offered back. The per-candidate
68+
commands repeat the setup flags the caller passed, so a recovery cannot
69+
silently complete with less than `--ci` or an agent-instruction selection
70+
asked for. `--minimal` adopts no detected name or tool surface and is
71+
unaffected; a repository that really is one agent surface across several
72+
projects passes `--allow-unresolved-scope`; and re-running `init --write
4673
--agent-instructions=…` on an adopted repository is untouched, because its
4774
scope was settled when its manifest was written.
75+
76+
Two surfaces around it were wrong in the same direction. `init --ci` scoped
77+
to a sub-directory wrote `<project>/.github/workflows/agents-shipgate.yml`,
78+
which GitHub never loads — a gate reported as written that could not run; the
79+
workflow now lands at the repository root with a `config:` naming the
80+
manifest relative to that root. And `TRIGGER-SHIPGATE-MANIFEST` matched
81+
`shipgate.yaml` only at the repository root, so an edit to
82+
`services/refund/shipgate.yaml` — the file that declares that project's
83+
agent, purpose, and tool surface — reported `no_match`; it now matches at any
84+
depth, as do the pre-commit `files:` regex and the Cursor activation globs
85+
that copy the catalog, and a nested manifest counts as the repo-already-opted-in
86+
signal. `tools/shipgate-detect.py` (`script_version` `0.3.0`) carries
87+
`agent_scope` and `agent_project_candidates[]` too, pinned against the CLI by
88+
the parity test: an agent that consults the zero-install path must not adopt
89+
a scope the CLI refuses.
4890
([#363](https://github.com/ThreeMoonsLab/agents-shipgate/issues/363))
4991

5092
- **The recommended next command now runs where it was recommended.** Every

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,8 @@
5757
"53296f41b7c2bc8538555a4361707de8b990748b7a5d80ae4ce066af83af8fa7",
5858
"63dfb5f850c23009d5059a909bdd88bf35c57a77ab21a75aaa010f382945ef34",
5959
"514d8312f6edeed5007179bf6e7173da74cf526171da9ccf090fac9bb8f8f447",
60-
"44606ff86cc48c6532b5503a479a8a821874246b47b7abd54a23ffd280e0caba"
60+
"44606ff86cc48c6532b5503a479a8a821874246b47b7abd54a23ffd280e0caba",
61+
"0f1ff58bb69a680a380d40a370c4066910e389b42b1421de31164e7676d179ed"
6162
],
6263
"prompts/stabilize-strict-mode.md": [
6364
"ac9a176738ab2538d725c29ba302637bac6b287588e07d952aae352f85ab98cc",

‎adoption-kits/claude-code-skill/prompts/add-shipgate-to-repo.md‎

Lines changed: 30 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -55,34 +55,42 @@ agent-related PRs should use `agents-shipgate verify` after this adoption step.
5555
would classify `is_agent_project: false`; look for `suggested_sources` and
5656
`codex_plugin_candidates` when those fields are present.
5757

58-
Run the emitted command **verbatim, including its `--workspace`**. When the
59-
changed paths all sit inside one self-contained project, preview scopes
60-
setup to that project instead of the repository root; re-spelling the
61-
command with `--workspace .` in a monorepo writes one manifest covering
62-
every unrelated agent in the repo. If that project already carries its own
63-
`shipgate.yaml`, preview routes you to `verify` there rather than to setup.
64-
65-
4. **Generate a starter manifest + GitHub Actions workflow** — at the workspace preview named:
58+
Run the emitted command **verbatim, including its `--workspace`**, and keep
59+
that directory for step 4 (`WS` below). When every capability-bearing
60+
changed path belongs to one self-contained project, preview scopes setup to
61+
that project instead of the repository root; re-spelling the command with
62+
`--workspace .` in a monorepo writes one manifest covering every unrelated
63+
agent in the repo. If that project already carries its own `shipgate.yaml`,
64+
preview routes you to `verify` there rather than to setup. If the change
65+
spans several projects, preview routes you to `detect` instead — read the
66+
project list and initialize the one your change belongs to.
67+
68+
4. **Generate a starter manifest + GitHub Actions workflow.** Use the
69+
workspace preview named — `WS` below is that directory, which is `.` only
70+
when preview said so:
6671
```bash
67-
$SG init --workspace . --write --ci --json
72+
$SG init --workspace "$WS" --write --ci --json
6873
```
6974
The `--json` form returns:
70-
- `manifest_status`: `"written"` | `"skipped_existing"` | `"refused_ambiguous_scope"` | `"not_attempted"`
75+
- `manifest_status`: `"written"` | `"skipped_existing"` | `"refused_unresolved_scope"` | `"not_attempted"`
7176
- `workflow.status` (with `--ci`): `"written"` | `"skipped_existing_target"` | `"skipped_cross_reference"`
7277
- `placeholders[]` — entries the template intentionally left as `CHANGE_ME` because no high-confidence signal was available
7378
- `auto_detected.agent_name` — the value the manifest carries (`null` when the template fell back to `CHANGE_ME`)
74-
- `auto_detected.agent_scope`: `"single"` | `"ambiguous"`, with `auto_detected.agent_project_candidates[]` naming every self-contained project that defines an agent
75-
76-
`--ci` writes `.github/workflows/agents-shipgate.yml` orthogonally to `--write`. Each gets its own overwrite-refusal check; existing workflows that already call `ThreeMoonsLab/agents-shipgate` skip with a distinct `cross_reference_path`.
77-
78-
`refused_ambiguous_scope` (exit 2) means the workspace defines agents in
79-
more than one project, so no single `agent.name`, `declared_purpose`, or
80-
tool surface describes it. Nothing was written — not the manifest, not the
81-
workflow, not the reports `.gitignore` block. Do not retry the same command:
82-
pick the project this change belongs to from `agent_project_candidates[]`
83-
and re-run with `--workspace <that directory>`. `--allow-ambiguous-scope`
84-
writes one manifest for all of them, and is right only when a single agent
85-
surface genuinely spans them.
79+
- `auto_detected.agent_scope`: `"single"` | `"ambiguous"` | `"unknown"`, with `auto_detected.agent_project_candidates[]` naming every self-contained project that defines an agent
80+
81+
`--ci` writes `.github/workflows/agents-shipgate.yml` orthogonally to `--write`. Each gets its own overwrite-refusal check; existing workflows that already call `ThreeMoonsLab/agents-shipgate` skip with a distinct `cross_reference_path`. The workflow always lands at the **repository root** — GitHub loads workflows from nowhere else — with `config:` naming the manifest relative to that root, so a scoped adoption still gets a gate that runs.
82+
83+
`refused_unresolved_scope` (exit 2) means the manifest scope was not
84+
settled: agents in more than one self-contained project (`agent_scope:
85+
"ambiguous"`), or discovery capped before it could tell (`"unknown"`). No
86+
single `agent.name`, `declared_purpose`, or tool surface describes such a
87+
workspace, so nothing was written — not the manifest, not the workflow, not
88+
the reports `.gitignore` block. Do not retry the same command: pick the
89+
project this change belongs to from `agent_project_candidates[]` and re-run
90+
with `--workspace <that directory>`, keeping the setup flags (the emitted
91+
`next_actions[]` commands already carry them). `--allow-unresolved-scope`
92+
writes one manifest for the workspace as a whole, and is right only when a
93+
single agent surface genuinely spans it.
8694

8795
5. **Replace placeholders.** Walk `placeholders[]` from the JSON output. On a fresh workspace the template typically leaves two:
8896
- `agent.name: CHANGE_ME` — replace with the agent's actual role (no strong `Agent(name="…")` literal was found in the source).

‎benchmark/setup-variants/30-cursor-rule/agents-shipgate.mdc.template‎

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"

0 commit comments

Comments
 (0)