open/llm-ingestion-okf
1
0
Fork 0
Code Issues Releases 1 Activity

docs(plan): amendments etter PM-dom 02.09

Browse source 
Record the two cross-repo decisions the programme ratified on 2026-09-02, so
they exist on this side of the boundary rather than only in a consumer's plan.

- Concept IDs are bundle-local; identity across bundles is the tuple
  (bundle_id, concept_id); no cross-bundle link form in v0.2. Written down
  before a golden freezes the IDs, because retrofitting would move a pinned
  golden.
- The adjudication state has a fixed wire form: frontmatter key `adjudication`
  with a closed value set, three companion keys when adjudicated, and an
  `adjudication` index facet -- new profile only, SEGMENTED_V1 byte-identical.
  Absence of the key means `unknown`, never `absent`.

The ten amendments from the same judgement are applied to the voyage plan
itself, which is LOCAL-ONLY under this repo's public-remote model and so is
not part of this commit.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-09-02 13:58:21 +02:00
commit 11cde6d0b5
1 changed files with 56 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

56
docs/plan/office-intake.md
View file

@ -92,3 +92,59 @@ The acceptance rubric these decisions are measured against (K1–K7) is owned at
programme level, spans this library and its consumers, and is not closed here.
This work produces numbers on K1–K5 with their denominators; the thresholds that
turn a number into a verdict belong to whoever owns the rubric.
## Two cross-repo decisions ratified after these three
The three above were this repository's own to make. The two below were not: they
span this library and a consumer, so they were ratified at programme level on
2026-09-02 and are recorded here because a contract that lives only in a
consumer's plan file is a contract this side cannot be held to. They enter the
office-intake work as amendments to it, not as new scope.
### 4. Concept IDs are bundle-local; identity across bundles is a tuple
**Decision: programme level, 2026-09-02.**
A concept ID is **bundle-local and stable**. Identity **across** bundles is the
tuple `(bundle_id, concept_id)` — never the concept ID alone. The producer
already stamps `bundle_id` into every concept's frontmatter, so a consumer reads
the whole tuple from a single document and needs the root `index.md` only as a
fallback for an older bundle.
**There is no cross-bundle link form in v0.2.** A consumer that holds several
bundles partitions per bundle; nothing in this library emits a syntax for
pointing from inside one bundle into another, and adding one is out of scope
until a consumer states the need.
The timing is the reason this is written down now rather than later. The moment a
golden bundle carrying `okf_version` is byte-pinned, the IDs inside it stop being
adjustable — retrofitting a different denotation afterwards would move a pinned
golden, which is the one thing byte-pinning exists to prevent.
### 5. The adjudication state has a fixed wire form
**Decision: programme level, 2026-09-02.**
Segment concepts carry their adjudication state in a frontmatter key
`adjudication`, whose value set is **closed**: `proposed` or `adjudicated`. A
value outside that set is an error, not an extension point.
When the value is `adjudicated`, three keys are written alongside it:
| Key | Form |
|---|---|
| `adjudicated_by` | the adjudicator's identifier |
| `adjudicated_at` | ISO 8601 |
| `adjudication_dwell_s` | integer seconds |
The state is projected into the index as the facet `adjudication`. All of it is
written **only under the new profile**; `SEGMENTED_V1` output stays byte-identical.
Two things make this a contract rather than a naming preference. First, the dwell
time travels with the verdict: a ratified flag with no per-item time is
unfalsifiable, and the same field is what makes adjudication throughput
measurable at all. Second, the consumer side has a rule this side must not
break — **absence of the key means the state `unknown` (an older bundle), never
`absent`**. A producer that emitted the key inconsistently would collapse that
distinction, and the consumer's ability to see an unratified concept and
discount it is the whole point of surfacing the state.