You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 5750853
Browse filesBrowse the repository at this point in the historyBrowse 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]>
Copy file name to clipboardExpand all lines: adoption-kits/claude-code-skill/prompts/add-shipgate-to-repo.md
+30-16Lines changed: 30 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -55,19 +55,33 @@ agent-related PRs should use `agents-shipgate verify` after this adoption step.
55
55
would classify `is_agent_project: false`; look for `suggested_sources` and
56
56
`codex_plugin_candidates` when those fields are present.
57
57
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
60
69
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:
71
85
```bash
72
86
$SG init --workspace "$WS" --write --ci --json
73
87
```
@@ -78,7 +92,7 @@ agent-related PRs should use `agents-shipgate verify` after this adoption step.
78
92
- `auto_detected.agent_name` — the value the manifest carries (`null` when the template fell back to `CHANGE_ME`)
79
93
- `auto_detected.agent_scope`: `"single"` | `"ambiguous"` | `"unknown"`, with `auto_detected.agent_project_candidates[]` naming every self-contained project that defines an agent
80
94
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.
82
96
83
97
`refused_unresolved_scope` (exit 2) means the manifest scope was not
84
98
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.
98
112
99
113
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.
100
114
101
-
6. **Run the scan with patch suggestions:**
115
+
6. **Run the scan with patch suggestions** — in the workspace you initialized:
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`.
106
120
107
121
**Read these first for release gating (v0.8+):**
108
122
- `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`.
Copy file name to clipboardExpand all lines: plugins/claude-code/skills/agents-shipgate/prompts/add-shipgate-to-repo.md
+30-16Lines changed: 30 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -55,19 +55,33 @@ agent-related PRs should use `agents-shipgate verify` after this adoption step.
55
55
would classify `is_agent_project: false`; look for `suggested_sources` and
56
56
`codex_plugin_candidates` when those fields are present.
57
57
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
60
69
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:
71
85
```bash
72
86
$SG init --workspace "$WS" --write --ci --json
73
87
```
@@ -78,7 +92,7 @@ agent-related PRs should use `agents-shipgate verify` after this adoption step.
78
92
- `auto_detected.agent_name` — the value the manifest carries (`null` when the template fell back to `CHANGE_ME`)
79
93
- `auto_detected.agent_scope`: `"single"` | `"ambiguous"` | `"unknown"`, with `auto_detected.agent_project_candidates[]` naming every self-contained project that defines an agent
80
94
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.
82
96
83
97
`refused_unresolved_scope` (exit 2) means the manifest scope was not
84
98
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.
98
112
99
113
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.
100
114
101
-
6. **Run the scan with patch suggestions:**
115
+
6. **Run the scan with patch suggestions** — in the workspace you initialized:
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`.
106
120
107
121
**Read these first for release gating (v0.8+):**
108
122
- `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