open/llm-ingestion-okf
1
0
Fork 0
Code Issues Releases 4 Activity
llm-ingestion-okf/skills/okf-consume/references/README.md
Kjell Tore Guttormsen 977040f575 feat(check): the contract and the checker state the payload's v1.1 forms 
C6. `docs/consumption-contract.md` now says what the pre-pass emits:

- SS 2.5 point 2: sub-questions are written in the bundle's terms and given to
  the pre-pass in ONE run where it takes several;
- SS 8's example is `okf-consumption/2` as shipped: `withheld` is the
  `{total, by_rule, nearest, complete}` mapping, `coverage` carries
  `absent_terms` and `weak`, an excerpt carries `text`, `text_sha256`,
  `passage` and `own_title`; point 1 closes the identity on `withheld.total`;
- point 7 keeps the falsified verdicts on record and states the one reading
  carried since v1.1, `weak`, with its rule: a word held in no form, or
  nothing delivered -- whether a word exists at all, which does not move with
  question style or corpus size the way the two shares did;
- point 8 the passage (`{start, end, of}`, `text_sha256` over the passage,
  `sha256` still the file's), point 9 several sub-questions in one run (one
  cut, `questions`, `subquestions`, per-sub-question coverage), point 10 a
  title inherited from the heading above, with `own_title`;
- SS 10 names this library's default ranking (BM25) and `--ranking fusion`.

`okf check` holds the two new forms a reader acts on: `passage_malformed`
(not whole numbers with 0 <= start < end <= of) and `subquestions_unindexed`
(not distinct indices into `questions`, or indices in a payload listing none).
17 -> 19 rules; the two tests that pin the published count move with it.
Each rule is held against a real payload (0 findings) and against that
payload broken six ways.

Editing the contract moved the SS 7.4 known-positive, measured once after the
edit: 19 837 -> 23 672 encoded, 19 358 -> 23 092 raw, delta 479 -> 580. The
example payload and `skills/okf-consume` are regenerated by the published
recipe and `okf check` reports 19 rules, 0 findings on them.

Suite on a clean tree after `git add`: 2443 passed, 2 skipped, 4 xfailed.
ruff, ruff format, mypy --strict clean.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-21 08:47:46 +02:00

2.9 KiB
Raw Blame History

References

example-payload.json is a real payload, not an illustration, and ../SKILL.md is the skill generated for the same bundle. Both come from the three-concept golden bundle that ships in this repository, examples/ingest-golden-segmented-okf-v0-2/expected-bundle, so anyone reading this file can regenerate them byte for byte and compare. Neither carries content from any corpus.

Regenerate them from the repository root rather than editing either file, with okf being this checkout's own install (for example .venv/bin/okf):

okf skill examples/ingest-golden-segmented-okf-v0-2/expected-bundle \
  --out skills/okf-consume --force --for-bundle \
  --example-question "Hva sier veiledningen om krav?"
python3 -c 'import os, pathlib; p = pathlib.Path("skills/okf-consume/SKILL.md"); p.write_text(p.read_text(encoding="utf-8").replace(os.path.realpath(".") + "/", ""), encoding="utf-8")'
okf check --skill skills/okf-consume/SKILL.md \
  --payload skills/okf-consume/references/example-payload.json

Why each part is there:

  • --for-bundle: since v1.1 the generator writes the GENERIC skill by default; this copy is the instantiated one, for this bundle.
  • --force: the generator refuses to replace an existing SKILL.md (refused (target_occupied)), because a silent overwrite would destroy a hand-edited copy.
  • --example-question: without it the question is derived from the bundle's own titles and the payload is a different one. tests/test_okf_consume.py asserts this payload byte for byte against the pre-pass for exactly Hva sier veiledningen om krav?, so the question is part of what the file is.
  • The python3 line: okf skill writes the bundle root and the skill's own path absolute when --out is not under .claude/skills/, and this directory is not. Shipped as generated, the two commands in SKILL.md would name one checkout on one machine. The line strips that checkout's prefix and nothing else, and a test holds the shipped SKILL.md to the generator's output with exactly that prefix removed.
  • okf check should report conformant: 19 rules over 3 excerpts and 0 withheld entries, 0 findings and exit 0.

The generated name is b-golden-segmented-okf-v0-2-consume while this directory stays skills/okf-consume/. Claude Code takes a project or personal skill's command from its directory name and uses name as a display label, so a copy placed at .claude/skills/okf-consume/ is still /okf-consume.

The payload is here so that its shape can be read without running anything, and so that a reader can see what the members the contract does not name look like in practice: text and text_sha256 on every excerpt (§ 8 permits additional members; § 1 defines an excerpt as delivered content, and without a body the budget gate would measure a skeleton), rank, bundle_id_inherited, and the raw_bytes/encoding_delta pair that gives the known-positive a second, independent check.