Commit graph

2 commits

Author SHA1 Message Date
01e4170fe4 docs(plan): make retrieval cost a first-order element of the consumption contract
Second order 20260825T133057Z-193098605-from-.claude, carrying an operator
directive that how an agent finds information in a bundle must be
token-efficient, as a property the contract carries rather than a later
optimisation. The order prescribed the goal, left the form to us, and invited
the objection that "token-efficiency" is the wrong abstraction for a generic
layer. It is, so the element is not called that.

C6 — retrieval cost is declared: instrument, budget, denominator, breaking
point. It binds the READING side (the order's property 1): a conformant
consumption skill states the bound its cut targets, what a typical answer costs
against the whole-bundle denominator by a named instrument, which way cost
scales, and the corpus size at which its strategy stops fitting its budget.
Each is re-runnable as a command (property 2), and the instrument must
reproduce known-good figures before its own are believed — C3's second
corollary applied to a positive quantity.

Why not "token efficiency": a token is one encoder family's unit and fixing it
would adopt one vendor's arithmetic as everyone's (the move §3 already refuses);
"efficient" is a comparative with the denominator missing; and efficiency is a
property of a run while a contract binds a document. Reading a whole bundle
stays legal — doing it UNDECLARED does not.

Measured for this revision, all against stated refs: the gap was real (one
pre-revision hit, on an unrelated sense of "costs"); the cited 250 785 /
430 144 / 112 116 figures and their prior validation against three known-good
values hold; the reading model navigates rather than searches. A fifth
measurement the order did not know, prompted by vegnormal-okf's coord message:
IndexPolicy.per_directory is a JUDGING field (required_indexes/violations) —
no code path here emits a nested index, and materialize refuses STRICT_V1 for
exactly that reason. So a permitted shape is not an emitted shape, and §2 now
says a cost figure inherits the ref rather than the profile.

Bundle SHAPE stays with the repo that produces it (O2); no instrument is
blessed; no engine, ranker or cutter is designed. No src/, no bump, no tag.
2026-08-25 23:38:34 +02:00
d205b707da docs(plan): take ownership of the generic OKF bundle consumption contract
Plan work only, per operator decision 2026-08-25 relayed through .claude
(order 20260825T122454Z-4632317874). No code, no module, no version bump.

Fixes four things a bundle-specific consumption skill can be held to:

- The contract's five bundle-independent elements: source marking, pin
  anchoring by ref rather than version, denominator reporting, the
  script-cuts/agent-judges division of labour, and (added here, grounded
  in a measurement in a second corpus) conditionally-written fields,
  whose absence is a measurement rather than a fact.
- Architecture: a parallel document, not a field on BundleProfile. The
  profile is a construction-time gate in one runtime and deliberately
  excludes judgement vocabulary. Drift is prevented by shared profile
  identity plus a pin plus a requirement that structural claims be
  re-measured by command, never restated in prose. IndexPolicy's
  entries_match_directory binds the consumption side unchanged.
- The source-marking vocabulary: five required values plus a declared
  extension mechanism. [verified-in-target] is an extension, not a
  required value, because it presupposes a target outside the bundle
  and a measured corpus exists where that presupposition fails.
- A conformance checklist for a bundle-specific consumption skill.

The order's premise that the 2026-08-13 ratification was unfounded does
not survive re-measurement: the supporting grep was scoped to 16 of 639
files and missed the tracked state file that records the decision. The
real defect is narrower and belongs to another repo — the document its
own engine names as requirements owner has not been updated. Reported
by coord, not edited (O2).
2026-08-25 15:06:51 +02:00