1
0
Fork 0

docs(readme,security,contributing): meet the repo standard — 0 ERROR

The per-repo gate flagged four ERRORs and two WARNs. Fixed, in the order the
work actually gets done in:

MISSING
- `## Honest limitations` -> `## Known limitations`, `## Out-of-scope
  (documented boundary)` -> `## Non-goals`. Both sections existed under names
  no reader or agent scans for; the contract wants predictable top-level
  headings. Pointers followed: the in-README anchor, SECURITY.md's out-of-scope
  preamble, CONTRIBUTING.md's scope section, and the consumer-facing
  docs/ADOPTION-BRIEF.md. Historical records (CHANGELOG, docs/PLAN.md,
  docs/OKF-INGESTION-BRIEF.md) keep the name they were written with.

WEAKENING
- README now opens with one line identical to the forge description, above the
  badges. That is the only place a machine can check description == README.
- Forge description shortened 207 -> 178 codepoints (bound 180), and the same
  string written to pyproject's `description` so the fourth copy cannot drift.

The tests badge is dropped, not updated. `tests-699_passing` as a static image
is a claim dressed as evidence: there is no CI runner on this forge, so nothing
verifies it. Replaced with the honest substitute in Install — the single command
that runs the suite from a clean clone, stated together with the fact that
nothing runs it automatically.

Two WARNs deliberately left standing:
- H1 `# llm-ingestion-guard` != repo name. The register itself records
  llm-ingestion-guard as "a package, not a repo"; the H1 names what you pip
  install. Renaming the repo is the operator's call, not this commit's.
- The `Status` badge trips the same claim-badge regex, but `alpha` asserts
  maturity, not a run — the same reason version/license/platform are exempt.
  Measured false positive in the gate's classifier, reported upstream.
This commit is contained in:
Kjell Tore Guttormsen 2026-08-03 21:59:07 +02:00
commit 0bf07295c2
5 changed files with 20 additions and 11 deletions

View file

@ -5,7 +5,7 @@ especially one converging on Google's Open Knowledge Format (OKF v0.1) — and n
to decide **when** and **where** to add a write-time ingestion guard.
**Status of the guard:** `v0.2` (alpha). Stdlib-only core, framework-agnostic.
Public API may still change. Read the honest-limitations section before you rely
Public API may still change. Read the known-limitations section before you rely
on it.
This brief is self-contained: you can plan an inclusion from it alone. Every
@ -194,10 +194,10 @@ untrusted ingest path goes live*, wired at the point where enriched content is
committed. If today you only have first-party ingest, note the guard as a
dependency to add when (not if) you open an external/inbox/received-bundle path.
## 8. Honest limitations (read these — a green scan is not "safe")
## 8. Known limitations (read these — a green scan is not "safe")
Conceding these is itself a control. The full list is in the guard's `README.md`
("Honest limitations"); the ones that matter most for a wiki/second-brain:
("Known limitations"); the ones that matter most for a wiki/second-brain:
- **Semantic / factual poisoning is invisible** to lexicon + entropy: a
plausible-but-wrong concept (wrong join-path, wrong metric, wrong runbook step)
@ -225,7 +225,7 @@ Conceding these is itself a control. The full list is in the guard's `README.md`
## 9. Where to read more (in the guard repo)
- `README.md` — usage, the full contract, and the complete honest-limitations list.
- `README.md` — usage, the full contract, and the complete known-limitations list.
- `docs/BRIEF.md` — design rationale and the nearest-neighbour survey (§11).
- `docs/OKF-INGESTION-BRIEF.md` — the OKF threat-surface analysis (frontmatter,
`resource`, cross-link graph, reserved names, provenance) the adapter implements.