Skip to content

Commit 0c5f40f

Browse files
fix(evidence): a declaration weaker than its evidence is never silent (#409) (#411)
* fix(evidence): a declaration weaker than its evidence is never silent (#409) Increment 1 of the evidence-first declaration RFC (#410): the monotone declaration rule. Declaring `effect: read` on a tool this scanner itself tagged `external_write` was accepted with zero findings. The pre-existing `inferred_effect_only` gap was closed by the very declaration that contradicted the heuristic which raised it, the action went pass-eligible (0/12 -> 1/12), and the contradicting `risk_tags` stayed in the same report with nothing joining them. The contradiction check already existed and was correct for the claims it could see: `_assess_effect` admits a claim into `contradictory` only when `policy_eligible`, which `domain.py` grants only to typed, high-confidence bases. Heuristic risk hints are deliberately excluded -- a heuristic must never *drive* policy (#357). But one flag governed two different powers. Driving a verdict heuristics rightly cannot. Challenging a human assertion they should: a declaration sitting *below* an observation is not the heuristic gating anything, it is a human statement contradicting something the scan saw. Effect declarations are now monotone. Escalation stays silent. De-escalating past a non-policy-eligible inference raises `declaration_below_inferred_evidence` (report schema 0.35 -> 0.36), a review-level evidence gap naming the declared value, the inferred value, and the hint that produced it. The declaration stays operative and the row never blocks, but the action is not evidence-backed-pass until it is answered -- by raising `effect`, or by the new `action_surface.actions[].override` block naming the `evidence` checked and the `reason` it does not apply. An acknowledged override is accepted (the action is pass-eligible again) and reported as one semantic review concern, so a run carrying one can never read `passed`. Two guards keep the rule from firing where nothing is being asserted. A declaration the source itself corroborates is not challenged (`support.search_kb` declares `read` beside `readOnlyHint: true`, and a keyword reading `financial_write` out of "refund" in its description is the weaker signal). Corroboration never counts the manifest row's own restatements of itself, so a declaration cannot close its own gap. And an override can never silence `conflicting_effect_evidence`: where policy-eligible evidence outranks the declaration, the blocking conflict is unchanged and no acknowledgement attaches. Closes #409. Co-Authored-By: Claude Opus 5 <[email protected]> * review: corroborating source evidence names the row, it does not exempt it Self-review round 1 on #411. The first draft exempted a declaration the source itself corroborates: `support.search_kb` declares `read` and carries `readOnlyHint: true`, so why make a reviewer defend a protocol annotation against a keyword? Because this resolver already refuses to pass on that annotation alone -- with no declaration the same tool is `inferred_effect_only` and not pass-eligible, precisely because a hint outranks it. A declaration that merely restates the annotation must not buy what the annotation could not, or #409's hole moves rather than closes. Worse, the corroboration was drawn from content the tool source supplies about itself, which is not conditioned on `tool_sources[].trust`: an MCP server could assert `readOnlyHint: true` about a destructive tool and a `read` declaration would sail through with zero rows. Corroboration is now named in the row instead -- "source evidence agrees with the declaration (mcp_annotation)" -- which is what makes the override one line to write rather than an investigation to open. Measured cost of dropping the exemption across the whole sample and fixture corpus: two rows, both true, both now carried as overrides in `samples/support_refund_agent` and `samples/ai_generated_refund_pr`, so the shipped samples are the worked example. Also from the review: - An `override` written where the conflict is with policy-eligible evidence was silently discarded. That is the field a blocked reviewer reaches for first, and they got a byte-identical message on re-run. `conflicting_effect_evidence` now says the override does not reach it and why. - `_decision_reason` composed its sentence from three known `reason_counts` keys, so a future review-concern reason would vanish from the sentence whenever an authority or override phrase was present. The unnamed remainder is now counted explicitly. - `SemanticCoverageDecision`'s docstring -- published verbatim as the `description` in the generated report schema -- and the agent contract still described `review_concern_count` as authority-only. - The comparator block now lives entirely inside the guard that gives its locals meaning, dropping a type-checker-only conjunct that read as a real possibility. - The #409 rule, the trust boundary, the ignored override, and the deliberately accepted stale override are each pinned by a test. The `test_weaker_write_declaration_with_inferred_financial_effect_is_ie` canary now asserts the stronger property: `create_refund` declares `write` against a `financial_write` heuristic, so the discarded escalation is on the record instead of being carried only by the policy-evidence gap. Co-Authored-By: Claude Opus 5 <[email protected]> * review: both conflicting branches name an ignored override Self-review round 2 on #411. The read-versus-side-effect conflict is the same user error as the ranked one — a reviewer reaches for `override`, the resolver discards it — so both branches now route through one message builder instead of one of them going quiet. Reworded so the sentence is accurate for both: the conflict is *in* policy-eligible source evidence, which is true whether it outranks the declaration or splits read from side-effect. `docs/passed-verdict-contract.md` enumerates what keeps human review mandatory and did not mention that an acknowledged override joins `unscoped`/`ambient` authority on that list. Swept every sample and fixture manifest for rows the stricter rule newly raises: zero, after the two overrides added in the previous commit. Co-Authored-By: Claude Opus 5 <[email protected]> * review: the instruction names the effect it asks for Self-review round 3 on #411. The `Improve evidence:` line read "Raise action_surface.actions[].effect to the inferred effect this row names" -- and named it nowhere the user could see. Every human surface renders the short per-kind headline (`evidence_gap_headline`), not the row's `why`, so the one artifact carrying `external_communication` was report.json. A published next step that cannot be executed from what it publishes is the #362 failure mode. `expects` now names the value: "Raise action_surface.actions[].effect to 'external_communication', or acknowledge the difference with an override ...". That also settles what `accepted_values` is the vocabulary for -- the field `expects` names -- which was the other half of the complaint. Deriving the value twice is this codebase's recurring defect class, so the comparison lives in one function. `claims_above_declared_effect` is called by the resolver (which needs the claims, to name their sources) and by `strongest_effect_above_declaration`, which the release-decision projection calls for the value alone. A test asserts the instruction and the reason name the same effect. `action_surface_declaration` was spelled eight times across two modules and is now load-bearing for the projection, so it is `DECLARED_EFFECT_SOURCE`. Carrying the value on `SemanticIssue` instead would have added a published field to every semantic issue in the report schema; the CLAUDE.md surface-discipline gate says to default against that when one shared function does the job. Co-Authored-By: Claude Opus 5 <[email protected]> * review: consume the acknowledgement, and project each exception Addresses the four findings on #411. [P1] Consume the acknowledgement in policy applicability. Policy applicability asks exactly what the override answers -- "does the higher heuristic effect apply here?" -- so leaving the acknowledged claim unresolved there traded `declaration_below_inferred_evidence` for `mixed_policy_evidence`: the reviewer followed the row's own instruction and landed on a differently-named `insufficient_evidence`. The override claim now carries `overridden_claim_ids`, and `_non_authoritative_effect_escalation_support`, the action-policy predicates, and capability-policy matching all read that one authored list rather than re-deriving the comparison. The acknowledged fixture reaches `review_required` with zero policy gaps, asserted end to end. [P1] Preserve each override in the reviewer projection. A count is not a review surface. `semantic_coverage.acknowledged_overrides[]` names the action, both readings, the hint source, any source evidence that agrees, and the human's evidence and reason. The packet's section 1 and the PR comment (`SHIP-ACTION-EFFECT-OVERRIDE-ACKNOWLEDGED`) render one row per override. Packet schema 0.12 -> 0.13 and verifier 0.9 -> 0.10, both with forward-reading paths for the frozen shapes: the field is absent there and an empty list is the honest reading. [P2] Reject visually blank override evidence. `strip()` leaves U+200B and U+2060 intact, so an override that renders as nothing to the reviewer it exists for validated, suppressed the mismatch, and restored pass-eligibility. Both fields now require visible content, using the repository's own `has_visible_content` semantics -- moved to `schemas/text.py` so the schema layer can use it without importing `core`, with `core.evidence_actions` re-exporting it. [P2] Keep the public manifest schema aligned with runtime validation. `docs/manifest-v0.1.json` is advertised for live editor validation and accepted both an `override` with no `effect` and blank `evidence`/`reason`. The dependency is published as an `if`/`then`, the visible-content rule as a `pattern` generated from the same code-point table the runtime reads (BMP as `\uXXXX` and astral as literals -- `\u{...}` is ECMA-262-with-u-flag only and Python's `re` rejects it outright), and `tests/test_manifest_schema_parity.py` runs twelve payloads through both validators and requires them to agree. `samples/support_refund_agent` and `samples/ai_generated_refund_pr` already carried the two overrides this rule asks for, so the packet golden now shows the rendered rows. Co-Authored-By: Claude Opus 5 <[email protected]> * test: pin the property that makes consuming acknowledgements safe Policy applicability, action policies, and capability policies all drop the claims an override names. That is only safe because an override can never name a policy-eligible claim -- the resolver refuses to attach one while policy-eligible evidence outranks the declaration, and the recorded set is filtered on `not policy_eligible`. Asserted once at the producer rather than three times at the consumers.
1 parent 109c586 commit 0c5f40f

85 files changed

Lines changed: 15693 additions & 403 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

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

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -188,9 +188,9 @@
188188
"codex_boundary_result_schema_path": "docs/codex-boundary-result-schema.v2.json",
189189
"agent_boundary_result_schema_version": "shipgate.agent_boundary_result/v2",
190190
"agent_boundary_result_schema_path": "docs/agent-boundary-result-schema.v2.json",
191-
"report_schema_version": "0.35",
192-
"packet_schema_version": "0.12",
193-
"verifier_schema_version": "0.9",
191+
"report_schema_version": "0.36",
192+
"packet_schema_version": "0.13",
193+
"verifier_schema_version": "0.10",
194194
"verify_run_schema_version": "shipgate.verify_run/v4",
195195
"verification_plan_schema_version": "shipgate.verification_plan/v1",
196196
"verification_unit_result_schema_version": "shipgate.verification_unit_result/v1",
@@ -480,19 +480,19 @@
480480
"current_control": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/current-control-schema.v1.json",
481481
"agent_control": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/agent-control-schema.v1.json",
482482
"manifest": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/manifest-v0.1.json",
483-
"report": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/report-schema.v0.35.json",
483+
"report": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/report-schema.v0.36.json",
484484
"agent_result": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/agent-result-schema.v3.json",
485485
"agent_boundary_result": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/agent-boundary-result-schema.v2.json",
486486
"codex_boundary_result": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/codex-boundary-result-schema.v2.json",
487-
"verifier": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/verifier-schema.v0.9.json",
487+
"verifier": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/verifier-schema.v0.10.json",
488488
"verify_run": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/verify-run-schema.v4.json",
489489
"verification_plan": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/verification-plan-schema.v1.json",
490490
"verification_unit_result": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/verification-unit-result-schema.v1.json",
491491
"verification_artifact_manifest": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/verification-artifact-manifest-schema.v1.json",
492492
"verification_receipt": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/verification-receipt-schema.v1.json",
493493
"human_authorization": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/human-authorization-schema.v1.json",
494494
"agent_handoff": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/agent-handoff-schema.v7.json",
495-
"packet": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/packet-schema.v0.12.json",
495+
"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",
497497
"capability_lock": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/capability-lock-schema.v0.6.json",
498498
"capability_lock_diff": "https://raw.githubusercontent.com/ThreeMoonsLab/agents-shipgate/main/docs/capability-lock-diff-schema.v0.7.json",

‎AGENTS.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -532,7 +532,7 @@ restate version archaeology here):
532532
- Audit envelopes: `release_decision.contribution_rules[]`, `policy_audit`,
533533
`privacy_audit`, `heuristics_filter` — explanatory, never a second gate
534534

535-
The current schema is [`docs/report-schema.v0.35.json`](docs/report-schema.v0.35.json). Emitted reports carry `report_schema_version: "0.35"`; `surface_exclusions` records every subject a stage removed from the analysed surface and whether the release decision saw it, typed predicate support prevents heuristic evidence from being upgraded by policy severity or block metadata, and verify-native reports bind the content-addressed request and decision. A `passed` result requires a complete root-reachable static binding graph plus complete, conflict-free identity, effect, authority, and applicable-policy evidence for every reachable action. Every release decision explicitly carries `static_analysis_only: true`, `runtime_behavior_verified: false`, and `static_verdict_disclaimer`; packet §1 mirrors them. Binding, semantic, and policy-applicability gaps are not Findings and cannot be suppressed or baselined. See [`docs/passed-verdict-contract.md`](docs/passed-verdict-contract.md), [`docs/verification-reproducibility.md`](docs/verification-reproducibility.md), and [`docs/agent-contract-current.md`](docs/agent-contract-current.md). v0.34 remains frozen at [`docs/report-schema.v0.34.json`](docs/report-schema.v0.34.json).
535+
The current schema is [`docs/report-schema.v0.36.json`](docs/report-schema.v0.36.json). Emitted reports carry `report_schema_version: "0.36"`; `surface_exclusions` records every subject a stage removed from the analysed surface and whether the release decision saw it, typed predicate support prevents heuristic evidence from being upgraded by policy severity or block metadata, and verify-native reports bind the content-addressed request and decision. A `passed` result requires a complete root-reachable static binding graph plus complete, conflict-free identity, effect, authority, and applicable-policy evidence for every reachable action. Every release decision explicitly carries `static_analysis_only: true`, `runtime_behavior_verified: false`, and `static_verdict_disclaimer`; packet §1 mirrors them. Binding, semantic, and policy-applicability gaps are not Findings and cannot be suppressed or baselined. See [`docs/passed-verdict-contract.md`](docs/passed-verdict-contract.md), [`docs/verification-reproducibility.md`](docs/verification-reproducibility.md), and [`docs/agent-contract-current.md`](docs/agent-contract-current.md). v0.35 remains frozen at [`docs/report-schema.v0.35.json`](docs/report-schema.v0.35.json).
536536

537537
**Release gating signal**: prefer `release_decision.decision` (`"blocked" | "review_required" | "insufficient_evidence" | "passed"`) over `summary.status`. The new field is **baseline-aware** — a baseline-matched critical surfaces in `release_decision.review_items` (accepted debt), not `release_decision.blockers`. `summary.status` stays baseline-blind for v0.7 compatibility, so a baseline-matched-only critical produces both `summary.status = "release_blockers_detected"` AND `release_decision.decision = "review_required"` (intentional divergence — see [STABILITY.md](STABILITY.md#release_decisiondecision-vs-summarystatus)). `insufficient_evidence` (added v0.14) signals that the scan saw too many low-confidence tools or source-loader warnings to be trustworthy; consumers that switch on the enum must fall back to `review_required` for unknown future values.
538538

@@ -612,7 +612,7 @@ validation and [`docs/manifest-v0.1.md`](docs/manifest-v0.1.md) for prose.
612612
### Where is the report schema?
613613

614614
Parse `agents-shipgate-reports/report.json` and validate against
615-
[`docs/report-schema.v0.35.json`](docs/report-schema.v0.35.json) (current).
615+
[`docs/report-schema.v0.36.json`](docs/report-schema.v0.36.json) (current).
616616
Older reports (`report_schema_version: "0.10"`) validate against the
617617
frozen [`docs/report-schema.v0.10.json`](docs/report-schema.v0.10.json).
618618
Do not scrape Markdown when JSON is available.
@@ -650,7 +650,7 @@ For the short, current statement of "which fields to read", see [`docs/agent-con
650650
| What | Path | Stable |
651651
|---|---|---|
652652
| Manifest schema | [`docs/manifest-v0.1.json`](docs/manifest-v0.1.json) | `0.1` |
653-
| Report schema (current) | [`docs/report-schema.v0.35.json`](docs/report-schema.v0.35.json) | `0.35` |
653+
| Report schema (current) | [`docs/report-schema.v0.36.json`](docs/report-schema.v0.36.json) | `0.36` |
654654
| Report schema (v0.34 frozen reference) | [`docs/report-schema.v0.34.json`](docs/report-schema.v0.34.json) | `0.34` |
655655
| Report schema (v0.33 frozen reference) | [`docs/report-schema.v0.33.json`](docs/report-schema.v0.33.json) | `0.33` |
656656
| Report schema (v0.32 frozen reference) | [`docs/report-schema.v0.32.json`](docs/report-schema.v0.32.json) | `0.32` |
@@ -688,7 +688,7 @@ For the short, current statement of "which fields to read", see [`docs/agent-con
688688
| Report schema (v0.8 frozen reference) | [`docs/report-schema.v0.8.json`](docs/report-schema.v0.8.json) | `0.8` |
689689
| Report schema (v0.7 frozen reference) | [`docs/report-schema.v0.7.json`](docs/report-schema.v0.7.json) | `0.7` |
690690
| Report schema (v0.6 frozen reference) | [`docs/report-schema.v0.6.json`](docs/report-schema.v0.6.json) | `0.6` |
691-
| Packet schema (Release Evidence Packet, latest) | [`docs/packet-schema.v0.12.json`](docs/packet-schema.v0.12.json) | `0.12` |
691+
| Packet schema (Release Evidence Packet, latest) | [`docs/packet-schema.v0.13.json`](docs/packet-schema.v0.13.json) | `0.13` |
692692
| Agent result schema (current) | [`docs/agent-result-schema.v2.json`](docs/agent-result-schema.v2.json) | `agent_result_v2` |
693693
| Verifier schema (current) | [`docs/verifier-schema.v0.5.json`](docs/verifier-schema.v0.5.json) | `0.5` |
694694
| Agent handoff schema (current) | [`docs/agent-handoff-schema.v5.json`](docs/agent-handoff-schema.v5.json) | `shipgate.agent_handoff/v5` |
@@ -746,7 +746,7 @@ Newer commands (stable intent, flags may still evolve):
746746
| `agents-shipgate registry` | `ingest --attestation <file>` / `query` / `report --bypass` — local capability-release ledger over attestations. |
747747
| `agents-shipgate install-hooks` | Claude Code hooks: PreToolUse trust-root boundary (`ask`/`deny`), PostToolUse trigger nudge, Stop verify. |
748748

749-
### Release Evidence Packet (v0.9)
749+
### Release Evidence Packet (v0.13)
750750

751751
`scan` emits a reviewer-shaped Release Evidence Packet alongside
752752
`report.{md,json}` by default; outputs land at
@@ -758,7 +758,7 @@ NOT prove. Use `--no-packet` / `--packet-format` on `scan`, and
758758
`agents-shipgate evidence-packet --from <packet.json|report.json>` to
759759
re-render. The full packet contract (fixed sections, disclaimers,
760760
`evidence_matrix` rules) lives in
761-
[STABILITY.md §Release Evidence Packet](STABILITY.md#release-evidence-packet-v012)
761+
[STABILITY.md §Release Evidence Packet](STABILITY.md#release-evidence-packet-v013)
762762
and [`docs/agent-contract-current.md`](docs/agent-contract-current.md#read-these-for-release-review).
763763

764764
Exit codes (stable):

‎CHANGELOG.md‎

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

33
## Unreleased
44

5+
- **A declaration weaker than the evidence inferred for it is no longer
6+
silent.** Declaring `effect: read` on a tool this scanner itself tagged
7+
`external_write` was accepted with zero findings: the pre-existing
8+
`inferred_effect_only` gap was closed by the very declaration that
9+
contradicted the heuristic which raised it, the action went pass-eligible,
10+
and the contradicting `risk_tags` stayed in the same report with nothing
11+
joining them
12+
([#409](https://github.com/ThreeMoonsLab/agents-shipgate/issues/409),
13+
Increment 1 of
14+
[#410](https://github.com/ThreeMoonsLab/agents-shipgate/issues/410)).
15+
16+
The contradiction check already existed and was correct for the claims it
17+
could see: `semantic_assessment._assess_effect` admits a claim into
18+
`contradictory` only when `policy_eligible`, and `domain.py` grants that only
19+
to typed, high-confidence bases. Heuristic risk hints are deliberately
20+
excluded — a heuristic must never *drive* policy (#357). But one flag
21+
governed two different powers. **Driving a verdict** heuristics rightly
22+
cannot. **Challenging a human assertion** they should: a declaration sitting
23+
*below* an observation is not the heuristic gating anything, it is a human
24+
statement contradicting something the scan saw, which is precisely what a
25+
reviewer needs surfaced.
26+
27+
Effect declarations are now **monotone**. Adding or escalating relative to
28+
the evidence stays silent — a reviewer calling an action more dangerous than
29+
the evidence proves needs no ceremony. De-escalating past a non-policy-
30+
eligible inference raises `declaration_below_inferred_evidence`
31+
(report schema `0.35` → `0.36`): a review-level evidence gap naming the
32+
declared value, the inferred value, and the hint that produced it. The
33+
declaration remains the operative effect — heuristics still do not drive the
34+
verdict, and this row never blocks — but the action is not evidence-backed-
35+
pass until it is answered.
36+
37+
Two answers close it, and the reviewer owns the choice: raise `effect` to
38+
what was inferred — the row names the exact value, so `Improve evidence:`
39+
reads *Raise action_surface.actions[].effect to 'external_communication'* —
40+
or acknowledge the difference with the new
41+
`action_surface.actions[].override` block, which names the `evidence` you
42+
checked and the `reason` it does not apply. An acknowledged override is
43+
accepted — the action is pass-eligible again — and is reported as one
44+
semantic review concern, so a run carrying one can never read `passed`. It is
45+
a human assertion like every other declaration: the gap's template carries
46+
`suggested_patch_kind: manual`, `auto_apply: false`,
47+
`requires_human_review: true`, and `apply-patches` never writes it.
48+
49+
An override never silences `conflicting_effect_evidence`: where
50+
**policy-eligible** evidence outranks the declaration, the existing blocking
51+
conflict is unchanged, no acknowledgement attaches, and the row now says the
52+
override does not reach it — a reviewer blocked there reaches for the field,
53+
and silently discarding it left them re-running against an unchanged message.
54+
55+
Source evidence that **agrees** with the declared value does not exempt the
56+
row. A first draft exempted it — `support.search_kb` declares `read` and
57+
carries `readOnlyHint: true`, so why make a reviewer defend a protocol
58+
annotation against a keyword? Because this resolver already refuses to pass
59+
on that annotation alone: with no declaration the same tool is
60+
`inferred_effect_only` and not pass-eligible, precisely because a hint
61+
outranks it. A declaration that merely restates the annotation must not buy
62+
what the annotation could not, or #409's hole moves rather than closes — and
63+
the corroboration would be drawn from content the tool source supplies about
64+
itself, which is not conditioned on `tool_sources[].trust` (an MCP server can
65+
assert `readOnlyHint: true` about a destructive tool). The agreeing source is
66+
**named in the row** instead — "source evidence agrees with the declaration
67+
(mcp_annotation)" — which is what makes the override one line to write. The
68+
manifest row's own `effect`, `risk_tags`, `scopes`, and `override` never
69+
count as agreeing evidence for itself.
70+
71+
`samples/support_refund_agent` carries the two overrides this rule asks it
72+
for, so the shipped sample is the worked example.
73+
74+
**The acknowledgement is consumed everywhere the question is asked.** Policy
75+
applicability asks exactly what the override answers — "does the higher
76+
heuristic effect apply here?" — so leaving the acknowledged claim unresolved
77+
there traded `declaration_below_inferred_evidence` for
78+
`mixed_policy_evidence`: the reviewer followed the row's own instruction and
79+
landed on a differently-named `insufficient_evidence`. The override claim
80+
carries `overridden_claim_ids`, and `_non_authoritative_effect_escalation_support`,
81+
the action-policy predicates, and capability-policy matching all read that one
82+
authored list rather than re-deriving the comparison. The acknowledged fixture
83+
now reaches `review_required` with zero policy gaps.
84+
85+
**Each exception is a row, not a count.** `semantic_coverage.acknowledged_overrides[]`
86+
(report schema `0.36`, packet `0.12` → `0.13`, verifier `0.9` → `0.10`) names
87+
the action, both readings, the hint source, any source evidence that agrees,
88+
and the human's evidence and reason. The packet's §1 and the PR comment
89+
(`SHIP-ACTION-EFFECT-OVERRIDE-ACKNOWLEDGED`) render one row per override, so
90+
a reviewer reads the exceptions rather than a number. Frozen `0.12` packets
91+
and `0.9` verifier artifacts still read forward; the field is absent there and
92+
an empty list is the honest reading.
93+
94+
**Blank-looking answers are rejected.** `str.strip()` leaves U+200B and U+2060
95+
intact, so an override whose `evidence` and `reason` render as nothing to the
96+
reviewer they exist for validated, suppressed the mismatch, and restored
97+
pass-eligibility. Both fields now require visible content — the repository's
98+
own `has_visible_content` semantics, moved to `schemas/text.py` so the schema
99+
layer can use it without importing `core`, covering whitespace, controls,
100+
bidi marks, and every Default_Ignorable code point.
101+
102+
**The published manifest schema says what the CLI enforces.**
103+
`docs/manifest-v0.1.json` is advertised for live editor validation and
104+
accepted both an `override` with no `effect` and blank `evidence`/`reason`,
105+
which `model_validate` rejects — telling a user their manifest is valid and
106+
then refusing it. The dependency is published as an `if`/`then`, the
107+
visible-content rule as a `pattern` generated from the same code-point table
108+
the runtime check reads, and `tests/test_manifest_schema_parity.py` runs
109+
twelve payloads through both validators and requires them to agree.
110+
111+
Known limitation: an override whose inferred evidence later stops firing
112+
stays accepted and unreported. Distinguishing a stale exception from one that
113+
never applied needs the `basis: confirmed:<derivation_id>` pin from increment
114+
4 of #410, which is where it belongs.
115+
5116
- **Every evidence gap now labels a tool the way a reader can use, in every gap
6117
kind.** `EvidenceGap.subject` is a display label — identity lives in
7118
`subject_id` — but the policy evidence gaps (every row of

0 commit comments

Comments
 (0)