evidgate 0.9.2.post1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- evidgate-0.9.2.post1/LICENSE +21 -0
- evidgate-0.9.2.post1/PKG-INFO +221 -0
- evidgate-0.9.2.post1/README.md +203 -0
- evidgate-0.9.2.post1/evidgate/__init__.py +6 -0
- evidgate-0.9.2.post1/evidgate/cli.py +599 -0
- evidgate-0.9.2.post1/evidgate/core/__init__.py +10 -0
- evidgate-0.9.2.post1/evidgate/core/builtin.py +105 -0
- evidgate-0.9.2.post1/evidgate/core/check.py +175 -0
- evidgate-0.9.2.post1/evidgate/core/evidence.py +243 -0
- evidgate-0.9.2.post1/evidgate/core/gate.py +154 -0
- evidgate-0.9.2.post1/evidgate/core/packs.py +90 -0
- evidgate-0.9.2.post1/evidgate/core/suggest.py +185 -0
- evidgate-0.9.2.post1/evidgate/ledger/__init__.py +4 -0
- evidgate-0.9.2.post1/evidgate/ledger/table.py +135 -0
- evidgate-0.9.2.post1/evidgate/packs/build.yaml +25 -0
- evidgate-0.9.2.post1/evidgate/packs/figures.yaml +29 -0
- evidgate-0.9.2.post1/evidgate/packs/repo.yaml +17 -0
- evidgate-0.9.2.post1/evidgate/plugins/__init__.py +1 -0
- evidgate-0.9.2.post1/evidgate/plugins/artifact.py +303 -0
- evidgate-0.9.2.post1/evidgate/plugins/prose.py +181 -0
- evidgate-0.9.2.post1/evidgate.egg-info/PKG-INFO +221 -0
- evidgate-0.9.2.post1/evidgate.egg-info/SOURCES.txt +27 -0
- evidgate-0.9.2.post1/evidgate.egg-info/dependency_links.txt +1 -0
- evidgate-0.9.2.post1/evidgate.egg-info/entry_points.txt +2 -0
- evidgate-0.9.2.post1/evidgate.egg-info/top_level.txt +1 -0
- evidgate-0.9.2.post1/pyproject.toml +50 -0
- evidgate-0.9.2.post1/setup.cfg +4 -0
- evidgate-0.9.2.post1/tests/test_evidgate.py +944 -0
- evidgate-0.9.2.post1/tests/test_skill_commands.py +92 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 BringCo
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,221 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: evidgate
|
|
3
|
+
Version: 0.9.2.post1
|
|
4
|
+
Summary: Evidence gates for deliverables: every claim gets a command, an exit code, and a ledger line.
|
|
5
|
+
Author: BringCo
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/BringCo/evidgate
|
|
8
|
+
Keywords: evidence,gate,audit,ledger,reproducibility,documentation
|
|
9
|
+
Classifier: Programming Language :: Python :: 3
|
|
10
|
+
Classifier: Operating System :: OS Independent
|
|
11
|
+
Classifier: Topic :: Documentation
|
|
12
|
+
Classifier: Topic :: Software Development :: Testing
|
|
13
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
14
|
+
Requires-Python: >=3.9
|
|
15
|
+
Description-Content-Type: text/markdown
|
|
16
|
+
License-File: LICENSE
|
|
17
|
+
Dynamic: license-file
|
|
18
|
+
|
|
19
|
+
# evidgate
|
|
20
|
+
|
|
21
|
+
[](https://pypi.org/project/evidgate/)
|
|
22
|
+
[](https://pypi.org/project/evidgate/)
|
|
23
|
+
[](LICENSE)
|
|
24
|
+
[](https://github.com/BringCo/evidgate/actions/workflows/ci.yml)
|
|
25
|
+
|
|
26
|
+
**English** · [简体中文](README.zh-CN.md)
|
|
27
|
+
|
|
28
|
+
**A command-line tool that turns a deliverable's claims into checks — and refuses to
|
|
29
|
+
load a check that cannot go red.**
|
|
30
|
+
|
|
31
|
+
It does not judge whether the content is right. It judges whether the evidence you claim
|
|
32
|
+
for it is real, still there, and reproducible, then writes that judgement into one ledger
|
|
33
|
+
you can hand to somebody else.
|
|
34
|
+
|
|
35
|
+
One ledger line = one check = the command that ran = the exit code it produced = the
|
|
36
|
+
point where you resume = the decision to release or block.
|
|
37
|
+
|
|
38
|
+
## The failure this exists to catch
|
|
39
|
+
|
|
40
|
+
A check that reports green for the wrong reason is worse than no check: you stop
|
|
41
|
+
looking. Three shapes of that, all encountered while building this:
|
|
42
|
+
|
|
43
|
+
**1. The command never ran.** On Windows there is no `grep`. Running a missing command
|
|
44
|
+
exits `1` — and `exit:1` is exactly how you assert "grep found nothing". So a check that
|
|
45
|
+
never executed reported PASS, indefinitely. evidgate now tells "the command did not run"
|
|
46
|
+
apart from "the command ran and returned this code"; only the second can pass.
|
|
47
|
+
|
|
48
|
+
**2. The check had nothing to check.** A 172-file manifest where every entry was a
|
|
49
|
+
source made the `figures` pack report **3 PASS with 100% coverage**: with no derivative
|
|
50
|
+
there is nothing to compare, so every rule held vacuously. There is now a `GF0` check
|
|
51
|
+
whose only job is to fail when a manifest contains no derivative at all.
|
|
52
|
+
|
|
53
|
+
**3. Nobody ever asked the check to fail.** This one is silent by construction: a rule
|
|
54
|
+
written straight into CI and never run against a broken version is an untested rule.
|
|
55
|
+
So `counter` — *how does this check go red* — is a required field, and a check without
|
|
56
|
+
it is refused at load time, not at run time.
|
|
57
|
+
|
|
58
|
+
## How it differs
|
|
59
|
+
|
|
60
|
+
| | typical linter | checklist (human) | evidgate |
|
|
61
|
+
|---|---|---|---|
|
|
62
|
+
| Who decides pass | the rule | a person ticking a box | the command + its exit code |
|
|
63
|
+
| What proves it | nothing | nothing | command, exit code, output tail, artifact hash, timestamp |
|
|
64
|
+
| If the rule silently stops working | silent | silent | `evidgate mutate` reports "detection 1/1" or "NOT caught" |
|
|
65
|
+
| Where "what is left" lives | nowhere | another sheet | the same ledger line |
|
|
66
|
+
| Can a rule exist with no way to fail | yes | yes | **refused at load time** |
|
|
67
|
+
|
|
68
|
+
`counter` is a required field, so **a gate that cannot fail is not a gate, it is a wish.**
|
|
69
|
+
|
|
70
|
+
## 30 seconds
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
pip install evidgate
|
|
74
|
+
cd <your project>
|
|
75
|
+
evidgate init --dir . # writes evidgate.yaml; picks a file that actually exists
|
|
76
|
+
evidgate doctor --dir . # yaml parseable? every command resolvable? — before blaming the project
|
|
77
|
+
evidgate run --dir . # ledger + verdicts; exit 1 = blocked
|
|
78
|
+
|
|
79
|
+
# straight from a clone, no install needed (stdlib only):
|
|
80
|
+
./bin/evidgate --version
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
If `doctor` prints `BAD`, fix that first — the most common failure is a `method` whose
|
|
84
|
+
command is not on `PATH`, or a `method` that needs `shell:` and does not declare it.
|
|
85
|
+
|
|
86
|
+
Running the bundled three-domain example:
|
|
87
|
+
|
|
88
|
+
```console
|
|
89
|
+
$ evidgate run --dir examples/mixed
|
|
90
|
+
evidgate 0.9.2.post1 · mixed-delivery (fictional) · 7 checks
|
|
91
|
+
D1 FAIL(红) 草稿里的绝对化词带范围或检索日期 ─ -exit 2 (want 0) | got: L3 [首次实现] 本方案首次实现全自动估价流程。 | [absolutes] 1 finding(s) (exit 2)
|
|
92
|
+
D2 DIFF(黄) 草稿里的统计数字带口径 ─ -exit 3 (want 0) | got: L3 抽样调参后误差降低 18.4%。 | [numeral_scope] 1 finding(s) (exit 3)
|
|
93
|
+
A1 PASS 产物存在且非空 ─ +exit 0 (want 0) ; +regex OK ─ \d -> 3
|
|
94
|
+
A2 FAIL(红) 正本与其派生副本逐字节一致 ─ -exit 1 (want 0)
|
|
95
|
+
C1 PASS 代码单测全绿 ─ +exit 0 (want 0)
|
|
96
|
+
C2 PASS 源码里没有明文密钥 ─ +exit 0 (want 0) ; +not_contains OK:api_key ; +not_contains OK:secret_key
|
|
97
|
+
C3 PASS 源码里没有残留 TODO ─ +exit 1 (want 1)
|
|
98
|
+
|
|
99
|
+
PASS 4 · DIFF(黄) 1 · FAIL(红) 2 · 待补 0 · 未覆盖 0 | coverage 7/7 (100.0%)
|
|
100
|
+
RELEASE BLOCKED blocked by D1, A2
|
|
101
|
+
note: PASS 表示「证据存在且可复现」,不表示数值本身正确。
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
The example deliberately mixes Chinese check names with English output: the shipped
|
|
105
|
+
`prose` rules target Chinese drafts, and one ledger holds either language.
|
|
106
|
+
|
|
107
|
+
Red blocks the release. Yellow goes to a confirmation list. **待补 is never "done".**
|
|
108
|
+
Exit code 1 means blocked — a non-zero run cannot be reported as a pass.
|
|
109
|
+
|
|
110
|
+
## What it finds on real things
|
|
111
|
+
|
|
112
|
+
| target | size | result |
|
|
113
|
+
|---|---|---|
|
|
114
|
+
| Mature open-source repos | 8 | **0 findings** |
|
|
115
|
+
| Personal deliverable repos | 4 | **3 real defects** |
|
|
116
|
+
| A real paper draft | 581 sentences | 222 findings before calibration → **32** |
|
|
117
|
+
|
|
118
|
+
The zero is the boundary, not a weakness: mature projects do not commit credentials or
|
|
119
|
+
leave `.bak` files behind. Personal repos produced a crash on a broken symlink, the
|
|
120
|
+
vacuous-green manifest above, and a `suggest` that could not see `.fig`/`.dia`/`.dat` as
|
|
121
|
+
figure sources. This tool is for **the last look before you hand something over**.
|
|
122
|
+
|
|
123
|
+
## Who this is for
|
|
124
|
+
|
|
125
|
+
- You are about to hand a draft, a report, an application package or a build directory to
|
|
126
|
+
someone who will ask "where did this number come from?"
|
|
127
|
+
- An agent produced the deliverable, and "done" arrived as one sentence with no command
|
|
128
|
+
behind it. The same holds across your own windows: a claim from another context is
|
|
129
|
+
something to check, not to trust.
|
|
130
|
+
- You already run tests and linters, and none of them leave a record of *what was
|
|
131
|
+
verified, with which command, when*.
|
|
132
|
+
|
|
133
|
+
## Who it is not for
|
|
134
|
+
|
|
135
|
+
- **Content correctness** — whether the number is right or the argument holds.
|
|
136
|
+
- **Typography, terminology, AI-tone linting** — [Vale](https://vale.sh/) and
|
|
137
|
+
`deliverable-qa` have far more rules for that.
|
|
138
|
+
- **Auditing mature repositories** — expect zero findings.
|
|
139
|
+
- **Approval workflows** — no roles, no multi-user sign-off; this is a single-user CLI.
|
|
140
|
+
|
|
141
|
+
## Install as an agent skill
|
|
142
|
+
|
|
143
|
+
`skill/evidgate/SKILL.md` is a written instruction set for an agent: when to reach for
|
|
144
|
+
the tool, the first-run commands, what a check looks like, and the three shapes of false
|
|
145
|
+
green. Copy or link the directory into your agent's skills folder:
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
cp -r skill/evidgate ~/.hermes/skills/ # Hermes
|
|
149
|
+
ln -s "$PWD/skill/evidgate" ~/.hermes/skills/evidgate # or link instead of copying
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
After that, an instruction as short as "run evidgate before you tell me it is done" has
|
|
153
|
+
something concrete behind it. `evidgate run` exits 1 when blocked, and an agent that
|
|
154
|
+
reports success off a non-zero run is doing precisely what this tool exists to catch.
|
|
155
|
+
|
|
156
|
+
## Commands
|
|
157
|
+
|
|
158
|
+
```bash
|
|
159
|
+
evidgate init --dir <proj> # starter evidgate.yaml
|
|
160
|
+
evidgate suggest --dir <proj> [--write] # read the disk, name the pack that applies
|
|
161
|
+
evidgate doctor --dir <proj> # yaml + command resolvability, before you blame the project
|
|
162
|
+
evidgate run --dir <proj> [--only C1,P2] # run + rebuild the ledger; exit 1 = blocked
|
|
163
|
+
evidgate resume --dir <proj> # rerun only unresolved checks
|
|
164
|
+
evidgate report --dir <proj> # gate_report.md: table, yellows, unverified, verdict
|
|
165
|
+
evidgate mutate --dir <proj> --baseline A --mutant B [--only C1] # does the check actually go red?
|
|
166
|
+
evidgate prose-init --dir <proj> --file <draft> # append the Chinese prose checks (P1..P5)
|
|
167
|
+
evidgate artifact-init --dir <proj> --out artifacts.json # scan a directory into a manifest
|
|
168
|
+
evidgate artifact-update --dir <proj> # recompute an artifact's own md5 (never source_md5)
|
|
169
|
+
evidgate artifact-stamp --dir <proj> --path P # after regenerating: record the source hash
|
|
170
|
+
evidgate pack [list|show <name>] # what a pack expands to
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
## Documentation
|
|
174
|
+
|
|
175
|
+
| doc | covers |
|
|
176
|
+
|---|---|
|
|
177
|
+
| [Writing a check](docs/writing-a-check.md) | `method` forms, `optional`, every `expect` clause, the evidence self-check, adding your own domain |
|
|
178
|
+
| [Artifact plugin](docs/artifact-plugin.md) | the five manifest rules, why `stale` hashes instead of comparing mtimes, `orphan` scope and cost, the one writer of `source_md5` |
|
|
179
|
+
| [Prose plugin](docs/prose-plugin.md) | the five Chinese rules, the calibration story, sentence boundaries, `EVIDGATE_EVIDENCE` |
|
|
180
|
+
| [Shell and Windows](docs/shell-and-windows.md) | why no shell by default, Git Bash discovery, the Windows false green |
|
|
181
|
+
| [suggest and packs](docs/suggest-and-packs.md) | the first command, the three packs and their parameters |
|
|
182
|
+
|
|
183
|
+
## Examples
|
|
184
|
+
|
|
185
|
+
All examples are **fictional**; every defect is planted on purpose.
|
|
186
|
+
|
|
187
|
+
- `examples/mixed/` — prose + artifact + code in one ledger (the output above)
|
|
188
|
+
- `examples/` — a Chinese draft, six checks, 2 PASS / 2 DIFF / 2 FAIL
|
|
189
|
+
- `examples/figures/` — one SVG source, three derivatives, all three `stale` verdicts
|
|
190
|
+
side by side
|
|
191
|
+
- `examples/artifact/` — one markdown source with two derivatives, four asset checks
|
|
192
|
+
|
|
193
|
+
Mutation demo:
|
|
194
|
+
|
|
195
|
+
```bash
|
|
196
|
+
./bin/evidgate mutate --dir examples --baseline examples/base --mutant examples/mut --only C1
|
|
197
|
+
# detection power: 1/1
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
## Scope
|
|
201
|
+
|
|
202
|
+
**Does not** verify that a reference exists or says what you claim — use
|
|
203
|
+
[refchecker](https://github.com/markrussinovich/refchecker) for that.
|
|
204
|
+
**Does not** detect AI-generated text, judge typography, or decide whether a number is
|
|
205
|
+
correct.
|
|
206
|
+
**Does** check that the evidence you claim for your own statements, numbers and
|
|
207
|
+
artifacts is real, reproducible and recorded — in whatever domain your command can
|
|
208
|
+
observe.
|
|
209
|
+
|
|
210
|
+
`prose` is a writing prompt, not a proofreader. Measured honestly: of 22 problems found
|
|
211
|
+
by reading a draft by hand, and 26 reported by the rules, the overlap was small.
|
|
212
|
+
|
|
213
|
+
## Attribution
|
|
214
|
+
|
|
215
|
+
Evidence triples and three-state verdicts follow obra/superpowers'
|
|
216
|
+
`verification-before-completion`; the evidence-gate framing follows TestifySec Pushgate.
|
|
217
|
+
What is new here is listed in [ATTRIBUTION.md](ATTRIBUTION.md).
|
|
218
|
+
|
|
219
|
+
## License
|
|
220
|
+
|
|
221
|
+
MIT
|
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
# evidgate
|
|
2
|
+
|
|
3
|
+
[](https://pypi.org/project/evidgate/)
|
|
4
|
+
[](https://pypi.org/project/evidgate/)
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
[](https://github.com/BringCo/evidgate/actions/workflows/ci.yml)
|
|
7
|
+
|
|
8
|
+
**English** · [简体中文](README.zh-CN.md)
|
|
9
|
+
|
|
10
|
+
**A command-line tool that turns a deliverable's claims into checks — and refuses to
|
|
11
|
+
load a check that cannot go red.**
|
|
12
|
+
|
|
13
|
+
It does not judge whether the content is right. It judges whether the evidence you claim
|
|
14
|
+
for it is real, still there, and reproducible, then writes that judgement into one ledger
|
|
15
|
+
you can hand to somebody else.
|
|
16
|
+
|
|
17
|
+
One ledger line = one check = the command that ran = the exit code it produced = the
|
|
18
|
+
point where you resume = the decision to release or block.
|
|
19
|
+
|
|
20
|
+
## The failure this exists to catch
|
|
21
|
+
|
|
22
|
+
A check that reports green for the wrong reason is worse than no check: you stop
|
|
23
|
+
looking. Three shapes of that, all encountered while building this:
|
|
24
|
+
|
|
25
|
+
**1. The command never ran.** On Windows there is no `grep`. Running a missing command
|
|
26
|
+
exits `1` — and `exit:1` is exactly how you assert "grep found nothing". So a check that
|
|
27
|
+
never executed reported PASS, indefinitely. evidgate now tells "the command did not run"
|
|
28
|
+
apart from "the command ran and returned this code"; only the second can pass.
|
|
29
|
+
|
|
30
|
+
**2. The check had nothing to check.** A 172-file manifest where every entry was a
|
|
31
|
+
source made the `figures` pack report **3 PASS with 100% coverage**: with no derivative
|
|
32
|
+
there is nothing to compare, so every rule held vacuously. There is now a `GF0` check
|
|
33
|
+
whose only job is to fail when a manifest contains no derivative at all.
|
|
34
|
+
|
|
35
|
+
**3. Nobody ever asked the check to fail.** This one is silent by construction: a rule
|
|
36
|
+
written straight into CI and never run against a broken version is an untested rule.
|
|
37
|
+
So `counter` — *how does this check go red* — is a required field, and a check without
|
|
38
|
+
it is refused at load time, not at run time.
|
|
39
|
+
|
|
40
|
+
## How it differs
|
|
41
|
+
|
|
42
|
+
| | typical linter | checklist (human) | evidgate |
|
|
43
|
+
|---|---|---|---|
|
|
44
|
+
| Who decides pass | the rule | a person ticking a box | the command + its exit code |
|
|
45
|
+
| What proves it | nothing | nothing | command, exit code, output tail, artifact hash, timestamp |
|
|
46
|
+
| If the rule silently stops working | silent | silent | `evidgate mutate` reports "detection 1/1" or "NOT caught" |
|
|
47
|
+
| Where "what is left" lives | nowhere | another sheet | the same ledger line |
|
|
48
|
+
| Can a rule exist with no way to fail | yes | yes | **refused at load time** |
|
|
49
|
+
|
|
50
|
+
`counter` is a required field, so **a gate that cannot fail is not a gate, it is a wish.**
|
|
51
|
+
|
|
52
|
+
## 30 seconds
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
pip install evidgate
|
|
56
|
+
cd <your project>
|
|
57
|
+
evidgate init --dir . # writes evidgate.yaml; picks a file that actually exists
|
|
58
|
+
evidgate doctor --dir . # yaml parseable? every command resolvable? — before blaming the project
|
|
59
|
+
evidgate run --dir . # ledger + verdicts; exit 1 = blocked
|
|
60
|
+
|
|
61
|
+
# straight from a clone, no install needed (stdlib only):
|
|
62
|
+
./bin/evidgate --version
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
If `doctor` prints `BAD`, fix that first — the most common failure is a `method` whose
|
|
66
|
+
command is not on `PATH`, or a `method` that needs `shell:` and does not declare it.
|
|
67
|
+
|
|
68
|
+
Running the bundled three-domain example:
|
|
69
|
+
|
|
70
|
+
```console
|
|
71
|
+
$ evidgate run --dir examples/mixed
|
|
72
|
+
evidgate 0.9.2.post1 · mixed-delivery (fictional) · 7 checks
|
|
73
|
+
D1 FAIL(红) 草稿里的绝对化词带范围或检索日期 ─ -exit 2 (want 0) | got: L3 [首次实现] 本方案首次实现全自动估价流程。 | [absolutes] 1 finding(s) (exit 2)
|
|
74
|
+
D2 DIFF(黄) 草稿里的统计数字带口径 ─ -exit 3 (want 0) | got: L3 抽样调参后误差降低 18.4%。 | [numeral_scope] 1 finding(s) (exit 3)
|
|
75
|
+
A1 PASS 产物存在且非空 ─ +exit 0 (want 0) ; +regex OK ─ \d -> 3
|
|
76
|
+
A2 FAIL(红) 正本与其派生副本逐字节一致 ─ -exit 1 (want 0)
|
|
77
|
+
C1 PASS 代码单测全绿 ─ +exit 0 (want 0)
|
|
78
|
+
C2 PASS 源码里没有明文密钥 ─ +exit 0 (want 0) ; +not_contains OK:api_key ; +not_contains OK:secret_key
|
|
79
|
+
C3 PASS 源码里没有残留 TODO ─ +exit 1 (want 1)
|
|
80
|
+
|
|
81
|
+
PASS 4 · DIFF(黄) 1 · FAIL(红) 2 · 待补 0 · 未覆盖 0 | coverage 7/7 (100.0%)
|
|
82
|
+
RELEASE BLOCKED blocked by D1, A2
|
|
83
|
+
note: PASS 表示「证据存在且可复现」,不表示数值本身正确。
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
The example deliberately mixes Chinese check names with English output: the shipped
|
|
87
|
+
`prose` rules target Chinese drafts, and one ledger holds either language.
|
|
88
|
+
|
|
89
|
+
Red blocks the release. Yellow goes to a confirmation list. **待补 is never "done".**
|
|
90
|
+
Exit code 1 means blocked — a non-zero run cannot be reported as a pass.
|
|
91
|
+
|
|
92
|
+
## What it finds on real things
|
|
93
|
+
|
|
94
|
+
| target | size | result |
|
|
95
|
+
|---|---|---|
|
|
96
|
+
| Mature open-source repos | 8 | **0 findings** |
|
|
97
|
+
| Personal deliverable repos | 4 | **3 real defects** |
|
|
98
|
+
| A real paper draft | 581 sentences | 222 findings before calibration → **32** |
|
|
99
|
+
|
|
100
|
+
The zero is the boundary, not a weakness: mature projects do not commit credentials or
|
|
101
|
+
leave `.bak` files behind. Personal repos produced a crash on a broken symlink, the
|
|
102
|
+
vacuous-green manifest above, and a `suggest` that could not see `.fig`/`.dia`/`.dat` as
|
|
103
|
+
figure sources. This tool is for **the last look before you hand something over**.
|
|
104
|
+
|
|
105
|
+
## Who this is for
|
|
106
|
+
|
|
107
|
+
- You are about to hand a draft, a report, an application package or a build directory to
|
|
108
|
+
someone who will ask "where did this number come from?"
|
|
109
|
+
- An agent produced the deliverable, and "done" arrived as one sentence with no command
|
|
110
|
+
behind it. The same holds across your own windows: a claim from another context is
|
|
111
|
+
something to check, not to trust.
|
|
112
|
+
- You already run tests and linters, and none of them leave a record of *what was
|
|
113
|
+
verified, with which command, when*.
|
|
114
|
+
|
|
115
|
+
## Who it is not for
|
|
116
|
+
|
|
117
|
+
- **Content correctness** — whether the number is right or the argument holds.
|
|
118
|
+
- **Typography, terminology, AI-tone linting** — [Vale](https://vale.sh/) and
|
|
119
|
+
`deliverable-qa` have far more rules for that.
|
|
120
|
+
- **Auditing mature repositories** — expect zero findings.
|
|
121
|
+
- **Approval workflows** — no roles, no multi-user sign-off; this is a single-user CLI.
|
|
122
|
+
|
|
123
|
+
## Install as an agent skill
|
|
124
|
+
|
|
125
|
+
`skill/evidgate/SKILL.md` is a written instruction set for an agent: when to reach for
|
|
126
|
+
the tool, the first-run commands, what a check looks like, and the three shapes of false
|
|
127
|
+
green. Copy or link the directory into your agent's skills folder:
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
cp -r skill/evidgate ~/.hermes/skills/ # Hermes
|
|
131
|
+
ln -s "$PWD/skill/evidgate" ~/.hermes/skills/evidgate # or link instead of copying
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
After that, an instruction as short as "run evidgate before you tell me it is done" has
|
|
135
|
+
something concrete behind it. `evidgate run` exits 1 when blocked, and an agent that
|
|
136
|
+
reports success off a non-zero run is doing precisely what this tool exists to catch.
|
|
137
|
+
|
|
138
|
+
## Commands
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
evidgate init --dir <proj> # starter evidgate.yaml
|
|
142
|
+
evidgate suggest --dir <proj> [--write] # read the disk, name the pack that applies
|
|
143
|
+
evidgate doctor --dir <proj> # yaml + command resolvability, before you blame the project
|
|
144
|
+
evidgate run --dir <proj> [--only C1,P2] # run + rebuild the ledger; exit 1 = blocked
|
|
145
|
+
evidgate resume --dir <proj> # rerun only unresolved checks
|
|
146
|
+
evidgate report --dir <proj> # gate_report.md: table, yellows, unverified, verdict
|
|
147
|
+
evidgate mutate --dir <proj> --baseline A --mutant B [--only C1] # does the check actually go red?
|
|
148
|
+
evidgate prose-init --dir <proj> --file <draft> # append the Chinese prose checks (P1..P5)
|
|
149
|
+
evidgate artifact-init --dir <proj> --out artifacts.json # scan a directory into a manifest
|
|
150
|
+
evidgate artifact-update --dir <proj> # recompute an artifact's own md5 (never source_md5)
|
|
151
|
+
evidgate artifact-stamp --dir <proj> --path P # after regenerating: record the source hash
|
|
152
|
+
evidgate pack [list|show <name>] # what a pack expands to
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
## Documentation
|
|
156
|
+
|
|
157
|
+
| doc | covers |
|
|
158
|
+
|---|---|
|
|
159
|
+
| [Writing a check](docs/writing-a-check.md) | `method` forms, `optional`, every `expect` clause, the evidence self-check, adding your own domain |
|
|
160
|
+
| [Artifact plugin](docs/artifact-plugin.md) | the five manifest rules, why `stale` hashes instead of comparing mtimes, `orphan` scope and cost, the one writer of `source_md5` |
|
|
161
|
+
| [Prose plugin](docs/prose-plugin.md) | the five Chinese rules, the calibration story, sentence boundaries, `EVIDGATE_EVIDENCE` |
|
|
162
|
+
| [Shell and Windows](docs/shell-and-windows.md) | why no shell by default, Git Bash discovery, the Windows false green |
|
|
163
|
+
| [suggest and packs](docs/suggest-and-packs.md) | the first command, the three packs and their parameters |
|
|
164
|
+
|
|
165
|
+
## Examples
|
|
166
|
+
|
|
167
|
+
All examples are **fictional**; every defect is planted on purpose.
|
|
168
|
+
|
|
169
|
+
- `examples/mixed/` — prose + artifact + code in one ledger (the output above)
|
|
170
|
+
- `examples/` — a Chinese draft, six checks, 2 PASS / 2 DIFF / 2 FAIL
|
|
171
|
+
- `examples/figures/` — one SVG source, three derivatives, all three `stale` verdicts
|
|
172
|
+
side by side
|
|
173
|
+
- `examples/artifact/` — one markdown source with two derivatives, four asset checks
|
|
174
|
+
|
|
175
|
+
Mutation demo:
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
./bin/evidgate mutate --dir examples --baseline examples/base --mutant examples/mut --only C1
|
|
179
|
+
# detection power: 1/1
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
## Scope
|
|
183
|
+
|
|
184
|
+
**Does not** verify that a reference exists or says what you claim — use
|
|
185
|
+
[refchecker](https://github.com/markrussinovich/refchecker) for that.
|
|
186
|
+
**Does not** detect AI-generated text, judge typography, or decide whether a number is
|
|
187
|
+
correct.
|
|
188
|
+
**Does** check that the evidence you claim for your own statements, numbers and
|
|
189
|
+
artifacts is real, reproducible and recorded — in whatever domain your command can
|
|
190
|
+
observe.
|
|
191
|
+
|
|
192
|
+
`prose` is a writing prompt, not a proofreader. Measured honestly: of 22 problems found
|
|
193
|
+
by reading a draft by hand, and 26 reported by the rules, the overlap was small.
|
|
194
|
+
|
|
195
|
+
## Attribution
|
|
196
|
+
|
|
197
|
+
Evidence triples and three-state verdicts follow obra/superpowers'
|
|
198
|
+
`verification-before-completion`; the evidence-gate framing follows TestifySec Pushgate.
|
|
199
|
+
What is new here is listed in [ATTRIBUTION.md](ATTRIBUTION.md).
|
|
200
|
+
|
|
201
|
+
## License
|
|
202
|
+
|
|
203
|
+
MIT
|