Kjell Tore Guttormsen
0bf07295c2
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.
65 lines
3.2 KiB
Markdown
65 lines
3.2 KiB
Markdown
# 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:
|
|
|
|
1. **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.
|
|
2. **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/`.
|
|
3. **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.
|
|
4. **Fail-secure / fail-closed stays total.** `guard()` and `screen_output` must
|
|
never turn an un-scannable or malformed input into a silent persist.
|
|
5. **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.
|
|
6. **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.
|
|
7. **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
|
|
|
|
```bash
|
|
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.
|