docs(readme): show the test command, and stop calling a shipped phase planned

Two defects on the published surface, both measured this session rather than
assumed.

org-ops' census 07 found no test command inside a fenced block in our README,
and the finding is true: the string "pytest" did not appear in the file at all.
A stranger could install the library but could not confirm it works. The block
now names the command, and says the thing the command alone would not: it needs
a clone, because the wheel packages only src/llm_ingestion_okf and tests/ lives
at the repository root. The 589-test count and the run date are measured, not
carried over.

Running org-ops' own A5 criterion ("no claim on the surface is untrue") against
ourselves found the second one. The status paragraph said phases 1 and 2 are
implemented and phases 3-4 are planned, while profiles.py:701 has shipped
STRICT_V1 since phase 3 landed. The Roadmap section and the profile table were
already consistent with phase 3 being done, so the stale claim sat alone in the
one paragraph a reader meets first.

Fixing only the first would have repeated the most expensive finding we have
recorded: writing a trap down is not running it.

Verified with the instrument org-ops supplied, against this branch:
  awk '/^```/{f=!f; next} f' README.md \
    | grep -icE 'npm (run )?test|node --test|pytest|vitest|jest|make test|bats'
  -> 1 (was 0)

Docs only. No release, no tag, no pin movement: the guard pin and the paired
install tags are untouched, and the open release decision stays open.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UgzRG5EGPk72Mj4JN4uhQS
This commit is contained in:
Kjell Tore Guttormsen 2026-08-13 21:09:16 +02:00
commit bd522a1f61

View file

@ -2,16 +2,19 @@
Shared OKF (Open Knowledge Format) ingestion library: spec-based connectors, bundle inbox, and external-bundle import. Security delegated to llm-ingestion-guard.
Status: phases 1 and 2 are implemented. Phase 1 (spec-based ingestion) covers
Status: phases 13 are implemented. Phase 1 (spec-based ingestion) covers
manifest validation, the `file`/`sql`/`http` connectors, deterministic
materialization, index generation, and the golden fixture suite under
`examples/`. Phase 2 adds the bundle inbox (`process_inbox`) and
external-bundle import (`import_bundle`), both against an **injected** persist
gate, with `llm_ingestion_okf.guard_adapter` wiring that gate to the real
guard (see below). One phase-2 item is deliberately outstanding: binary
extraction (`pdf`/`docx`/`xlsx` behind the `[extract]` extra) is unimplemented,
so those types are rejected fail-fast. Phases 34 are planned (see
`docs/plan/`).
guard (see below). Phase 3 makes the bundle contract configurable, so types,
layers, frontmatter sets, index shape, and reserved-file policy are carried by
a profile rather than by constants (see [Upstream OKF
versions](#upstream-okf-versions)). One phase-2 item is deliberately
outstanding: binary extraction (`pdf`/`docx`/`xlsx` behind the `[extract]`
extra) is unimplemented, so those types are rejected fail-fast. Phase 4 (the
Node half) is planned (see `docs/plan/`).
## Install
@ -232,6 +235,17 @@ Python 3.10+, and exactly one runtime dependency — the security boundary,
`llm-ingestion-guard>=0.3,<0.4`. Everything else is stdlib. The commands are
under [Install](#install); what follows is why they look the way they do.
From a checkout, the test suite runs with:
```
.venv/bin/python -m pytest
```
The suite is the verification surface for everything above: 589 tests, run on
2026-08-13 against this branch. It is not shipped in an installed
distribution — `tests/` lives at the repository root, so this command needs a
clone rather than a `pip install`.
A git URL is a PEP 508 direct reference and pins one exact tag, so it is an
install-time *channel*, not the pin: the range above stays the declared
dependency — a wheel built from this branch carries `Requires-Dist: