Skip to content

Commit d73d64b

Browse files
fix(evidence): a declaration cannot discharge a category it does not cover (#409)
Three follow-ups to #411, each a defect that shipped with the monotone declaration rule. **Effects are risk-ordered; their obligations are not.** `claims_above_declared_effect` compared `_EFFECT_RANK` alone, so declaring `financial_write` over an inferred `external_communication` read as escalation and stayed silent. `financial_write` obliges approval, audit, and idempotency — but not confirmation, which is exactly what communicating outward requires. Reproduced against `main`: `pass_eligible_actions: 1 of 1`, `gap_count: 0`, and no `SHIP-ACTION-EXTERNAL-COMMUNICATION-AUDIT-MISSING`, while the external-write risk tag sat untouched in the same report. A declaration now accounts for an observation only when it ranks at or above it *and* obliges at least that observation's built-in controls. The obligations move into `BUILTIN_EFFECT_OBLIGATIONS`, pinned to the four inline control branches by a test that walks each entry through a real scan rather than by a refactor of gate-critical code. Coverage also reads every policy-eligible claim instead of the `effect` field alone: `risk_tags: [financial_action]` produces a policy-eligible `financial_write` claim and applies the financial-write controls, so a heuristic reading the same effect is already accounted for — which is also the remedy for the cross-category case, and why the two `escalation is silent` fixtures now carry a `risk_tags` entry. **The two comparators disagreed.** `_non_authoritative_effect_escalation_support` still compared `ACTION_EFFECT_RANK`, which orders `write` and `privileged_data_access` opposite to `_EFFECT_RANK` — so a declaration could read as covered by the declaration rule and raise `mixed_policy_evidence` on the same action, a verdict no override could reach. Both now call `declaration_covers`, which requires *both* orders to agree. Picking one would have loosened an existing gate path or contradicted the #409 rule; the conjunction is a strict superset of the predicate it replaces, so nothing that gated before stops gating. **Four published schema documents were mutated in place.** `declaration_below_inferred_evidence` was written into `packet-schema.v0.12`, `verifier-schema.v0.9`, `capability-lock-schema.v0.6`, and `capability-lock-diff-schema.v0.7` while each kept its version identifier — and the two capability-lock documents had no successor version at all, so a consumer pinned to any of the four rejects artifacts that document is supposed to describe. `generate_schemas.py --check` cannot catch this: it proves committed == generated, never that a content change moved the version. All four are restored byte-for-byte; the capability lock advances 0.6 -> 0.7 and its diff 0.7 -> 0.8; and a lock written under 0.6 is advanced on read rather than rejected, which the bump would otherwise have done to every committed `capabilities.lock.json` (the normalizer handled only 0.1-0.4). Also: the row names every uncovered observation rather than the strongest alone, so a reviewer is not asked to acknowledge evidence the row never showed them; and the published remedy is true of its state — `strongest_effect_above_declaration` becomes `effect_remedy_instruction`, which names the missing controls instead of telling a reviewer to raise an effect that already outranks the observation. Co-Authored-By: Claude Opus 5 <[email protected]>
1 parent 0c5f40f commit d73d64b

35 files changed

Lines changed: 3788 additions & 82 deletions

‎.well-known/agents-shipgate.json‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -288,8 +288,8 @@
288288
"scenario": "scenario.json",
289289
"governance_benchmark_result": "benchmark/agent-pr-governance/results/result.json"
290290
},
291-
"capability_lock_schema_version": "0.6",
292-
"capability_lock_diff_schema_version": "0.7",
291+
"capability_lock_schema_version": "0.7",
292+
"capability_lock_diff_schema_version": "0.8",
293293
"preflight_schema_version": "0.4",
294294
"attestation_schema_version": "0.5",
295295
"registry_schema_version": "0.4",
@@ -494,8 +494,8 @@
494494
"agent_handoff": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/agent-handoff-schema.v7.json",
495495
"packet": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/packet-schema.v0.13.json",
496496
"preflight": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/preflight-schema.v0.4.json",
497-
"capability_lock": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/capability-lock-schema.v0.6.json",
498-
"capability_lock_diff": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/capability-lock-diff-schema.v0.7.json",
497+
"capability_lock": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/capability-lock-schema.v0.7.json",
498+
"capability_lock_diff": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/capability-lock-diff-schema.v0.8.json",
499499
"governance_benchmark_catalog": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/governance-benchmark-catalog-schema.v0.2.json",
500500
"governance_benchmark_result": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/governance-benchmark-result-schema.v0.2.json",
501501
"feedback": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/feedback-schema.v0.1.json",

‎AGENTS.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -697,8 +697,8 @@ For the short, current statement of "which fields to read", see [`docs/agent-con
697697
| Host-grants baseline schema | [`docs/host-grants-baseline-schema.v0.2.json`](docs/host-grants-baseline-schema.v0.2.json) | `0.2` |
698698
| Host-grants drift schema | [`docs/host-grants-drift-schema.v0.2.json`](docs/host-grants-drift-schema.v0.2.json) | `0.2` |
699699
| Capability standard | [`docs/capability-standard.md`](docs/capability-standard.md) | `0.5` |
700-
| Capability lock schema | [`docs/capability-lock-schema.v0.6.json`](docs/capability-lock-schema.v0.6.json) | `0.6` |
701-
| Capability lock diff schema | [`docs/capability-lock-diff-schema.v0.7.json`](docs/capability-lock-diff-schema.v0.7.json) | `0.7` |
700+
| Capability lock schema | [`docs/capability-lock-schema.v0.7.json`](docs/capability-lock-schema.v0.7.json) | `0.7` |
701+
| Capability lock diff schema | [`docs/capability-lock-diff-schema.v0.8.json`](docs/capability-lock-diff-schema.v0.8.json) | `0.8` |
702702
| Governance benchmark catalog schema | [`docs/governance-benchmark-catalog-schema.v0.2.json`](docs/governance-benchmark-catalog-schema.v0.2.json) | `0.2` |
703703
| Governance benchmark result schema | [`docs/governance-benchmark-result-schema.v0.2.json`](docs/governance-benchmark-result-schema.v0.2.json) | `0.2` |
704704
| Check catalog | [`docs/checks.json`](docs/checks.json) | regenerated each release |

‎CHANGELOG.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,56 @@
22

33
## Unreleased
44

5+
- **A declaration cannot discharge a category it does not cover, and a
6+
published schema keeps its bytes.** Three follow-ups to the monotone
7+
declaration rule, each a defect that shipped with it
8+
([#409](https://github.com/ThreeMoonsLab/agents-shipgate/issues/409),
9+
[#411](https://github.com/ThreeMoonsLab/agents-shipgate/pull/411)).
10+
11+
*Effects are risk-ordered; their obligations are not.* The monotone
12+
comparison read the effect rank alone, so declaring `financial_write` over an
13+
inferred `external_communication` read as escalation and stayed silent —
14+
`financial_write` requires approval, audit, and idempotency but **not**
15+
confirmation, which is exactly what communicating outward requires. The
16+
action reported pass-eligible with no gap and no
17+
`SHIP-ACTION-EXTERNAL-COMMUNICATION-AUDIT-MISSING` while its external-write
18+
risk tag sat untouched in the same report. A declaration now accounts for an
19+
observation only when it ranks at or above it *and* obliges at least that
20+
observation's built-in controls, from the new `BUILTIN_EFFECT_OBLIGATIONS`
21+
table — pinned to the branches it mirrors by a test that walks each entry
22+
through a real scan. Coverage also reads every policy-eligible claim rather
23+
than the `effect` field alone, so a `risk_tags: [financial_action]` entry
24+
accounts for an inferred `financial_write` exactly as the control evaluator
25+
already treats it.
26+
27+
*The two comparators disagreed.* The declaration rule compared `_EFFECT_RANK`
28+
while `_non_authoritative_effect_escalation_support` compared
29+
`ACTION_EFFECT_RANK`, and the two order `write` and `privileged_data_access`
30+
oppositely — so a declaration could read as covered in one place and raise
31+
`mixed_policy_evidence` in the other, a verdict no override could reach. Both
32+
now call `declaration_covers`, which requires *both* orders to agree; nothing
33+
that gated before stops gating.
34+
35+
*Four published schema documents were mutated in place.* The new
36+
`declaration_below_inferred_evidence` value was written into
37+
`packet-schema.v0.12.json`, `verifier-schema.v0.9.json`,
38+
`capability-lock-schema.v0.6.json`, and `capability-lock-diff-schema.v0.7.json`
39+
while they kept their version identifiers — and the two capability-lock
40+
documents had no successor version at all, so a consumer pinned to any of the
41+
four rejected artifacts that document is supposed to describe.
42+
`generate_schemas.py --check` cannot catch this: it proves committed ==
43+
generated, never that a content change moved the version. All four are
44+
restored byte-for-byte, the capability lock advances `0.6` → `0.7` and its
45+
diff `0.7` → `0.8`, and a lock written under `0.6` is advanced on read rather
46+
than rejected — the normalizer handled only `0.1`–`0.4`, so the bump would
47+
otherwise have orphaned every committed `capabilities.lock.json`.
48+
49+
Also: the row now names *every* uncovered observation rather than the
50+
strongest one alone, so a reviewer is not asked to acknowledge evidence the
51+
row never showed them; and the published remedy is true of its state —
52+
"raise the effect" is not printed where the declared effect already outranks
53+
the observation.
54+
555
- **A declaration weaker than the evidence inferred for it is no longer
656
silent.** Declaring `effect: read` on a tool this scanner itself tagged
757
`external_write` was accepted with zero findings: the pre-existing

‎STABILITY.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,48 @@ for reproducible CI.
1313

1414
---
1515

16+
<a id="migration-note-unreleased-effect-coverage"></a>
17+
18+
## Migration Note: unreleased — effect coverage, and the schemas that stayed frozen
19+
20+
Two capability schemas move: `capability_lock_schema_version` `0.6` → `0.7` and
21+
`capability_lock_diff_schema_version` `0.7` → `0.8`. `report_schema_version`
22+
(`0.36`), `packet_schema_version` (`0.13`), `verifier_schema_version` (`0.10`),
23+
`contract_version`, and the manifest `version: "0.1"` are unchanged.
24+
25+
**Four published documents are restored to the bytes they were published with.**
26+
`declaration_below_inferred_evidence` had been written into
27+
`docs/packet-schema.v0.12.json`, `docs/verifier-schema.v0.9.json`,
28+
`docs/capability-lock-schema.v0.6.json`, and
29+
`docs/capability-lock-diff-schema.v0.7.json` while each kept its version
30+
identifier. A consumer pinned to any of them was rejecting artifacts that
31+
document is supposed to describe. The value now reaches only the current
32+
document of each family, and the two capability schemas — which had no
33+
successor version at all — gain one.
34+
35+
**A lock written under `0.6` still loads.** It is advanced to `0.7` on read, the
36+
way a `0.12` packet and a `0.9` verifier artifact already are. Nothing needs
37+
regenerating.
38+
39+
**A declaration accounts for an inferred observation on two conditions, not
40+
one.** It must rank at or above the observation under both published effect
41+
orders, *and* oblige at least that observation's built-in controls. Rank alone
42+
is not enough: `financial_write` outranks `external_communication` but requires
43+
no confirmation, which is what communicating outward requires. A repository
44+
declaring a higher-risk effect across categories — `financial_write` on a tool
45+
inferred to communicate externally — now raises
46+
`declaration_below_inferred_evidence` where it was previously silent, and the
47+
row names the controls rather than telling the reviewer to raise an effect that
48+
is already higher. Coverage reads every policy-eligible claim on the action, so
49+
a `risk_tags: [financial_action]` entry accounts for an inferred
50+
`financial_write` exactly as the built-in control evaluator already treats it.
51+
52+
Nothing that gated before stops gating: the policy-applicability predicate now
53+
asks the same question, and its new form is a strict superset of the rank
54+
comparison it replaces.
55+
56+
---
57+
1658
<a id="migration-note-unreleased-gap-subject-labels"></a>
1759

1860
## Migration Note: unreleased — every gap subject is a label, never a raw id

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,8 @@
4444
"cc468647434d12be45819de4db6ece8a860010b44c31ba3586038067eb3357af",
4545
"3e10877198eead17338d54810ef7dc32317fa1b1013b54acccc1c2e9a94f53e4",
4646
"86a0e4a2b3711d3684305f5d9b2e61a9968e44472dcc67c3e7d3b2a84b965568",
47-
"54f7edb69fe52eb1edac386575b400feb046b149c7e0020b85ab1dde0c35d854"
47+
"54f7edb69fe52eb1edac386575b400feb046b149c7e0020b85ab1dde0c35d854",
48+
"9f6714e1756f117098cd3f63c9671b62fcdf04a74700959aa380a81c0efb21e7"
4849
],
4950
"prompts/add-shipgate-to-repo.md": [
5051
"ea3c37cfbbd42c40d164abfe21d468a3a5550d5384125f94a53c947dea6b4b2a",

‎adoption-kits/claude-code-skill/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,7 @@ For non-GitHub CI (GitLab, CircleCI, Jenkins, Azure Pipelines, Buildkite, Bitbuc
9090
- **Report JSON**: `report_schema_version: "0.36"`. Read `release_decision.decision` first. A `passed` decision requires a complete root-reachable static binding graph plus complete, conflict-free identity, effect, and authority evidence for every reachable action; it does not prove runtime behavior. Preserve `release_decision.static_analysis_only=true`, `runtime_behavior_verified=false`, and `static_verdict_disclaimer` in summaries. Read `release_decision.evidence_coverage.binding_coverage`, `semantic_coverage`, `identity_coverage`, and `policy_gap_count`, then work every `evidence_gaps[].next_action` in order. Binding, semantic, and policy-applicability gaps are not Findings and cannot be suppressed, baselined, severity-overridden, cleared by `--no-heuristics`, or satisfied by `human_ack`; binding, effect, and authority declarations are human assertions and must never be auto-written. Use `tool_catalog[]` for diagnostics and `tool_inventory[]` for the proven reachable surface, and read `surface_exclusions` for what the run removed from analysis — a `newly_unbound_tool` row is a capability this change introduced that no check judged. The current schema is [`docs/report-schema.v0.36.json`](https://github.com/ThreeMoonsLab/agents-shipgate/blob/main/docs/report-schema.v0.36.json); v0.35 is a frozen compatibility reference. See the [current agent contract](https://github.com/ThreeMoonsLab/agents-shipgate/blob/main/docs/agent-contract-current.md), [verification identity contract](https://github.com/ThreeMoonsLab/agents-shipgate/blob/main/docs/verification-reproducibility.md), and [evidence-backed passed contract](https://github.com/ThreeMoonsLab/agents-shipgate/blob/main/docs/passed-verdict-contract.md).
9191
These binding-backed fields require runtime contract v13; the unambiguous `AgentControl` projection requires runtime contract v14. A contract-v12 CLI emits the frozen v0.30 report and must not be described using the v0.31 binding claim.
9292
- **Release Evidence Packet**: `agents-shipgate-reports/packet.{md,json,html}` (and `packet.pdf` with the `[pdf]` extras) is a supporting/provisional reviewer artifact. Packet v0.13 projects the verification request and decision IDs plus binding and semantic coverage; it never creates a second gate. See [`docs/packet-schema.v0.13.json`](https://github.com/ThreeMoonsLab/agents-shipgate/blob/main/docs/packet-schema.v0.13.json) and [STABILITY.md §Release Evidence Packet](https://github.com/ThreeMoonsLab/agents-shipgate/blob/main/STABILITY.md#release-evidence-packet-v013).
93-
- **Capability standard**: `agents-shipgate capability export` emits a stable static capability lock (`capability_lock_schema_version: "0.6"`) and `agents-shipgate capability diff` emits a stable semantic diff (`capability_lock_diff_schema_version: "0.7"`). These artifacts implement capability standard v0.5, are supporting/provisional and non-gating, exclude runtime trace evidence, and are documented in [`docs/capability-standard.md`](https://github.com/ThreeMoonsLab/agents-shipgate/blob/main/docs/capability-standard.md).
93+
- **Capability standard**: `agents-shipgate capability export` emits a stable static capability lock (`capability_lock_schema_version: "0.7"`) and `agents-shipgate capability diff` emits a stable semantic diff (`capability_lock_diff_schema_version: "0.8"`). These artifacts implement capability standard v0.5, are supporting/provisional and non-gating, exclude runtime trace evidence, and are documented in [`docs/capability-standard.md`](https://github.com/ThreeMoonsLab/agents-shipgate/blob/main/docs/capability-standard.md).
9494
- **Governance benchmark**: `benchmark/agent-pr-governance/cases.yaml` and `scripts/run_governance_benchmark.py` are the stable research benchmark substrate (`governance_benchmark_result_schema_version: "0.2"`), not a release gate. See [`docs/governance-benchmark.md`](https://github.com/ThreeMoonsLab/agents-shipgate/blob/main/docs/governance-benchmark.md).
9595
- **Single source of truth for the contract**: [`docs/agent-contract-current.md`](https://github.com/ThreeMoonsLab/agents-shipgate/blob/main/docs/agent-contract-current.md). When the schema bumps, that file updates first.
9696
- **Exit codes**: `0` pass, `2` config error, `3` parse error, `4` other error, `20` strict-mode gate failure.

‎docs/INDEX.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -97,8 +97,10 @@ A single entry point for human readers and AI agents walking the `docs/` tree.
9797
- [`attestation-schema.v0.2.json`](attestation-schema.v0.2.json) — frozen v0.2 attestation reference
9898
- [`attestation-schema.v0.1.json`](attestation-schema.v0.1.json) — frozen v0.1 attestation reference
9999
- [`registry-schema.v0.2.json`](registry-schema.v0.2.json) — frozen v0.2 registry reference
100-
- [`capability-lock-schema.v0.6.json`](capability-lock-schema.v0.6.json) — current JSON Schema for `capabilities.lock.json`; carries typed semantic evidence and remains non-gating
101-
- [`capability-lock-diff-schema.v0.7.json`](capability-lock-diff-schema.v0.7.json) — current JSON Schema for semantic capability-lock diff artifacts; remains non-gating
100+
- [`capability-lock-schema.v0.7.json`](capability-lock-schema.v0.7.json) — current JSON Schema for `capabilities.lock.json`; carries typed semantic evidence and remains non-gating
101+
- [`capability-lock-schema.v0.6.json`](capability-lock-schema.v0.6.json) — frozen v0.6 reference; a v0.6 lock still loads and is advanced on read
102+
- [`capability-lock-diff-schema.v0.8.json`](capability-lock-diff-schema.v0.8.json) — current JSON Schema for semantic capability-lock diff artifacts; remains non-gating
103+
- [`capability-lock-diff-schema.v0.7.json`](capability-lock-diff-schema.v0.7.json) — frozen v0.7 reference
102104
- [`capability-lock-schema.v0.5.json`](capability-lock-schema.v0.5.json) — frozen v0.5 binding-hash reference
103105
- [`capability-lock-diff-schema.v0.6.json`](capability-lock-diff-schema.v0.6.json) — frozen v0.6 diff reference
104106
- [`capability-lock-schema.v0.2.json`](capability-lock-schema.v0.2.json) — frozen v0.2 capability-lock reference

‎docs/agent-contract-current.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -231,8 +231,8 @@ Downstream repos generated with
231231
- Current preflight schema: `0.4` — [`docs/preflight-schema.v0.4.json`](preflight-schema.v0.4.json)
232232
- Current downstream local agent contract schema: `10`
233233
- Current capability standard: `0.5` — [`docs/capability-standard.md`](capability-standard.md)
234-
- Current capability lock schema: `0.6` — [`docs/capability-lock-schema.v0.6.json`](capability-lock-schema.v0.6.json)
235-
- Current capability lock diff schema: `0.7` — [`docs/capability-lock-diff-schema.v0.7.json`](capability-lock-diff-schema.v0.7.json)
234+
- Current capability lock schema: `0.7` — [`docs/capability-lock-schema.v0.7.json`](capability-lock-schema.v0.7.json)
235+
- Current capability lock diff schema: `0.8` — [`docs/capability-lock-diff-schema.v0.8.json`](capability-lock-diff-schema.v0.8.json)
236236
- Current attestation schema: `0.5` — [`docs/attestation-schema.v0.5.json`](attestation-schema.v0.5.json)
237237
- Current registry schema: `0.4` — [`docs/registry-schema.v0.4.json`](registry-schema.v0.4.json)
238238
- Current org evidence bundle schema: `shipgate.org_evidence_bundle/v2` — [`docs/org-evidence-bundle-schema.v2.json`](org-evidence-bundle-schema.v2.json)

‎docs/capability-lock-diff-schema.v0.7.json‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1131,7 +1131,6 @@
11311131
"missing_effect_evidence",
11321132
"inferred_effect_only",
11331133
"conflicting_effect_evidence",
1134-
"declaration_below_inferred_evidence",
11351134
"missing_authority_evidence",
11361135
"partial_authority_evidence",
11371136
"conflicting_authority_evidence",

0 commit comments

Comments
 (0)