Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

feat(gates): sweep the provenance corpus on pre-push

Browse Source 
Nothing ran validate-provenance.sh across the real corpus, so the 36
INFOs it reported for Research doc mismatches were found only by a
manual loop, and a FAIL tier would have been inert. Add
scripts/check-provenance-corpus.sh, which runs the validator over every
plugins/*/.apm/skills/*/ that has references/sources.md.

Exit 1 when any skill FAILs, naming them; INFO lines are printed but do
not fail; exit 2 when the gate cannot run (missing validator, validator
exit 2, or no skills found). Registered as a pre-push hook shaped like
check-scope-walkup-sync, documented in docs/spec/gates.md, and pinned in
test-adr0020-contract.sh's list of repo-authored hooks.

Refs: #121
ADR: 0028
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EGHFJextYtVQseaHPDDhxB
This commit is contained in:
Defame1297
2026-09-21 17:29:20 +00:00
parent 740f631d1d
commit a1f9fa9091
5 changed files with 338 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
docs/spec/gates.md
View File

@@ -42,7 +42,7 @@ is checked out. Push one ref at a time when the gate matters.
## The pre-push gate
Eight hooks, grouped below by what they guard rather than by the order `.pre-commit-config.yaml` declares them in.
Nine hooks, grouped below by what they guard rather than by the order `.pre-commit-config.yaml` declares them in.
**Core checks**
@@ -66,6 +66,7 @@ version-blind, so a stale key deploys fine (see [apm gates](#apm-gates)).
| Hook | Guards |
|---|---|
| `check-apm-agents-valid` | runs `factory-audit`'s `validate.sh` over every real `plugins/*/.apm/agents/*.agent.md` (see [Agent files](#agent-files-take-the-description-gates-not-the-body-gate)) |
| `check-provenance-corpus` | runs `factory-audit`'s `validate-provenance.sh` over every real `plugins/*/.apm/skills/*/` that has a `references/sources.md`, failing on any FAIL (see [The provenance corpus sweep](#the-provenance-corpus-sweep-adr-0028)) |
**apm's own gates**
@@ -576,6 +577,38 @@ follows symlinks with `find -L` because vale does.
on `files:` patterns that match single markdown files, and only the `-d "$arg"` branch mirrors a
directory. The exposed caller is the hand-invoked `vale-wrap.sh <dir>`.
## The provenance corpus sweep (ADR-0028)
`check-provenance-corpus` runs `validate-provenance.sh` over every real
`plugins/*/.apm/skills/*/` directory that has a `references/sources.md`, and fails on any FAIL. The set
is discovered by glob, not counted, so a new skill is covered the moment it grows a `sources.md`, and
**discovering zero skills is an error, not a pass**.
The hook exists because nothing else ran the validator over the real corpus.
`check-scope-walkup-sync` invokes it only against synthetic `mktemp` fixtures, and `factory-audit`'s
bats suite does the same. So a `Research doc:` naming the wrong file, or a slug absent from its
Research registry, could only be found by hand-running the validator in a loop. That is how 36
mismatches (#121) reported INFO while every gate stayed green. ADR-0028 promotes "the check ran and
found a mismatch" from INFO to FAIL; without a caller across the corpus that FAIL tier would be inert.
It reuses the validators' exit contract (see
[the three exit tiers](#the-three-exit-tiers-of-factory-audits-validators)) and keeps the tiers apart:
| Exit | Means |
|---|---|
| **0** | every skill validated. INFO-only findings are printed, never swallowed |
| **1** | at least one skill FAILed. The summary line names the failing skills |
| **2** | the gate could not run: the validator is missing, a skill's validator run exited 2 ("not auditable"), or no skill with a `references/sources.md` was found |
A validator exit 2 is reported as a gate error, not as a FAIL about that skill: it says the audit never
happened, and the skill has not been shown to be wrong.
An unresolvable `Research doc:` path stays INFO by design, because a deployed copy of a skill outside
this repo will not carry the research docs (see `skill-file-structure.md`'s `sources.md` exemption).
This repo's own corpus is audited from the authoring source, where every path resolves, so an INFO
printed here is worth reading. Needs no network; needs `python3`, which the validator's own preflight
names.
## Current retrofit status
The ADR-0020 gates ship hot, with no baseline file — a shrinking baseline was considered and