docs(k3): round 21, parent all the way to the reader

The record for K3-21 A-D: what an excerpt, a heading-only body, the checker
and the index now carry, and every gate with its denominator -- the pinned K2
bundle (7 passed in each export), 32 regression payloads, R761 with and
without `--shell-parent` (hit@1/8/50 6/6 at both k, the known-positive at
rank 1, 675 of 710 shells with exactly one link and 0 broken, 710 of 710
pointing at the source's own ancestor after D), consumption 6 of 6 in both
forms, the byte cost against the consumer's 51.0 %, the ranking cost the
link's path carries, and the 35 shells with no ancestor holding text, listed.
Deviations from the order stated first; honesty limits last.

CHANGELOG under Unreleased; README and CLAUDE.md say 710 of 710, 17 rules,
and that the outline mark keeps its depth. The README's project measurement
was re-run (26 concepts, 0 checkout paths, `okf check` 17 rules, 0 findings).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-09-11 14:28:42 +02:00
commit e98ca6d25f
4 changed files with 407 additions and 8 deletions

View file

@ -7,8 +7,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Added
- **`parent` reaches the reader (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`, and an
excerpt carries `parent: { concept_id, title }`, conditional like
`req_number`; a pointer that lands nowhere is named `parent_unresolved:
true`. A heading-only body whose plan entry has a parent gains ONE line,
`Enclosing section: [<title>](/<bundle-relative path>)` (SPEC § 5.1, § 6.1).
Measured on the one standard with such sections: 675 of 710 carry exactly
one link, 0 broken, 72 265 B = 4.49 % of body bytes; hit@1/8/50 6/6 at both
`k` with the known-positive at rank 1.
- **`okf consume --follow-parent` (K3-21 B, off).** `parent` also carries the
enclosing concept's `text` with that concept's own `sha256`, placed after the
cut from the room it left, in rank order -- the delivered set is the same
with it as without it (16 of 16 payloads); a text that does not fit is cut
and marked `truncated`.
### Changed
- **`okf check` has seventeen rules** (`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`. Every "16 rules" line a consumer quotes
is now "17 rules". Contract § 8 gains point 6, and its sentence "additional
members are permitted and are not read by the checker" now says the checker
reads only the members § 8 names. A consumer that does not know `parent`
has nothing to do: it is conditional and absent on every bundle without it.
- **The § 7.4 known-positive moved** (13 238 / 12 893 / 345 -> 14 721 /
14 346 / 375), because it IS the contract document: every payload's
`budget.known_positive` block moves with no bundle changing. Measured on 32
regression payloads, everything outside that block is byte-identical.
- **`--shell-parent` stays off, on a measurement** rather than on "`okf
consume` reads no `parent` key", which A made false: the link's absolute
path repeats the document's directory in 675 bodies and moved the delivered
set on 2 of 8 questions at the default `k` (3 of 8 at `k` 50), hit@k
unchanged.
### Fixed
- **The index resolves a `parent` naming a segment of its own document
(K3-21 C).** 675 of 675 such facets rendered `parent: pN?` while the concept
stood in the bundle; now 0. The two segmented goldens' index files move one
`?` each (4 lines).
- **A declared section below markdown's sixth level keeps its level in the
plan (K3-21 D).** The NISO-STS reader clipped the outline mark to 6 along
with the heading; the mark now carries the declared depth. On one standard
the plan moves on exactly 2 entries (`--shell-parent` only), and 710 of 710
shells point at the ancestor the `<sec>` nesting names (708 before).
- **Frontmatter this library writes is YAML a YAML reader reads back the same
(K3-22).** SPEC § 11 point 1 requires "a parseable YAML frontmatter block" in
every file. Measured with PyYAML 6.0.3 before the change, the pinned K2