docs(changelog): the harness's plan replay, log.md, and the proposer's scope

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-09-03 04:46:27 +02:00
commit 5628467be0

View file

@ -9,6 +9,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Added
- **The corpus harness (`tools/okf_corpus_run.py`) can replay segmentation
plans, and it writes the bundle's `log.md`.** `--plans-dir` names the
proposals to replay and the profile follows from it; `--bundle-id` and
`--okf-version` are arguments, never constants, because a profile names a key
and the caller owns its value. `log.md` is written in SPEC section 9 form and
dated from `ingested_at`, so `merged + sum(coded rejections) == N` is
checkable from the bundle alone rather than only from a report that does not
travel with it. Without `--plans-dir` a run is unchanged.
Measured cause: the harness passed `STRUCTURED_V1` and no plans, so a
43-document corpus arrived as 39 flat concepts with no `adjudication` key
anywhere. Rebuilt, the same corpus yields 629 concepts, 618 of them
`adjudication: proposed`. Record: `docs/2026-09-03-k2-bundle-rebuild.md`.
- **`tools/okf_propose_segments.py` takes `--path-prefix`.** Section numbering
is document-local, so across 39 documents 618 proposed entries claimed only
601 distinct paths -- 17 collisions that Door B's gate refuses per document.
Scoping each document's entries under a caller-supplied prefix removes all
17. Without the flag every artifact already produced is byte-identical.
### Changed
- **`tools/okf_propose_segments.py` writes no artifact when it has nothing to
propose**, exiting `1` (distinct from `2`, "could not do the job") instead of
`0` with an empty plan. An empty plan cannot be replayed -- `process_inbox`
refuses one, because a plan naming no entry would persist nothing for a
document that was dropped -- so the file's only possible use was to fail a
run later, and it did. Measured: 11 of 39 documents in the K2 corpus propose
zero segments.
- **A concept can now record more than one source.** `sources` renders a flow
sequence of N flow mappings on one line, so a v0.2 profile can express
multi-source provenance instead of the single entry that was the measured