Kjell Tore Guttormsen 0bf07295c2 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.

2026-08-03 21:59:07 +02:00

3.2 KiB

Raw Blame History

Contributing

Thanks for looking. This is a small, security-focused library; contributions are welcome as long as they hold the invariants below. When in doubt, open a discussion before a large change.

Where the project lives

Canonical repository: Forgejo — git.fromaitochitta.com/open/llm-ingestion-pipeline-security.
There is no GitHub repository; do not open pull requests there.

Non-negotiable invariants

A change that breaks one of these will not be merged, however useful it is otherwise:

Test-first (the Iron Law). No production code without a failing test first. Add the red test, then the minimal implementation that makes it green. A pure refactor keeps the existing suite green unchanged as its proof of no behaviour change.
Stdlib-only core. pyproject.toml [project].dependencies stays []. The deterministic core imports only the standard library. Extraction / ML / judge libraries (pypdf, python-docx, python-pptx, openpyxl, ML detectors) live only in an extra ([dev], [ml], [judge]), never in core dependencies. The upload front-end and its parsers are dev-scoped showcase code under tests/.
Report / mutation separation. Detectors report findings; they never mutate the scanned text. neutralize is the only defanging surface and it is opt-in and byte-identical on clean input.
Fail-secure / fail-closed stays total. guard() and screen_output must never turn an un-scannable or malformed input into a silent persist.
Calibration lives in one place. Tunable thresholds (entropy floors, MAX_SCAN_CHARS, disposition ranks, cognitive-load lengths, severities) belong in src/llm_ingestion_guard/calibration.py, so the planned Node/TS port can mirror the exact numbers. Do not scatter magic numbers back into detectors.
The shared lexicon is never split. injection_lexicon.json is the single pattern source of truth for both the Python core and the future TS port.
Never ship a live payload. Build attack strings in tests from chr(0x…) fragments so the gitleaks pre-commit hook and the repo itself stay clean. Never bypass the hook with --no-verify.

Running the tests

python -m venv .venv
.venv/bin/pip install -e '.[dev]'        # dev extra: extraction libs for the front-end showcase
PYTHONPATH=src .venv/bin/pytest          # the full suite must be green

The suite is the release gate: a change is not done until the whole suite is green.

Commit style

Conventional Commits: type(scope): description (e.g. feat(egress): decode-rescan feeds base64 plaintext to secret-egress).
No trailers. Do not add Co-Authored-By / Signed-off-by / tool-attribution trailers.
Keep commits scoped: one logical change per commit; version bumps sync every file that names the version in the same commit.

Scope and honest limits

New detection is welcome, but the project ships its limitations as a control (see README.md → Known limitations). If a change narrows a stated gap, update that section. If it introduces a new deliberate boundary, document it there rather than leaving a silent miss. Absolute claims ("catches all …", "cannot be bypassed") do not belong in this codebase.

3.2 KiB Raw Blame History