Skip to content

Commit aa6b126

Browse files
fix(agent-mode): drop the edit variant and close the remaining setup findings (#323)
Addresses the third and fourth review rounds on #372. Two of the eleven threads were structural and both are resolved by taking scope *out* rather than adding more. **The typed `edit` action is removed.** Bumping the compatibility floor did not answer the objection: `CodingAgentAction` is embedded by the verifier, the handoff, preflight, the agent result, the boundary result, and verify-run, so widening it widened six durable published schemas under unchanged identifiers — and five of those artifacts record no `contract_version`, so a consumer holding a stored payload cannot use a runtime floor to tell which shape it has. All six are now byte-identical to `main` again, as is the frozen codex projection, and `MINIMUM_CONTROL_CONTRACT_VERSION` returns to 21 with the adoption-kit chain it had dragged along. A setup step that needs a file changed routes as a `configure` command naming the check that confirms it, with the file in `why` and structurally in `next_actions[].path` — which is where `docs/diagnostics.md` has always published a path, and is how every other producer in this system routes agent work. **`scan` is out of the rollout, and the claims now say so.** The verdict lift was withdrawn last round; what remained was a PR and a set of documents still claiming #323 was closed for six commands. `AGENTS.md`, `STABILITY.md`, `docs/agent-contract-current.md`, and the CHANGELOG now state that `scan` publishes no verdict and that #323's scan half stays open until a complete, reconfirmable input snapshot is threaded through report generation and pointer publication. The two misleading messages are corrected: a SARIF-only scan does bind a machine-readable artifact carrying the verdict, so the envelope says the verdict is *withheld*, never that none exists. The rest: - `init` validates the existing manifest before reporting `setup_complete`. An empty `shipgate.yaml` has no placeholders in it, so the refresh path called it configured and handed back a verify command that exits 2 on the same file. - `doctor`'s error paths carry the envelope. An invalid manifest printed nothing on stdout and a legacy line on stderr; a valid HITL manifest whose declared trace path is still `CHANGE_ME` failed while opening that literal path, before ownership was evaluated, losing the field, the line, and the fact that a person owes the value. - `detect` lets an adopted root settle an ambiguous scope. `--allow-unresolved-scope` is a decision, and re-asking on the next run made it unrepeatable. - `init`'s dry-run advance repeats the setup flags it was given. The bare `init --write` it emitted dropped `--ci`, the instruction selection, and `--allow-unresolved-scope` — the last of which makes the command exit 2 in the monorepo that needed it. - `inspect_sources` reads the manifest once and parses those bytes. Loading the path and then reopening it was two generations, so doctor could route from manifest A under an identity hashing manifest B. - `_placeholder_review_why` splits on both path separators and bounds the prefix twice, so a long Windows path can no longer push the line number and field name out of the only human action. - `init`'s `input_id` covers the #370 scope facts, so a changed candidate list moves the identity of the answer about it. - `.well-known` publishes the real floor, pinned by a parity test against the runtime contract, and the stale Codex-integration prerequisite is corrected. Co-Authored-By: Claude Opus 5 <[email protected]>
1 parent e8b220b commit aa6b126

40 files changed

Lines changed: 740 additions & 739 deletions

‎.agents/skills/agents-shipgate/SKILL.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Do not use it for general linting, runtime monitoring, evals, model-output quali
1515

1616
1. For local checks, verifier runs, host audits, and supporting recovery commands, read `references/recipes.md`.
1717
2. For reading `report.json`, summarizing release decisions, or deciding what may be auto-applied, read `references/report-reading.md`.
18-
3. Before running Shipgate CLI commands, require a CLI whose `agents-shipgate contract --json` reports `minimum_control_contract_version: 24`: run `command -v agents-shipgate`, `agents-shipgate --version`, and `agents-shipgate contract --json`. If it is missing or stale, tell the user to install or upgrade `agents-shipgate`. The Codex plugin supplies workflows, not the scanner binary.
18+
3. Before running Shipgate CLI commands, require a CLI whose `agents-shipgate contract --json` reports `minimum_control_contract_version: 21`: run `command -v agents-shipgate`, `agents-shipgate --version`, and `agents-shipgate contract --json`. If it is missing or stale, tell the user to install or upgrade `agents-shipgate`. The Codex plugin supplies workflows, not the scanner binary.
1919
4. Set `AGENTS_SHIPGATE_AGENT_MODE=1` before running Shipgate commands so errors include structured `next_action` JSON.
2020
5. Default first-time CI to advisory mode. Do not enable release-blocking CI or save a baseline until a human has reviewed current findings.
2121
6. For local agent control, run `shipgate check --agent codex --workspace . --format agent-boundary-json` and read the stdout `shipgate.agent_boundary_result/v2` object. Switch on `control.state`; follow only `control.next_action`, `control.allowed_next_commands`, and `control.human_review`. Treat `decision` as diagnostic context only.
@@ -26,7 +26,7 @@ Do not use it for general linting, runtime monitoring, evals, model-output quali
2626

2727
## Fast Paths
2828

29-
- CLI preflight: run `command -v agents-shipgate`, `agents-shipgate --version`, and `agents-shipgate contract --json`. Continue only when the installed CLI reports `minimum_control_contract_version: 24`; if it is missing or stale, ask the user to install or upgrade `agents-shipgate`.
29+
- CLI preflight: run `command -v agents-shipgate`, `agents-shipgate --version`, and `agents-shipgate contract --json`. Continue only when the installed CLI reports `minimum_control_contract_version: 21`; if it is missing or stale, ask the user to install or upgrade `agents-shipgate`.
3030
- Agent-native check: run `shipgate check --agent codex --workspace . --format agent-boundary-json`; read only the JSON result for routing. Four shapes: continue, repair, verify-and-report (a graded `require_review` set — finish the work, then name every `pending_review[]` item in the summary), and stop.
3131
- Agent-related PR/CI diff: run `agents-shipgate verify --workspace . --config shipgate.yaml --base origin/main --head HEAD --ci-mode advisory --format json` after making the base ref available. For local uncommitted work, omit `--base`/`--head` so the working tree is scanned. `verify` never fetches.
3232
- Existing manifest / ongoing PR: run `agents-shipgate verify --workspace . --config shipgate.yaml --ci-mode advisory --format json`.

‎.agents/skills/agents-shipgate/references/recipes.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ agents-shipgate contract --json
1717
```
1818

1919
Require `agents-shipgate contract --json` to report
20-
`minimum_control_contract_version: 24`. If it is missing or stale, ask the
20+
`minimum_control_contract_version: 21`. If it is missing or stale, ask the
2121
user to install or upgrade:
2222

2323
```bash
@@ -26,7 +26,7 @@ pipx upgrade agents-shipgate
2626
```
2727

2828
Do not report the task complete until the CLI exists and reports runtime
29-
contract 24. Local boundary checks emit `shipgate.agent_boundary_result/v2`;
29+
contract 21. Local boundary checks emit `shipgate.agent_boundary_result/v2`;
3030
legacy v1 fixtures are retained only for older protocol integrations.
3131

3232
## Local Agent Check

‎AGENTS.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -318,7 +318,15 @@ The machine-readable catalog of error kinds — exit codes, typical causes, addi
318318
`agents-shipgate agent control` emit. Switch on `control.control_state` and
319319
`control.permissions` for the whole adoption walk instead of learning a
320320
different result shape per command; `control.next_action` is the one typed
321-
rank-1 step, and `next_actions[]` beside it keeps the ranked alternatives.
321+
rank-1 step, and `next_actions[]` beside it keeps the ranked alternatives —
322+
including the exact `path` when the step is a file edit, which the control
323+
action names in `why`.
324+
325+
`scan` is **not** part of this: `agents-shipgate agent control` after a scan
326+
reports `decision: null` with a `reason` saying the verdict is withheld. A scan
327+
pointer binds no reconfirmable snapshot of the inputs it read, so no artifact in
328+
that directory can show its verdict still describes the workspace. Run `verify`
329+
for one that can.
322330

323331
Read `control.decision_source` before `control.decision`. Setup commands run
324332
before a release decision exists, so they report `setup` and a verdict from

‎CHANGELOG.md‎

Lines changed: 22 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,3 @@
1-
- **`agent control` after a `scan` publishes no release verdict, and says why.**
2-
`scan` runs the release engine and binds its `report.json`, but its pointer
3-
records no HEAD, no worktree overlay, and no input set, so nothing about that
4-
verdict can be reconfirmed: an edit to the manifest, to a `tools.json` it
5-
references, to a policy pack, or to a baseline leaves the pointer reading
6-
cleanly with the old answer. Reporting it anyway published a stale `passed`.
7-
The envelope therefore reports `decision: null` as it did before, and `reason`
8-
now states which of two things is true — the scan binds no reconfirmable
9-
input snapshot, or it bound no machine-readable report at all. That is the
10-
part that was actually missing: a bare `decision: null` reads exactly like
11-
output produced before any engine ran. A verdict a reader can check comes from
12-
`verify`.
131
# Changelog
142

153
## Unreleased
@@ -179,35 +167,28 @@
179167
over an existing manifest now inspects *that* manifest rather than the
180168
template it did not write, so the documented refresh command is not a route
181169
around the boundary.
182-
- **`next_action` gains a typed `edit` route** (`kind: "edit"`, with `path` and
183-
`expects`). Setup reaches steps that are unambiguously the agent's and have
184-
no executable form — a manifest the loader rejected, a `tool_sources[].path`
185-
that does not resolve — and the union previously forced a choice between
186-
hiding the instruction in another command's prose or stopping the turn for
187-
work the agent owns. Only setup output can contain it, so
188-
`minimum_control_contract_version` moves to `24`: the union is the one every
189-
control producer embeds, so "no producer emits it" is a claim about code paths
190-
rather than about what the contract permits. The frozen
191-
`shipgate.codex_boundary_result/v2` projection is byte-unchanged and now
192-
snapshots its own action union rather than tracking the live one — it had
193-
been silently widening with every variant added to `AgentControl`, which is
194-
what "frozen" was supposed to prevent.
195-
- **`agent control` after a `scan` now reports that scan's release decision —
196-
and withholds it once it is no longer current.** `scan` runs the release
197-
engine and binds its `report.json`, but the envelope published
198-
`decision: null` / `decision_source: "none"`, making a completed scan
199-
indistinguishable from output produced before any engine had run. The verdict
200-
is lifted from the bound report inside the same generation-safe read that
201-
validates the pointer, never recomputed. Byte integrity is not currency,
202-
though: a `scan` pointer binds no HEAD or worktree identity, so the generic
203-
comparison passed vacuously and an edited manifest still read cleanly with the
204-
old verdict. `scan` now records the manifest it read beside the digest it
205-
already recorded, and the verdict is published only while that file still
206-
hashes to it. Where it cannot be reconfirmed — or where a format-limited scan
207-
bound no machine-readable report — `decision` is `null` and `reason` says
208-
which, so a withheld verdict is never read as an absent one. Authority is
209-
unchanged throughout: the control state and permissions still come from the
210-
pointer, and a scan still cannot authorize a merge.
170+
- **The `AgentControl` union is unchanged, and the compatibility floor stays at
171+
`21`.** A typed `edit` route was added for setup steps that are the agent's
172+
own and have no executable form — a manifest the loader rejected, a
173+
`tool_sources[].path` that does not resolve — and then removed. That union is
174+
embedded by the verifier, the handoff, preflight, the agent result, the
175+
boundary result, and verify-run, so widening it widened six durable published
176+
schemas under unchanged identifiers, and five of those artifacts record no
177+
`contract_version` for a consumer holding a stored payload to disambiguate
178+
with. Such a step now routes as a `configure` command naming the check that
179+
confirms it, with the file named in `why` and structurally in
180+
`next_actions[].path`. Contract `24` covers what did widen:
181+
`shipgate.agent_control/v1`, which is emitted on stdout and never stored.
182+
- **`scan` is outside this rollout, and now says so.** `agent control` after a
183+
scan reports `decision: null` with a `reason` stating the verdict is
184+
*withheld*, not absent: the scan reached one — `report.sarif` even carries it
185+
— but a scan pointer binds no reconfirmable snapshot of the inputs it read, so
186+
no artifact in that directory can show the verdict still describes the
187+
workspace. An edit to the manifest, a referenced `tools.json`, a policy pack,
188+
or a baseline leaves the pointer reading cleanly with the old answer.
189+
Publishing a verdict from `scan` needs a complete input snapshot threaded
190+
through report generation and pointer publication; until that lands, `verify`
191+
is where a checkable verdict comes from, and #323's scan half stays open.
211192

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

‎STABILITY.md‎

Lines changed: 29 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -17,17 +17,25 @@ for reproducible CI.
1717

1818
## Migration Note: unreleased — one control vocabulary across the setup commands
1919

20-
Runtime contract `23 → 24`, and `minimum_control_contract_version` **moves to
21-
24** with it. The first reading of this change was that no *producer* emits the
22-
new `edit` route outside setup output, so a contract-21 consumer could never
23-
observe it. That is a claim about which code paths run, not about what the
24-
contract permits: `CodingAgentAction` is the union every control producer
25-
embeds, so a verifier, handoff, preflight, boundary, or verify-run payload
26-
carrying an `edit` route validates here and is rejected by a contract-21
27-
consumer's copy of the same schemas. A consumer switching exhaustively on
28-
`next_action.kind` has to be told, and the floor is how it is told.
29-
30-
**Two routing behaviours change**, and neither is additive:
20+
Runtime contract `23 → 24`. `minimum_control_contract_version` **stays at 21**,
21+
and the `AgentControl` union is byte-identical to v21.
22+
23+
A typed `edit` action was added to that union for setup routing and then
24+
removed. The union is embedded by six durable published schemas — verifier,
25+
agent-handoff, preflight, agent-result, agent-boundary-result, and verify-run —
26+
so widening it widened all six under unchanged identifiers, and five of those
27+
artifacts record no `contract_version` for a consumer holding a stored payload to
28+
disambiguate with. A setup step that needs a file changed routes as a `configure`
29+
command naming the check that confirms it, with the file in `why` and
30+
structurally in `next_actions[].path`.
31+
32+
What v24 does widen is `shipgate.agent_control/v1` itself — new `operation`
33+
values, `decision_source: "setup"`, and closed per-source `decision`
34+
vocabularies. That document is emitted on stdout and never written as an
35+
artifact, so there are no stored envelopes to disambiguate and its new
36+
operations cannot appear in anything a v21 consumer holds.
37+
38+
**One routing behaviour changes**, and it is not additive:
3139

3240
- `init --write` no longer names a runnable `scan` in `next_action` when the
3341
manifest it wrote still holds an unresolved human-owned declaration. Both
@@ -36,10 +44,6 @@ consumer's copy of the same schemas. A consumer switching exhaustively on
3644
published an executable command that would carry an unfilled
3745
`agent.declared_purpose` into a release decision, beside a control state that
3846
authorized nothing (#325).
39-
- `detect --json` reports `setup_incomplete` and hands off to `doctor` on a
40-
workspace that already has a manifest, where it previously said `init`.
41-
`detect` never opens the manifest, so it can neither run `init` usefully there
42-
nor establish that setup is done. See below.
4347

4448
**`detect --json`, `init --json`, and every `doctor --json` payload gain a
4549
`control` field.** It holds the same `shipgate.agent_control/v1` envelope that
@@ -92,24 +96,16 @@ fields `declared_purpose`, `prohibited_actions`, `owner`, `reason`, `expires`,
9296
`confirmation`, and `idempotency`, all route to a human. Anything else — a
9397
tool-source path, a project name — stays coding-agent work.
9498

95-
**`agent control` on a `scan` generation publishes no release verdict.** `scan`
96-
runs the release engine and binds its `report.json`, but its pointer records no
97-
HEAD, no worktree overlay, and no input set, so the generic currency comparison
98-
has nothing to compare and passes vacuously. Reporting the bound verdict on top
99-
of that published a *stale* decision: a clean scan said `passed`, an input
100-
changed, and the same pointer still read cleanly with the same verdict. Binding
101-
the manifest digest alone did not close it either — the manifest is one input
102-
among several, and editing a `tools.json` it references moved the real decision
103-
from `passed` to `insufficient_evidence` while the pointer stayed intact.
104-
105-
So the envelope reports `decision: null` / `decision_source: "none"` for every
106-
scan generation, as it did before this release, and `reason` now states which of
107-
two things is true: the scan binds no reconfirmable snapshot of the inputs it
108-
read, or it bound no machine-readable report at all. That part is worth having —
109-
a bare `decision: null` reads exactly like output produced before any engine ran.
110-
A verdict a reader can check comes from `verify`. Publishing one from `scan`
111-
needs a complete, reconfirmable input snapshot threaded through report generation
112-
and pointer publication; that is a separate change.
99+
**`scan` is not part of this rollout.** `agent control` on a `scan` generation
100+
reports `decision: null` / `decision_source: "none"`, exactly as it did before,
101+
with a `reason` stating that the verdict is *withheld* rather than absent. A
102+
scan pointer records no HEAD, no worktree overlay, and no input set, so no
103+
artifact in that directory can show its verdict still describes the workspace —
104+
editing the manifest, a `tools.json` it references, a policy pack, or a baseline
105+
leaves the pointer reading cleanly. Publishing a verdict from `scan` needs a
106+
complete, reconfirmable input snapshot threaded through report generation and
107+
pointer publication; that is a separate change, and #323's scan half stays open
108+
until it lands. `verify` is where a verdict a reader can check comes from.
113109

114110
**`shipgate.current_control/v1` is unchanged.** An earlier revision of this
115111
branch added an optional `policy_snapshot_path` to `workspace_identity`.

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

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -98,8 +98,7 @@
9898
"370a81cf1c35212584702ca89c5476f3cd6c19aaaf8b4bb9f57c18476f0d13ef",
9999
"4bc3d245f6a12937807ba59d1cae5085664361168233042d00422a43a056789d",
100100
"310e254f2873129355eec23d954c802590115215195d1f3c00348bc10958cc97",
101-
"b75525aad36ac1bfeb500f826dd0b35a8ab5859d814e860b85f3cffaafdd5e80",
102-
"341253ed61e5ce9e4f42fc7d1ab0c4c72edd32aacf941cb8d08e49d95493c59d"
101+
"b75525aad36ac1bfeb500f826dd0b35a8ab5859d814e860b85f3cffaafdd5e80"
103102
]
104103
},
105104
"bootstrap_legacy_sha256": {

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

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,7 @@
2424
"e543320aadab74777133ca591be72dcc910c90c2f881c135ec32c97864276ec9",
2525
"4bde76605784f71eaf6fe57f0c3f4e44e204f10f4eb023edb15424710928894f",
2626
"caba08258bdb5d89b0b2370b02a58f79e2ef26ea2ed36a1c1bd42357322dbbd9",
27-
"8d56a0a026f1ba0b29ead84a660a4a1274757e13f04ecd2ce2069580b4b5e461",
28-
"34ef4bdac90ff7b409eb2254f6b73c52888e92bd9ba44824d6f056c44c2a50ff"
27+
"8d56a0a026f1ba0b29ead84a660a4a1274757e13f04ecd2ce2069580b4b5e461"
2928
],
3029
"references/recipes.md": [
3130
"df5110bfa05eeabd9b918d8902b5c054fa547d1155be61ef6e7d7d63378bf210",
@@ -45,8 +44,7 @@
4544
"09509bbc6fe9b524ef0a756cfe2851000a768ae1b61b6b30d8a932b17768ce89",
4645
"97a8eb98fc560405c690581ac5542b2f94783480f2266af36f566ae12600e2cb",
4746
"936119b52f9de3afbde869a06727f3175e3b3bd25defd6a2c593697fd01de3ca",
48-
"533cf729416bb46a43501962f75a46ed3f3d337d9b082a7fb1ed44118be06203",
49-
"49f71ac4f5b6c83f34caa1e5a7126cf4550d95188725ce37d93b558c6bfae17a"
47+
"533cf729416bb46a43501962f75a46ed3f3d337d9b082a7fb1ed44118be06203"
5048
],
5149
"references/report-reading.md": [
5250
"75a655059f3d45db365c744b0ff82d1c9d69c3638acacf640fd667ae87260d05",

0 commit comments

Comments
 (0)