Kjell Tore Guttormsen
977040f575
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>
54 lines
2.9 KiB
Markdown
54 lines
2.9 KiB
Markdown
# 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`):
|
|
|
|
```sh
|
|
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.
|