Kjell Tore Guttormsen
4f7bd61500
K3-21 A. `okf consume` resolves a concept's `parent:` pointer -- a
`segment_id`, unique only inside one document's plan -- among the concepts
sharing its `source_file` (`consume.link_parents`, one pass, no file opened
again) and an excerpt carries `parent: { concept_id, title }`. Conditional
like `req_number`: a concept with no `parent` key moves no byte. A pointer
that lands nowhere is named `parent_unresolved: true`, never dropped.
The door writes ONE line into a heading-only body whose entry has a parent:
`Enclosing section: [<title>](/<bundle-relative path>)` (SPEC SS 5.1 lineage
through links, SS 6.1 the recommended absolute form and the kind in the
prose). Only such a body, so the segmented goldens' declared parents -- bodies
holding text -- are untouched. Appended AFTER structure derivation and
screened on its own (`_screened`, the `description` rule): read as body text
the link was derived into a second, unresolved `references` edge, measured on
the fixture. `segmentation.heading_only` is the one predicate the proposer and
the door share.
`okf check` gains its seventeenth rule, `parent_unfollowable`: a `parent`
that is not a concept_id and title, names its own excerpt, or names a concept
in neither `excerpts` nor `withheld` (together every considered concept).
Contract SS 8 point 6 added, the figure carries `parent`, and "additional
members are not read by the checker" now says the checker reads only the
members SS 8 names. The template tells the reader what `parent` is and that
SS 2.2 lets it read that one concept; `skill.CONDITIONAL_FIELDS` gains
`parent`. README and CLAUDE.md say what consume now reads.
Moved on purpose, each named: the SS 7.4 known-positive IS the contract
document, so `budget.known_positive` moves in every payload (13 238 / 12 893
/ 345 -> 14 455 / 14 083 / 372); `skills/okf-consume/` regenerated from the
segmented golden, whose plan declares s1 and s2 under s0 -- its example
payload now carries both parents; `test_bundle_identity` 16 -> 17 rules;
`test_shell_parent`'s byte test also accounts for the link line.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
51 lines
2.8 KiB
Markdown
51 lines
2.8 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 --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:
|
|
|
|
- **`--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: 17 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.
|