Skip to content

Commit 5750853

Browse files
fix(init): make unresolved scope a state, not an absence
Second review round on #363. Nine P1s and four P2s, most of them the same mistake in different places: treating "Shipgate could not tell which project this is" as though it were "the workspace you named is the one". **Preview evaluated less than the command it emits.** `changed_files` came from `base...head` only, while the emitted `init` runs against the worktree. An uncommitted-only capability change read as an empty diff, and an empty diff read as "nothing narrows the scope". Preview now unions the working tree exactly as the full verifier does — one merge-base comparison, untracked paths included — and skips it only for an explicit `--head`, which is the one case where the worktree is not what is being evaluated. **Unresolved scope no longer authorizes root initialization.** `ScopeResolution` carries a status: `resolved`, `not_narrowed`, `contested`, `unclaimed`, `not_evaluated`. Only `not_narrowed` — nothing in the change points below the workspace — means initializing that workspace is right. A head that is not checked out, a capability path no project claims, and a change spanning projects each route to discovery with the reason quoted, rather than writing a manifest for whichever agent the current checkout happens to hold. **Contested configured projects outrank a root manifest.** A change spanning two projects that each carry their own `shipgate.yaml` has two governance boundaries; a root manifest is not a substitute for either. That route now stops for human review and names both verify commands. One command cannot honor two gates and the control contract does not let a routing surface authorize two, so the boundaries are named in the route a human reads rather than offered as a pick among them. **Every scoped project gets its own gate.** The action takes a single `config` scalar, so a shared `agents-shipgate.yml` gated whichever project initialized first and returned `skipped_existing_target` for the rest — reporting a skip while leaving them ungated. `--ci` now writes `agents-shipgate-<project>.yml` per gated manifest, and the double-wiring guard matches on the manifest as well as on the action so it still refuses to gate one project twice. The `config:` value is YAML-quoted when the path needs it: `apps/agent #1` rendered a comment and the action received a manifest that does not exist. **Reports follow the workspace.** `init` installed its managed ignore in the project while the verifier wrote to the repository root, so the directory the ignore covers was not the directory the reports landed in. The default `--out` now resolves under the requested workspace; an explicit `--out` still resolves against the repository root, so every invocation that names a directory writes exactly where it wrote before. Two projects in one repository also stop overwriting each other's control pointer. **The nested-manifest opt-in holds outside preview.** `trigger` computed it from `<workspace>/shipgate.yaml` alone, so `apps/a/README.md` beside `apps/a/shipgate.yaml` returned a docs-only skip. Both surfaces now call one resolver, which only counts manifests above the changed paths — an unrelated project's adoption must not opt in a change that has nothing to do with it. **Detection, in both directions.** A bare `requirements.txt` is still not a project boundary, but one beside an agent is the only boundary that layout has: two sibling ADK agents were read as one root scope and `init` picked one of their names. Conversely, an `Agent(name=…)` literal only draws a boundary when its file carries a supported framework import — an unrelated module defining its own `Agent` class made a single-agent repository refuse. Those literals stay as name suggestions. Also: `tools/shipgate-detect.py` keeps its marker census complete instead of truncating it with the general file cap (5,000 filler files hid two nested projects the CLI found); symlinked markers and manifests are rejected before preview promises a command the verifier would reject for symlink components; a relative `--agent-instructions-kit` is rebased into a candidate workspace or the candidate is emitted as a review action rather than as a command that exits 2; `init`'s own `next_action` names the manifest it just wrote, so `scan` finds it from anywhere; and the adoption prompt derives the workspace without executing preview's command, runs `init` exactly once, and keeps the rest of the flow in that workspace. Re-verified on google/adk-samples PR #1917 at its head: bare `verify --preview --json` routes to python/agents/crypto-payroll-agent from committed *and* uncommitted evidence; scoped `init --ci` writes the manifest in the project, a per-project workflow at the repository root with a repo-relative config, and a `scan` command that resolves; and the scoped verify writes its reports beside the manifest whose `.gitignore` covers them. Co-Authored-By: Claude Opus 5 <[email protected]>
1 parent 505acb1 commit 5750853

19 files changed

Lines changed: 1212 additions & 182 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,46 @@
8787
`agent_scope` and `agent_project_candidates[]` too, pinned against the CLI by
8888
the parity test: an agent that consults the zero-install path must not adopt
8989
a scope the CLI refuses.
90+
91+
Review found the routing could still be spent on evidence that did not
92+
support it, so three things changed shape. Preview now evaluates the same
93+
effective change set the full verifier does — committed range unioned with
94+
uncommitted and untracked work — because the command it emits runs against
95+
the working tree: an uncommitted-only capability change previously read as an
96+
empty diff, and an empty diff read as "nothing narrows the scope". "Scope not
97+
established" is now a state of its own rather than an absence: a head that is
98+
not checked out, a capability path no project claims, or a change spanning
99+
several projects each route to discovery or to human review, and never to
100+
initializing the repository root, which would turn "Shipgate could not tell"
101+
into a manifest for whichever agent the current checkout happens to hold.
102+
When the contested projects are already configured, each is its own gate and
103+
a human decides — a root manifest is not a substitute for either boundary.
104+
105+
Three more surfaces followed the same distinction. Reports now default to the
106+
workspace the caller named, so `verify --workspace apps/a` writes
107+
`apps/a/agents-shipgate-reports/` — the directory that project's managed
108+
`.gitignore` block actually covers, and one that two projects cannot
109+
overwrite for each other; an explicit `--out` still resolves against the
110+
repository root. `--ci` writes one workflow per gated manifest
111+
(`agents-shipgate-<project>.yml` beside the root's `agents-shipgate.yml`),
112+
because the action takes a single `config` scalar and one shared file gated
113+
whichever project initialized first while reporting a skip for the rest; that
114+
scalar is now YAML-quoted when the path needs it, so a directory named
115+
`apps/agent #1` no longer renders a comment. And the `trigger` command reads
116+
the nested-manifest opt-in through the same resolver preview uses, so
117+
`apps/a/README.md` beside `apps/a/shipgate.yaml` stops reporting a docs-only
118+
skip.
119+
120+
Detection got two corrections in opposite directions. A bare
121+
`requirements.txt` still is not a project boundary, but one sitting beside an
122+
agent is the only boundary that layout has — two sibling ADK agents were
123+
reported as one root scope, and `init` picked one of their names. And an
124+
`Agent(name=…)` literal only draws a boundary when its file carries a
125+
supported framework import: an unrelated module defining its own `Agent`
126+
class made a single-agent repository refuse. Those literals remain name
127+
suggestions. `tools/shipgate-detect.py` keeps its marker census complete
128+
rather than truncating it with the general file cap, so heavy filler no
129+
longer hides the projects it is supposed to find.
90130
([#363](https://github.com/ThreeMoonsLab/agents-shipgate/issues/363))
91131

92132
- **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
@@ -58,7 +58,8 @@
5858
"63dfb5f850c23009d5059a909bdd88bf35c57a77ab21a75aaa010f382945ef34",
5959
"514d8312f6edeed5007179bf6e7173da74cf526171da9ccf090fac9bb8f8f447",
6060
"44606ff86cc48c6532b5503a479a8a821874246b47b7abd54a23ffd280e0caba",
61-
"0f1ff58bb69a680a380d40a370c4066910e389b42b1421de31164e7676d179ed"
61+
"0f1ff58bb69a680a380d40a370c4066910e389b42b1421de31164e7676d179ed",
62+
"5eb0ad816983cad7ee669027b6168d9db60d26303306141d13f164a705f736c6"
6263
],
6364
"prompts/stabilize-strict-mode.md": [
6465
"ac9a176738ab2538d725c29ba302637bac6b287588e07d952aae352f85ab98cc",

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

Lines changed: 30 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -55,19 +55,33 @@ 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`**, and keep
59-
that directory for step 4 (`WS` below). When every capability-bearing
58+
**Read `control.next_action` — do not run it yet.** Step 4 performs the
59+
setup exactly once; running the emitted `init` here and the command in
60+
step 4 as well makes the second one exit 2 with
61+
`manifest_status: "skipped_existing"`. Take the `--workspace` value out of
62+
the emitted command and keep it as `WS`:
63+
64+
```bash
65+
WS=$(… control.next_action.command …) # the --workspace value, verbatim
66+
```
67+
68+
`WS` is `.` only when preview said so. When every capability-bearing
6069
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:
70+
that project instead of the repository root; re-spelling it as `.` in a
71+
monorepo writes one manifest covering every unrelated agent in the repo.
72+
73+
Three `next_action` kinds mean *do not* continue to step 4:
74+
75+
- `kind: "verify"` — the changed project is already configured. Run that
76+
command; adoption is done.
77+
- `kind: "discover"` — the change spans several projects, or the scope
78+
could not be established. Run the emitted `detect` command, pick the
79+
project your change belongs to, and use it as `WS`.
80+
- `actor: "human"` — several *configured* projects are involved. Surface
81+
the result; each one is its own gate.
82+
83+
4. **Generate a starter manifest + GitHub Actions workflow** — this is the
84+
only `init` the flow runs:
7185
```bash
7286
$SG init --workspace "$WS" --write --ci --json
7387
```
@@ -78,7 +92,7 @@ agent-related PRs should use `agents-shipgate verify` after this adoption step.
7892
- `auto_detected.agent_name` — the value the manifest carries (`null` when the template fell back to `CHANGE_ME`)
7993
- `auto_detected.agent_scope`: `"single"` | `"ambiguous"` | `"unknown"`, with `auto_detected.agent_project_candidates[]` naming every self-contained project that defines an agent
8094

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.
95+
`--ci` writes the workflow orthogonally to `--write`; each gets its own overwrite-refusal check, and a workflow that already gates *this* manifest skips 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. A root manifest gets `agents-shipgate.yml`; a scoped one gets its own `agents-shipgate-<project>.yml`, because the action takes a single `config` and one shared file would leave every project after the first ungated. Read `workflow.path` rather than assuming the name.
8296

8397
`refused_unresolved_scope` (exit 2) means the manifest scope was not
8498
settled: agents in more than one self-contained project (`agent_scope:
@@ -98,11 +112,11 @@ agent-related PRs should use `agents-shipgate verify` after this adoption step.
98112

99113
Read the agent's prompt or main file to derive both. Skipping this leaves an invalid adoption artifact — the manifest validates but downstream consumers see meaningless defaults.
100114

101-
6. **Run the scan with patch suggestions:**
115+
6. **Run the scan with patch suggestions** — in the workspace you initialized:
102116
```bash
103-
$SG scan -c shipgate.yaml --suggest-patches --format json --ci-mode advisory
117+
cd "$WS" && $SG scan -c shipgate.yaml --suggest-patches --format json --ci-mode advisory
104118
```
105-
The report lands at `agents-shipgate-reports/report.json`. The supporting Release Evidence Packet lands at `agents-shipgate-reports/packet.{md,json,html}`. Parse `report.json`; Codex plugin facts, when present, live under `codex_plugin_surface`.
119+
The report lands at `$WS/agents-shipgate-reports/report.json`, beside the manifest it describes; the supporting Release Evidence Packet lands at `$WS/agents-shipgate-reports/packet.{md,json,html}`. (Reports follow the workspace, so two projects in one repository never overwrite each other's results.) Every path below is relative to `$WS`. init's own `next_action` already names the manifest correctly for wherever you are — prefer running that command verbatim over retyping this one. Parse `report.json`; Codex plugin facts, when present, live under `codex_plugin_surface`.
106120

107121
**Read these first for release gating (v0.8+):**
108122
- `release_decision.decision` ∈ `{"blocked", "review_required", "insufficient_evidence", "passed"}` — baseline-aware. This is the gating signal. `insufficient_evidence` (v0.14+) fires when evidence coverage is degraded past threshold; treat unknown future values as `review_required`.

‎docs/agent-recipes.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -142,7 +142,11 @@ Key response fields:
142142

143143
`--ci` is orthogonal to `--write`: each gets its own overwrite-refusal.
144144
Exit code is the max of per-action outcomes; manifest-error and
145-
workflow-skip can co-occur.
145+
workflow-skip can co-occur. The workflow lands at the repository root —
146+
GitHub loads workflows from nowhere else — named `agents-shipgate.yml` for a
147+
root manifest and `agents-shipgate-<project>.yml` for a scoped one, because
148+
the action takes a single `config` scalar and one shared file would leave
149+
every project after the first ungated. Read `workflow.path`.
146150

147151
`refused_unresolved_scope` (exit `2`) is the one outcome where **nothing**
148152
is written — not the manifest, not the workflow, not the agent-instruction

‎docs/troubleshooting.md‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,8 @@ left to compare.
4545
So Shipgate scopes rather than guesses:
4646

4747
- `verify --preview` derives the `--workspace` it recommends from the changed
48-
paths. Each is attributed to the nearest directory at or above it that
48+
paths — committed *and* uncommitted, because the command it emits runs
49+
against the working tree. Each is attributed to the nearest directory at or above it that
4950
carries a project marker (`pyproject.toml`, `package.json`, `go.mod`,
5051
`Cargo.toml`, `pom.xml`, …), and the recommendation is that project when
5152
exactly one is claimed. Run its command verbatim. Changes spanning two
@@ -64,6 +65,16 @@ So Shipgate scopes rather than guesses:
6465
belongs to and re-run with `--workspace <that path>`.
6566
- `--allow-unresolved-scope` writes the single root manifest anyway. Use it
6667
only when one agent surface genuinely spans those directories.
68+
- Reports follow the workspace: `verify --workspace apps/a` writes
69+
`apps/a/agents-shipgate-reports/`, which is what the managed `.gitignore`
70+
block in that project covers, and two projects in one repository never
71+
overwrite each other's results. An explicit `--out` still resolves against
72+
the repository root.
73+
- With `--ci`, each manifest gets its own workflow — `agents-shipgate.yml` for
74+
a repository-root manifest, `agents-shipgate-<project>.yml` for a scoped one.
75+
The action takes a single `config`, so one shared file would gate whichever
76+
project initialized first and leave the rest ungated. Read `workflow.path`
77+
rather than assuming the name.
6778
- `agent_scope: "unknown"` is the same refusal for a different reason:
6879
discovery stopped at its Python-file cap in a workspace with several project
6980
roots, so a "single project" answer would just be whichever files were read

‎llms-full.txt‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -905,7 +905,11 @@ Key response fields:
905905

906906
`--ci` is orthogonal to `--write`: each gets its own overwrite-refusal.
907907
Exit code is the max of per-action outcomes; manifest-error and
908-
workflow-skip can co-occur.
908+
workflow-skip can co-occur. The workflow lands at the repository root —
909+
GitHub loads workflows from nowhere else — named `agents-shipgate.yml` for a
910+
root manifest and `agents-shipgate-<project>.yml` for a scoped one, because
911+
the action takes a single `config` scalar and one shared file would leave
912+
every project after the first ungated. Read `workflow.path`.
909913

910914
`refused_unresolved_scope` (exit `2`) is the one outcome where **nothing**
911915
is written — not the manifest, not the workflow, not the agent-instruction

‎plugins/claude-code/skills/agents-shipgate/prompts/add-shipgate-to-repo.md‎

Lines changed: 30 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -55,19 +55,33 @@ 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`**, and keep
59-
that directory for step 4 (`WS` below). When every capability-bearing
58+
**Read `control.next_action` — do not run it yet.** Step 4 performs the
59+
setup exactly once; running the emitted `init` here and the command in
60+
step 4 as well makes the second one exit 2 with
61+
`manifest_status: "skipped_existing"`. Take the `--workspace` value out of
62+
the emitted command and keep it as `WS`:
63+
64+
```bash
65+
WS=$(… control.next_action.command …) # the --workspace value, verbatim
66+
```
67+
68+
`WS` is `.` only when preview said so. When every capability-bearing
6069
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:
70+
that project instead of the repository root; re-spelling it as `.` in a
71+
monorepo writes one manifest covering every unrelated agent in the repo.
72+
73+
Three `next_action` kinds mean *do not* continue to step 4:
74+
75+
- `kind: "verify"` — the changed project is already configured. Run that
76+
command; adoption is done.
77+
- `kind: "discover"` — the change spans several projects, or the scope
78+
could not be established. Run the emitted `detect` command, pick the
79+
project your change belongs to, and use it as `WS`.
80+
- `actor: "human"` — several *configured* projects are involved. Surface
81+
the result; each one is its own gate.
82+
83+
4. **Generate a starter manifest + GitHub Actions workflow** — this is the
84+
only `init` the flow runs:
7185
```bash
7286
$SG init --workspace "$WS" --write --ci --json
7387
```
@@ -78,7 +92,7 @@ agent-related PRs should use `agents-shipgate verify` after this adoption step.
7892
- `auto_detected.agent_name` — the value the manifest carries (`null` when the template fell back to `CHANGE_ME`)
7993
- `auto_detected.agent_scope`: `"single"` | `"ambiguous"` | `"unknown"`, with `auto_detected.agent_project_candidates[]` naming every self-contained project that defines an agent
8094

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.
95+
`--ci` writes the workflow orthogonally to `--write`; each gets its own overwrite-refusal check, and a workflow that already gates *this* manifest skips 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. A root manifest gets `agents-shipgate.yml`; a scoped one gets its own `agents-shipgate-<project>.yml`, because the action takes a single `config` and one shared file would leave every project after the first ungated. Read `workflow.path` rather than assuming the name.
8296

8397
`refused_unresolved_scope` (exit 2) means the manifest scope was not
8498
settled: agents in more than one self-contained project (`agent_scope:
@@ -98,11 +112,11 @@ agent-related PRs should use `agents-shipgate verify` after this adoption step.
98112

99113
Read the agent's prompt or main file to derive both. Skipping this leaves an invalid adoption artifact — the manifest validates but downstream consumers see meaningless defaults.
100114

101-
6. **Run the scan with patch suggestions:**
115+
6. **Run the scan with patch suggestions** — in the workspace you initialized:
102116
```bash
103-
$SG scan -c shipgate.yaml --suggest-patches --format json --ci-mode advisory
117+
cd "$WS" && $SG scan -c shipgate.yaml --suggest-patches --format json --ci-mode advisory
104118
```
105-
The report lands at `agents-shipgate-reports/report.json`. The supporting Release Evidence Packet lands at `agents-shipgate-reports/packet.{md,json,html}`. Parse `report.json`; Codex plugin facts, when present, live under `codex_plugin_surface`.
119+
The report lands at `$WS/agents-shipgate-reports/report.json`, beside the manifest it describes; the supporting Release Evidence Packet lands at `$WS/agents-shipgate-reports/packet.{md,json,html}`. (Reports follow the workspace, so two projects in one repository never overwrite each other's results.) Every path below is relative to `$WS`. init's own `next_action` already names the manifest correctly for wherever you are — prefer running that command verbatim over retyping this one. Parse `report.json`; Codex plugin facts, when present, live under `codex_plugin_surface`.
106120

107121
**Read these first for release gating (v0.8+):**
108122
- `release_decision.decision` ∈ `{"blocked", "review_required", "insufficient_evidence", "passed"}` — baseline-aware. This is the gating signal. `insufficient_evidence` (v0.14+) fires when evidence coverage is degraded past threshold; treat unknown future values as `review_required`.

0 commit comments

Comments
 (0)