vegnormal-okf measured the gap on 2026-08-27: the arm reading DEFAULT's
index.md scored 0 hits of 8, the arm reading a faceted index of the same
frontmatter scored 25 of 29. Same bundle, same concepts, same model. The
DEFAULT arm did not answer wrongly, it abstained -- the metadata is in the
bundle and the index throws it away (30 974 characters over 269
requirements, 0 occurrences of any of the eight facts).
FacetPolicy and STRUCTURED_V1 already did this. They did not reach Door C.
`import_bundle` now takes a keyword-only `profile` defaulting to DEFAULT, so
every existing call site emits the bytes it always did, and `link_in_index`
takes the facets to render.
Door C PROJECTS and never DERIVES, which is the answer to the objection this
work opened with: deriving structure for a document a third party wrote would
put our inference into an index entry ABOUT their bytes, where it reads as
their claim. The concept file was already verbatim; the entry describing it
now is too. Where the sender carries `derived`, THEIR list travels unchanged,
so a reader can still see which of the sender's facts the sender inferred.
The projection asks the policy which keys to carry and never what a key
means. That is what makes it work for a meeting note as well as a numbered
norm -- nothing in it can key off a numbering scheme -- and it is why a
consumer whose concepts are named by UUID can get `title` into the index by
naming the key, with no change here.
Two things measured during the work rather than assumed:
- A value carrying the policy's own joiner cannot be rendered. Door C's
tolerance is structural and it refuses no sender on form, so the FACET is
dropped and the concept still merges -- reported per concept and key in
`ImportResult.unrendered_facets`, never dropped silently.
- A faceted entry can go stale where a flat one never could: the collision
gate refuses an updated concept, so the operator's only route is to remove
the merged file and re-import, after which the file said `gjeldende` while
the index still said `utkast`. A faceted entry for a present target is now
refreshed in place instead of skipped. Unfaceted callers keep the early
return byte for byte.
Suite 695 -> 707; ruff and mypy --strict clean.
Order 20260826T224500Z-873805419-from-vegnormal-okf.
A deep-research report arrived mid-session (.claude broadcast 20260826T223230Z)
on a near-identical problem shape -- numbered regulatory requirements with
cross-references. Two of its numbers bear on this work: index-selection
strategy contributed +38.0 points of accuracy, and edge inference gave NO
accuracy gain at 2.8x the cost.
The second is a negative finding worth inheriting rather than re-measuring. It
does not condemn what landed today: references and parent are EXTRACTED from
explicit tokens, and the one proposed relation is structural and costs a single
pass. It draws a line for later -- no semantic edge inference without measuring
that 2.8x against our own corpus first.
The report also states that no published source gives per-query token counts
for structured versus flat context, and none reports an indexed superseded-by
facet. That reframes today's 3.3x-6.4x cost dial: it is the tradeoff nobody has
published, which is a reason to measure it properly rather than to hide it.
Treated as a premise, not a result. An external number changes what is worth
trying next, not what this repo has proved.
Six decisions, each with the failure it prevents: confidence carried in the
format, certainty stated per field, supersession never inferred from one
document, the index as a projection rather than an append, facets as a new
profile, and Door B's ownership stamp left deliberately open.
Six findings reported as findings rather than as gaps, per the order: the cost
of closing the metadata gap is 3.3x-6.4x the flat index and whether that keeps
the OKF arm's cost advantage cannot be answered from this repo -- it needs
their bake-off re-run on their corpus; a reference to a parent-level number
does not resolve to a child, and the fix needs a real corpus before 'unique'
can be defended; OKF_V0_2's verified/status/stale_after are still expressible
and unwritten for the reason already recorded.
Every number carries its denominator, and the supersedes 0/55 carries a
known-positive control (50/55 on a corpus that has shared numbers) proving the
query can find what it reported missing.
Door B takes a profile (keyword-only, DEFAULT) and, under a profile carrying
facets, derives each dropped document's title, number, hierarchy and
cross-references, writes them into the concept's own frontmatter, and projects
them into the index entry.
The additive requirement is answered by one decision rather than by an
algorithm: the index is a PROJECTION of the concept files, recomputed from the
whole bundle each round. Nothing is diffed, so the three invariants hold by
construction -- rebuild-from-scratch equals incremental byte for byte,
re-dropping a document replaces its entry instead of doubling it, and a
relation formed in round 3 UPDATES the round-1 entry it is about, which an
append-only index could never do.
An unresolved pointer is marked '?' in the entry rather than omitted: during
build-up, pointing at something not dropped yet is normal, and the dangerous
version is the one that leaves no trace. Facet values are validated per file
BEFORE the write, so a producer value that breaks the grammar fails that file
and not the run.
DEFAULT is byte-identical with and without the new parameter, and is asserted
so. Door B keeps writing the literal 'generated: true' rather than the
profile's ownership stamp -- routing it through the profile would move
DEFAULT's bytes and orphan every bundle this door has already written; that is
a separate question and answering it here would have answered it silently.
18 new tests; suite 677 -> 695.
The measured defect, as data: the 2026-08-26 bake-off had every arm retrieve
40/40, so quality could not separate them. The only axis that did was trap
exposure -- 18/20 for the OKF-index arm against 8/20 for a frontmatter
head-scan -- and both sides measured the reason independently: the flat index
carries title/date/status/supersedes 0 times while its own documents carry them
55/55/55/5. The metadata is in the bundle; the index throws it away.
FacetPolicy lets an index entry keep it. The grammar is thin on purpose (one
separator, then key: value joined by '; ') because index lines are read by
regex on both sides of this library, and a value carrying either delimiter is
REFUSED rather than escaped -- validation, not repair, as everywhere else here.
Additive by construction, not by caution. entry_pattern IS link_pattern when a
policy carries no facets, so DEFAULT and STRICT_V1 match the same lines and
emit the same bytes; the goldens are the proof. Facets arrive as STRUCTURED_V1,
a new profile, because DEFAULT states commons' ingest-spec index layer and
changing its bytes from here would be this repo editing a contract it does not
own.
17 new tests; suite 660 -> 677.
A bundle a consumer can only look things up in is a filing cabinet. This adds
the derivation half of what lets one REASON over it: per-document title,
number, parent and references, plus bundle-level resolution of every pointer.
Two rules carry the design. Every fact is marked DECLARED or DERIVED, because
an unmarked heuristic is worse than no heuristic -- a consumer cannot know when
to doubt it. And resolution is a PURE function of the whole document set rather
than a diff, which is what makes rebuild-from-scratch equal an incremental
update by construction: there is no diffing algorithm to prove correct.
An unresolved pointer is kept and reported, never dropped: while a bundle is
built up over several rounds, pointing at something not dropped yet is the
normal state, and the dangerous version of it is the one that leaves no trace.
Symmetrically, a parent our own grammar could never admit (4.2 -> 4, a bare
integer) is not emitted at all -- an unresolved list that never clears is one a
consumer learns to ignore.
45 new tests; suite 615 -> 660.
ms-ai-architect's bake-off measured that no door carries both freetext
ingestion and a formable index. Verified against the code (not the
report) that neither offered alternative closes it: a BundleProfile
carries no title-derivation field, and a Door A connector was already
rejected by the consumer's own 2026-07-20 reasoning. The real gap is a
Door B title-derivation feature, independent of profile selection;
recorded as a decision only, no implementation.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
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.
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).
Reflects actual maturity (615 passing tests, real consumer): PyPI
classifier "2 - Pre-Alpha" -> "3 - Alpha". README heading "Planned
scope (v1)" -> "Implemented scope (v1)" since all three doors (A/B/C)
are implemented. Cosmetic only, no functional change. Operator
decision recorded in docs/2026-08-24-beslutninger-classifier-a5-f7.local.md.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PGwbxHqib3QcaFa7hhMpB7
The operator's condition for revisiting the pin was met (v1.2.0 contains
the flow-mapping frontmatter fix, commit 5870483) and the operator has now
approved the move itself, dispatched as its own order because it changes
consumer-visible Requires-Dist and shifts golden-fixture admission.
Floor 1.2: this library needs the flow-mapping support (`generated: { by:
x, at: y }`) that landed there — without it Door C fail-secures every
concept carrying that stamp. Ceiling <2.0, not narrower: the guard's own
1.0.0 release freezes its exported surface until a 2.0.0, and explicitly
keeps calibration (severities, dispositions) free to move within 1.x, so a
tighter ceiling here would claim a stability guarantee neither side needs.
Re-measured through Door C against the guard's own default
(allow_reserved=True, matching how the earlier recommendation measured
it), over the 9 concept documents across all four Door-A goldens:
4/9 admitted at 0.3.4 -> 8/9 admitted at 1.2.0, confirming the number
already reported. The ninth (a `sources` block-list carrying `resource`)
stays refused by design (G30) and is not expected to move.
Failing-test-first: test_guard_adapter.py::test_guard_version_is_inside_the_pin
and test_packaging.py::test_the_only_runtime_dependency_is_the_security_boundary
were updated to the new pin first and confirmed red against the
still-installed 0.3.4, then `uv sync --extra extract` installed 1.2.0 and
both went green. Full suite (615), ruff and mypy --strict clean.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RxcxzNwpX1kDP53n1rLhM5
The operator asked for a job that checks at least weekly whether Google OKF has
moved, and messages the right repo immediately when it has. It belongs here
rather than in `.claude` because knowing what a meaningful spec change IS
requires owning the pin, the runbook and the always-latest policy.
`tools/okf_watch.py`, stdlib only, driving git against the local read-only
mirror. It lives outside `src/` so it never enters a wheel; a new packaging test
holds that as a promise rather than an accident of the build config.
Three properties carry the design, and each closes a failure this repo has
actually met:
1. A failed call is never an empty result. Every git invocation raises on a
non-zero exit and carries stderr, so a caller reading "" knows the query ran.
The precedent is `grep ... | head; echo $?` reporting head's exit status - a
broken query read as a quiet upstream.
2. It proves it can find, every run. Before believing any zero it re-runs the
full detect-and-classify path over `ad30107^1..ad30107`, a range known to have
changed SPEC.md. An empty known-positive aborts loudly rather than reporting a
clean sweep. Network failure likewise raises; it never degrades to "no change".
3. It reports on change, not on state. A pin-keyed state file records what has
been announced; moving the pin resets it, because a pin move means everything
behind it was absorbed.
Quiet is the enumerated list, not signal. Enumerating what counts as normative
can only match what upstream has already invented, so anything new would fall
outside it and the watch would go silent - failing in the direction nobody
notices. A small measured quiet list, everything else reports. README.md is
deliberately not quiet: the repository move was announced in a README commit.
Sixteen tests build their own git repository in tmp_path rather than skipping
when the mirror is absent - a skipped test preserves nothing on the machine
where the dependency exists. All four load-bearing behaviours were mutation-
tested red before this landed.
Two more tests exist because building this fired a real false alarm: running
with `--pin` and without `--dry-run` delivered two live coord messages. The
override now implies dry-run, enforced in argument parsing rather than
remembered, and `.claude` has the correction.
The runbook gains a section stating what the watch CANNOT do, because that is
the part a future session will otherwise assume away: it sees commits, not
meaning. It would have fired on the 2026-08 tightening because SPEC.md changed,
but no commit list says a value that conformed last month no longer does, and
none says is_stale reversed. Its output is "run the runbook", never "here is
your exposure".
The operator authorized the move from `3fcbb9f` (frozen `knowledge-catalog/okf/`)
to `ad30107` in `GoogleCloudPlatform/open-knowledge-format`. Cost to our fixtures
was measured at zero bytes before the decision and is unchanged: `okf_spec_commit`
is a key `STRICT_V1` names, its value is the caller's under D5, and no shipped
fixture carries one.
The old hash stays in the alignment plan rather than being rewritten. Every fact
under that heading was *read* at `3fcbb9f`; replacing the hash would give those
facts a provenance they do not have. What moves is the tree we measure against.
V-A8 re-run at the new pin: 9/9 of our golden documents parse under upstream's
reader, 0 failures, 27/27 semantic-reader calls (`trust_tier`,
`normalize_verified`, `is_stale`) return without raising. The zeroes are
measurements — the harness was put to a known-positive in both directions first:
`type: [unclosed` raises `OKFDocumentError` while a well-formed control parses,
and `is_stale` returns True for a past `stale_after` and False for a future one.
Types recovered: `ingested_at` -> str (was datetime), `generated` -> dict,
`sources` -> list, `okf_version` -> float (A-E6, still upstream's).
The `38c713f` divergence is carried forward as a written known divergence rather
than left to evaporate with the pin, and it is now recorded at pin-level
precision. `38c713f` is not an ancestor of `3fcbb9f` (`merge-base
--is-ancestor` exits 1) — it landed three weeks forward of the pin we left, so
both the old and the new pin carry the bare-scalar `tags:` form and the move
loses nothing. The accurate statement is that canonical ships a form its own
frozen predecessor has already repaired.
The open question is closed rather than deferred, because it was cheap: across
129 tracked text files present in both trees, 9 carry frozen-only lines - 8 are
`38c713f` and the 9th is the freeze notice in `README.md`. Zero files are
frozen-only. The divergence is fully enumerated.
Runbook Step 3a gains the harness trap that cost this round a re-run: the
semantic readers take the frontmatter mapping, not the document, and passing the
document raises an AttributeError that reads like an upstream incompatibility.
Order G34 asked whether the corpus-wide rejection of a conformant `sources`
block reproduces against guard 1.1.0, on the premise that 1.1.0 introduced a
mapping-key allowlist on 08-21. It does reproduce, and the premise is off by
one release: v1.1.0 is dated 08-13 and carries no allowlist. The allowlist is
`5870483`, nine commits past that tag and carrying no tag of its own -- its
`__version__` still reads 1.1.0.
Measured, each point extracted with `git archive` and put on PYTHONPATH ahead
of the venv, resolved version confirmed per run. The conformant variant is 0
merged and the control 34 of 34 at 0.3.4, 1.0.0, 1.1.0 AND the allowlist
commit; the control merging is what shows the harness can pass at all. Seven
candidate `sources` carriers, and none that names a `resource` merges at any
of the four points, because `resource` is deliberately off the allowlist while
SPEC 5.1 makes it REQUIRED inside an entry.
Two things the plan did not know. v1.1.0 closed the one-key block sequence,
which the 2026-08-02 measurement recorded as the only shape carrying a section
10 pointer through Door C, so `unverified_references` is empty by construction
at >=1.1. And the allowlist commit moves this library's own goldens from 4 of
9 to 8 of 9 concepts through Door C, the `generated` stamp being exactly the
shape it admits.
The pin therefore holds at `>=0.3,<0.4` / `v0.3.4`. Lifting to v1.1.0 is
behaviour-free here (595 pass, the one red being the pin assertion itself) and
buys nothing on this axis; the gain sits on an untagged commit, and pinning
one trades a release channel for a moving target. The condition to revisit is
a fact, not a date: a guard tag containing `5870483`.
The 2026-08-02 table is left standing and dated rather than rewritten -- it is
true of the version it names.
Operator GO 2026-08-23. Two findings outrank the change that triggered
the round.
OKF moved to GoogleCloudPlatform/open-knowledge-format (6265173). The
tree this repo pinned, knowledge-catalog path okf/, is now a frozen
snapshot by upstream's own notice, and the runbook's Trigger step named
it. The two trees have already diverged: the frozen copy carries a fix
(38c713f, eight tags: values as sequences rather than one plain scalar)
that the canonical repo does not.
The spec tightened without a version bump. SPEC.md still declares
Version 0.2, but every timestamp-valued key is now an ISO 8601 datetime
with an explicit offset, so a value that conformed in July does not
conform now under the same version number. Step 4 gained a fifth diff
class for it.
Our exposure is zero, measured: 10 of 10 timestamp values across the
four goldens already carry a Z offset, gated by _INGESTED_AT_RE. The
three tightened keys (stale_after, last_modified, usage_window) are
named but never written by any door. V-A8 at the new pin: 9/9 of our
bundle documents parse, 78/78 of upstream's do.
Two reference-reader behaviour changes recorded. A date-only
stale_after now reads as never stale rather than as stale -- silent,
fails open, and the class the black box cannot absorb. Timestamps now
survive a parse as written, so our ingested_at arrives as str where it
used to arrive as datetime.
No new profile: there is no new version to express. The pin move and
consumer notification are named as deliverables and deliberately not
taken here.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013j8ZEcjiZQpz22fecNsyLZ
The comment on [tool.uv.sources] claimed the built wheel carries
`Requires-Dist: llm-ingestion-guard<0.3,>=0.2`. That is the `v0.4.0` tag's
range, not this tree's, and it had been stale since the pin moved. A wheel
built from this tree carries `<0.4,>=0.3`, measured against the built wheel.
The old value is kept and attributed to the tag it belongs to rather than
substituted, because it is still true there.
Five measurements were run before editing, on uv 0.9.8 with an empty cache,
because the plan of record was to REMOVE this entry and the README claim it
supports had never been measured in more than one form:
- uv, direct: the README one-command install resolves the guard from the
tag's [tool.uv.sources]. Third independent confirmation (07-25, 08-20,
08-21).
- uv, transitive: a separate consumer project naming only this package still
resolves the guard from the entry, because this package reaches it as a git
source. Not previously measured.
- pip, negative: installing this package alone fails with exactly the error
the README names, and the message prints the tag's own range.
- pip, positive: the README's two commands in order install clean and import.
- core install: brings the guard and no binary parser packages.
The entry is therefore load-bearing, not scaffolding: a wheel carries
Requires-Dist and nothing else, so it cannot survive an index install, and
while the guard is off-index removing it would break the documented uv path.
No package index carries the guard today, which was the premise removal
depended on.
The README install block measured correct as published and is unchanged. Its
test count had drifted: 596 with the [extract] extra, 589 passed and 7 skipped
without, both measured today.
Wheel metadata is byte-identical before and after, so the change is inert.
Order G2a. Populates the optional `[extract]` extra for the first time with
one parser, `pdfplumber>=0.11.10,<0.12` (MIT), and wires `pdf` through it.
The default install is untouched: exactly one runtime dependency, stdlib
otherwise, enforced by test_packaging.py.
The gate for `pdf` becomes an import probe rather than a frozenset membership
test, exactly as extract.py's docstring had promised. The rejection does not
change: without the extra, `pdf` still raises `extractor_extra_missing` with
the same message. That behaviour is asserted UNCONDITIONALLY via a sys.modules
monkeypatch, so it holds on machines where the parser is installed too — a
skip would have preserved nothing there. Verified in a clean venv without the
extra: 589 passed, 7 skipped; with it, 596 passed.
`docx`/`xlsx` are unchanged and still fail fast — the extra names exactly what
it ships.
The parser choice was forced by measurement, not preference (b73dd9d,
docs/2026-08-21-g2-pdf-extraction-measurement.md): on a real requirement table
pdfplumber keeps 4 of 4 rows with label and value on one line, where pypdf,
pdfminer.six and pymupdf each keep 0 of 4. pymupdf is additionally out on
licence (AGPL-3.0), which an MIT package must not push onto a consumer.
Three facts from that measurement are now carried in code rather than in a
report:
- Extracted text is pinned to an exact transitive parser version
(pdfplumber pins pdfminer.six==20260107; date-stamped, no stability
contract). tests/test_extract.py freezes the expected text of a committed
hand-written fixture so a parser upgrade breaks something visible instead of
drifting silently. Reasoning at the declaration site and in
tests/fixtures/README.md.
- Determinism within a version is now held by a test, not only measured once.
- Drawn content does not survive extraction. Every pdf extraction emits the
new `ExtractionWarning`: figures have no text to recover, so a bundle built
from drawn documents is incomplete by construction. Stated categorically
rather than detected — deciding "is there a figure here" is the layout
heuristic G2b declined.
Two new error codes, both mirroring existing patterns: `extractor_empty_pdf`
(a scanned/image-only PDF, refused rather than persisted as an empty concept)
and `extractor_pdf_error` (parser failure wrapped, never leaked).
Structured table recovery (G2b) is NOT implemented and is documented as out of
scope: two independent parsers return the same wrong shape, so the breakage is
document geometry, not a library choice. PDFs enter as prose.
Also corrects an install promise this change would otherwise have published:
the README no longer presents a bare `pip install 'llm-ingestion-okf[extract]'`
as working, because the package is not on an index.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HtNhsdHnMGtMi7U2mvMU8z
Order 20260821T170054Z-486638087-from-.claude (gap G2). Measurement only: no
parser implemented, no version bump, no pin move.
Measured on Handbok N200 Vegbygging (juli 2018), 308 pages, page index 150:
the registry rejects .pdf with extractor_extra_missing while .md/.csv controls
pass in the same call, and process_inbox reports the file as failed without
aborting the run. pdfplumber recovers Tabell 524.1 as 4/4 correctly paired text
lines where pypdf, pdfminer.six and pymupdf all score 0/4; both structural
extractors return the same wrong 2x6 grid, so table structure is the document's
geometry rather than a library defect. Whole book: 308/308 pages yield text,
45 of 196 detected tables are clean enough for render_table.
Verdict: text extraction is a small, bounded job; structured table recovery is a
separate project that nothing currently waits on.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013xTq1nbpz9x34udpDDExWM
The command assumes uv is present but the file never said so; an agent
with only pip would hit "command not found" with no signal that a
fallback path exists. State the Python floor and the uv requirement
up front, and point the Optional README link at the pip-only path
explicitly rather than describing it as just an "alternative".
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011mVhrxD21mPtaLMrGdixUq
Structured entry point for an AI agent already in the repo, per the
llms.txt convention (llmstxt.org): H1, blockquote summary, and the
repo's one start command in copyable form. The command is byte-identical
to README's first fenced code block, not a rewritten variant, so the
two cannot drift apart silently.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011mVhrxD21mPtaLMrGdixUq
The one-command uv install existed only as prose with a Unicode ellipsis
in place of the URL, so it could not be copied. The two-command pip path
was first and copyable, but the second command alone fails
(No matching distribution found for llm-ingestion-guard) since pip does
not resolve the transitive git dependency uv reads from
[tool.uv.sources]. Re-measured 2026-08-20 with an empty uv cache: the
one-command path still installs guard==0.2.0 + okf==0.4.0 cleanly.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011mVhrxD21mPtaLMrGdixUq
Part of the AAA+ program's C-axis (trust) sweep across the open/ org:
a stated vulnerability-reporting address and response process is what a
stranger evaluating the repo looks for before reading any code.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011WZqVHfRgn26fS6neSMU9v
Two defects on the published surface, both measured this session rather than
assumed.
org-ops' census 07 found no test command inside a fenced block in our README,
and the finding is true: the string "pytest" did not appear in the file at all.
A stranger could install the library but could not confirm it works. The block
now names the command, and says the thing the command alone would not: it needs
a clone, because the wheel packages only src/llm_ingestion_okf and tests/ lives
at the repository root. The 589-test count and the run date are measured, not
carried over.
Running org-ops' own A5 criterion ("no claim on the surface is untrue") against
ourselves found the second one. The status paragraph said phases 1 and 2 are
implemented and phases 3-4 are planned, while profiles.py:701 has shipped
STRICT_V1 since phase 3 landed. The Roadmap section and the profile table were
already consistent with phase 3 being done, so the stale claim sat alone in the
one paragraph a reader meets first.
Fixing only the first would have repeated the most expensive finding we have
recorded: writing a trap down is not running it.
Verified with the instrument org-ops supplied, against this branch:
awk '/^```/{f=!f; next} f' README.md \
| grep -icE 'npm (run )?test|node --test|pytest|vitest|jest|make test|bats'
-> 1 (was 0)
Docs only. No release, no tag, no pin movement: the guard pin and the paired
install tags are untouched, and the open release decision stays open.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UgzRG5EGPk72Mj4JN4uhQS
The public install block did not work. It paired guard `@v0.3.4` with okf
`@v0.4.0`, and `v0.4.0` declares `llm-ingestion-guard>=0.2,<0.3` — which
v0.3.4 does not satisfy. With the guard absent from any package index, pip
then fails with `No matching distribution found for llm-ingestion-guard`:
exactly the error the two-step block exists to prevent. Anyone following the
front page hit it.
Three instances of one conflation, all measured, all introduced by writing
this branch's pin into a sentence about a tag:
1. l.23 guard tag — repaired to `@v0.2.0`, which is what `v0.4.0` needs and
what `v0.4.0`'s own README already says.
2. The uv sentence claimed uv reads `[tool.uv.sources]` in "this project's"
pyproject; installing `@v0.4.0` makes uv read the *tag's* file. Measured:
that entry in `v0.4.0` points at guard tag `v0.2.0`, so the uv path was
correct and only described wrong.
3. Requirements cited `Requires-Dist: llm-ingestion-guard<0.3,>=0.2` as
verified against the wheel, under a stated range of `>=0.3,<0.4`. A wheel
built from this branch today carries `<0.4,>=0.3`; the quoted evidence was
a true measurement of the old pin left standing under the new one.
The 2026-07-25 measurement stamp is kept rather than dropped: `v0.5.0a2`'s
frozen README shows that measurement was of the guard `v0.2.0` + okf `v0.4.0`
pair, which is the pair restored here. `b9ba42d` moved the numbers away from
what had been measured while keeping the date that vouched for them.
Docs only, by operator decision. Making the block's numbers true by releasing a
stable tag that carries this branch's pin is the other repair, and it is a
release: it belongs to the open release decision, and not inside the pilot
freeze.
The trap was already written down ("the install channel depends on the tag, not
`main`") and the public README carried the defect anyway. Recording a trap is
not applying it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PoZ2ZCWdkkZ3QYMHJFRX4z
The pilot ran the widened question on their own tree and returned the axis
neither of us could see alone. A value-literal predicate has two sides — the
code that tests the literal and the code that writes it — and they need not
share a codebase. Both sides local means the day the convention moves there is
a local diff to see it in. Producing side behind a version pin means the guard
can stop guarding with no local change at all: a dependency sync is the whole
event, and there is not even a byte diff to dismiss.
The three axes compound rather than stack. Quietest: fail-open, write path,
producer on our side of the pin — nothing local changed, nothing failed loudly,
and a golden byte comparison sees none of the three. Loudest: fail-closed with
both sides local, which is what we carry ourselves (`inbox.py:218`) — recorded
as a property of where the code sits, not as care we exercised.
Provenance of all three widenings is kept in the text deliberately: pilot, then
us, then the pilot again. Each round found what the round before could not,
which is the argument for asking rather than reasoning.
Consumer repo, file, line and the predicate's purpose stay in the mailbox; the
axis is recorded unattributed, as in fcb6e4c and 2541561.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H2Z8pTafcSPgt4rETsxxEP
A pilot's finding was that the report's question ("do you have a value-literal
`generated` predicate?") invites a search of the ingest path, while the class
also lives in code that WRITES concepts — a consumer searching where they
consume our output finds nothing and answers honestly.
Running the widened question on our own tracked tree added the second axis. Our
one instance (Door B's collision gate, `inbox.py:218`) gates a destructive
action rather than trust, so it fails CLOSED: it refuses to overwrite instead of
admitting foreign content. That direction is the one a consumer dismisses on
finding it, because refusing looks safe — but it breaks the same promise, by
turning "a re-run, nothing more" into a re-run that errors on its own prior
output. Neither direction shows up in a byte comparison.
Ours is measured inert and bounded twice (Door B writes and tests the same
literal; the second conjunct `source_file` is emitted by no other door). Not
fixed here: routing it through `DEFAULT.ownership.owns` would pre-decide half of
the already-deferred Door B stamp question by binding Door B to `DEFAULT`'s
actor, which is commons' and the operator's call. Recorded in the F5/F6 class.
The consumer's repo, file and line stay in the mailbox; the class is recorded
unattributed, as in fcb6e4c.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H2Z8pTafcSPgt4rETsxxEP
The pilot reads this section as instructions, and V1 (8318605) moved
premises underneath it while the tag it points at stayed still.
- A-E1: passing at v0.5.0a2 is not a promise DEFAULT's bytes never move.
The expectation is anchored to the upstream axis; DEFAULT also tracks
commons' ingest-spec axis, and V1 moved that one.
- A-E1: the runner reported the MAF wrapper has the same shape as
po-claude's (three positional args, no `profile`), and re-exports the
library symbol, so the two profile calls have somewhere to land.
- A-E1: our empty-diff span covers our examples/ only; the runner holds
a fourth golden set we cannot pre-measure.
- A-E5: the `:164`/`:144` literals still describe the tag but no longer
`main`; dated rather than swapped.
- A-E5: re-run-in-place was recorded as undecided. It is decided, and
was already true at the tag — measured by reading v0.5.0a2, not
inferred from main.
- GA table: two rows rest on "DEFAULT is byte-stable", which V1 ended.
Plus the input the release-exposure report must carry — a value-literal
`generated` predicate fails OPEN against the O2 form, so byte-clean
goldens are not evidence a consumer is unaffected.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01X974G3Z7yXzdXK2nHnm11h
The V1 commit told nine repos, in README, CHANGELOG, the plan and two
coord messages, that upgrading across it costs a consumer a re-run and
nothing more. Nothing exercised that end to end.
What was covered: `owns()` returning True for the legacy literal at the
unit level. What was not: the consumer's actual path -- materializing
into a directory that ALREADY holds pre-V1 `DEFAULT` output. The golden
suite cannot see it, because it materializes into a fresh directory
every time.
`test_second_v0_2_run_into_the_same_directory_succeeds` is the same
shape for `OKF_V0_2`, and its comment already said why one byte-compared
run cannot catch this. V1 made `DEFAULT` change its stamp exactly as D2
made `OKF_V0_2` change its own; no equivalent test followed it until now.
The legacy bundle is derived from a real run rather than hand-authored,
so every byte except the stamp is what an earlier version actually
wrote, and two assertions guard the derivation against silently becoming
a no-op the next time the stamp moves.
Hand-mutated to confirm it can fail: making `owns()` return the legacy
literal only for an actor-less profile turns it red with
`collision_unstamped` -- which is precisely the consumer-visible failure
the promise rules out.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VwcjUXbKySLbEG5WqTNkta
Commons ratified V1 2026-08-02 and executed it at `54e0ec7`; verified
against their tree rather than taken on report. ingest-spec.md:217 now
defines `generated` as `{ by: process:okf-ingest, at: <ingested_at> }`,
unquoted, `at` repeating `ingested_at` verbatim. `generated: true` no
longer appears in the spec.
`DEFAULT` states commons' §5 layer, so its stamp is theirs to decide.
`DEFAULT.ownership` gains the actor; the four goldens this repo's plan
named in advance were regenerated by RUNNING the materializer, each on
its own case's `ingested-at.txt`. The v0.2 golden was untouched, as
predicted -- it has carried the O2 form since D5.
Not a migration onto OKF v0.2: `DEFAULT` stays v0.1 on every axis
upstream owns and still emits no `sources`. Commons' spec and the Google
version are independent axes, and comments that narrated them as one
were rewritten rather than left to mislead. README and CLAUDE.md said
the additive rule without that boundary, which would have told a
consumer their DEFAULT bytes can never move; both now state it.
V-A3 is amended, not dropped. `DEFAULT` must OWN the mapping it now
writes -- a profile refusing its own output fires the collision gate on
files its own previous run wrote -- while a mapping naming a foreign
actor, or §7's `human:` actor on curated content, stays unowned. That
half is what carried the safety and it is asserted directly.
§11's stamp-integrity condition moved with the value: the forgeable
stamp was `true` and is now the mapping naming the ingest actor. The
defence was never the value -- the §3 scan globs `ingest-*.md`, so a
Door C import is unreachable however well it forges. Second spoof test
added; both were hand-mutated (glob widened to `*.md`) to confirm they
can fail.
The characterization test derived its foreign-stamp fixture from the
literal `generated: true`, which V1 leaves without a referent -- a
silent no-op waiting to happen. It now derives the needle from the
profile and asserts the substitution occurred.
Door B is deliberately untouched: not the ingest-spec's, marker is
`generated` + `source_file`, disjoint from Door A's `ingest_manifest`,
and the divergence predates V1.
Nothing released or notified. The pilot set pins `v0.5.0a2`, not `main`,
so this is invisible to portfolio-optimiser's freeze and demo; the
consumer exposure report is owed at the release that carries this.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VwcjUXbKySLbEG5WqTNkta
Test A's procedure still said "install the package at the v0.5.0a1 tag", and
the test-spec preamble said all three tests read from v0.5.0a1. That tag is
abandoned: it carries the excluded generated.by actor id.
This was a live hazard, not a stale reference. Installing it is exactly the
A-E5 failure this doc warns about -- a pilot would hold bundles the library
stops recognising the moment the id is corrected, hitting collision_unstamped
on their own files. It survived because the heading and the CHANGELOG were
corrected when the tag was abandoned while the procedure text underneath was
not, so the section contradicted itself.
Latent until now because no pilot was reading the procedure as an instruction.
Re-pointing Test A to portfolio-optimiser in 7d9bc0c is what made these lines
live again, which is why the fix belongs with that change rather than after it.
The message already sent to portfolio-optimiser never names a1 and gives the
v0.5.0a2 install channel explicitly, so no correction is owed to them.
The remaining a1 mentions are historical records of what the abandoned tag
required and why, and are left as written.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TgTrQdexGdLYmt1ZMenPyC
Operator decision 2026-08-09, on their request. po-claude is parked until the
MAF version ships, so Test A's verdict is not coming from the original
producer.
The admission is about the axis, not the headcount. With po-claude parked, no
original pilot member could EMIT a v0.2 bundle at all -- claude-code-llm-wiki
is read-only in the pilot and catalog is gate-side -- so GA exit criterion 5's
emit half had no possible runner. portfolio-optimiser consumes the same Door A
and is the D7 sibling of the parked repo, which makes it a substitute for the
axis rather than a fourth opinion on it.
A-E1 now measures a wider span than it was written for, because they are
pinned at v0.3.2. Measured rather than asserted: the three DEFAULT goldens are
byte-identical v0.3.2 -> v0.5.0a2, so the measurement can be cited instead of
asking them to trust the additivity promise.
CHANGELOG amends the pilot set under [Unreleased] rather than editing the
released v0.5.0a1 entry, which records what was true when that tag shipped.
It also states the guard pin that tag actually carries (>=0.2,<0.3, resolving
against guard v0.2.0), since main has since moved to >=0.3,<0.4.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TgTrQdexGdLYmt1ZMenPyC
Catalog ran Test B on 2026-07-31 and confirmed all three expectations, but
the verdict existed only as a coord message. GA exit criterion 1 requires
every P1-P3 finding to be fixed or explicitly accepted "with the reason
recorded in this doc" -- a result readable only in a mailbox cannot be
audited by the consumers this doc is written for, so criterion 1 could have
been closed against a record nobody could check.
Records the reader revision and source hashes (B-E3 is unreadable without
them), the three confirmations, and all three findings with dispositions:
the `timestamp` RECOMMENDED warning (accepted, catalog's own upstream drift,
not ours to fix), `resource`/`description` (accepted as UNMEASURED, not as
clean -- catalog refused to let them read as fine), and the two gates that
were not run (their words: "not run" must not read as "as expected").
Also corrects a measured-false claim in the same file: Test B does not run
on Test A's output. Its procedure says `examples/` at the tag, and that is
what catalog archived. The two signals were never serialized, so Test A's
absence never gated catalog.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TgTrQdexGdLYmt1ZMenPyC
The code span holding `* [Title](link) - description` wrapped across a
line break, so a line-oriented reader sees `[Title](link)` as a real
link into docs/ and reports a broken target. The three sibling
occurrences in this repo all keep the span intact on one line; this one
was incidental wrapping, not a decision.
Reflowing is the local fix. It is not the same as widening a checker's
code-span stripping to span line breaks, which this repo argued against
on 2026-08-03: that would hide the class instead of resolving it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TJUFZhHzf9AqLucMsJy6u1
The repo-standard gate (v0.1.1, class `standalone`) flagged two ERRORs on the
first screen. Both are about a reader who arrives from outside:
- The opening line now repeats the forge description verbatim. That is the
only place where description, catalog and README can be machine-checked to
agree; a paraphrase reads fine and is unverifiable.
- `## Install` exists as a heading, on the first screen, with the commands
under it. They were previously buried in `## Requirements` two screens
down, which is where a human eventually finds them and an agent does not.
`## Requirements` keeps the dependency policy and the direct-reference
rationale, and points at `## Install` for the commands.
The Install block also states which tag a stranger should pin: `v0.4.0` is
stable, `v0.5.0a2` is the OKF v0.2 pilot pre-release and is not for general
use. Nothing else moved; the body below the first screen is unchanged.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TJUFZhHzf9AqLucMsJy6u1
Operator, 2026-08-02: no MCP, no data lakes, no databases without a
stated need. We run on what we have -- defect fixes, improvements, and
features a consumer actually asked for.
That supersedes the 2026-07-27 line calling phase 5 committed, which
this file still carried. A roadmap that promises work nobody asked for
is a queue that generates its own deadlines, and the sql-is-sqlite-only
"gap" is the clearest case: closing it buys runtime dependency number
two for no asked-for use.
Phase 4 is not demoted the same way -- four named consumers have working
implementations to lift, so the need is real but untriggered. It starts
when one of them asks.
The upstream version policy is stated as the one exception and why: it
is a promise already made, so an upstream release is itself the need.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JxRjDS9U2szUGYDeuZB2M3
The notice po-claude was promised "before GA, not with it" went out
2026-08-02. Two places said otherwise and are now false in a tracked
public doc: the "Owed and unsent" paragraph and GA criterion 9's tail.
The paragraph also records what the message corrected rather than only
what it announced: our 2026-07-31 advice against binding to
OwnershipPolicy.owns stands, but the reason given then (it costs them a
dependency) was not the load-bearing one -- phase 4's Node half is.
A consumer building on the wrong reason builds the right thing by
accident.
Criterion 9 stays as the GA backstop; only its notice half is closed.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JxRjDS9U2szUGYDeuZB2M3
We told po-claude the notice lands before the GA release rather than with
it. A criterion verified at GA cannot enforce that ordering — as written it
would let the notice slide to GA day and still pass. Says so explicitly.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JxRjDS9U2szUGYDeuZB2M3
Two records, both from decisions that had already fallen but were living
only in a mailbox thread.
1. The ownership contract (operator, 2026-08-02). The byte form of
`generated: { by: process:okf-ingest, ... }` is the intended contract;
`OwnershipPolicy.owns` is its canonical implementation for Python
consumers, not the contract itself. The deciding argument is phase 4:
the Node half shares the contract and the fixtures but never the code,
so a Python API cannot be load-bearing there. The guarantee is
formalised at GA rather than now, because the profile is provisional on
a pre-release precisely so pilot feedback can still move the surface.
Recorded as GA exit criterion 9, including the notice still owed to
po-claude.
2. V6, measured end-to-end against the real guard (v0.3.4) instead of the
stub gate the D4 tests use. Both canonical §10 pointer forms are
rejected by the guard's grammar before `unverified_references` can see
them; the only shape that reaches `merged` today is the non-conformant
one-key block sequence the guard recorded as its own defect. So the
report is empty against everything conformant, and pre-empts no grammar
decision of theirs. Sent to them the same day.
586 tests green.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JxRjDS9U2szUGYDeuZB2M3
Measure first, widen after. The 19-fixture guard-surface suite was re-run
against v0.3.4 in a scratch venv before the range moved, and reproduced the
three deltas measured against v0.3.3 exactly, with none added. v0.3.4 is the
tag pinned rather than v0.3.3 because it shipped first and repairs a quadratic
regex (okf._MD_LINK_RE) that sits on Door C's own call path.
Door C now passes allow_reserved=False explicitly. The guard added the keyword
in the 0.3 line and defaults it True for received bundles, which would merge a
sender's index.md / log.md instead of rejecting them. The override keeps the
unconditional reserved-name refusal committed to before the keyword existed,
and the reason is structural rather than a second opinion on the guard's scan:
Door C generates the merged bundle's index.md from what it merged and writes
every merged concept verbatim, so a sender's index.md would be a second and
irreconcilable claim on one path.
This is not a behaviour change for anyone on the previous pin: under v0.2.0
the keyword did not exist and reserved names were refused by construction.
The floor is >=0.3 and not >=0.2 for a measured reason. allow_reserved is
absent in v0.2.0 and present from v0.3.0 onward, checked across all five tags:
a >=0.2 floor would admit a version that raises TypeError on every Door C
import. That measurement also corrects a recorded premise -- the plan said the
keyword "shipped in v0.3.3", which read the first version we ran the suite
against as the version it was introduced in. The conclusion held; the reason
did not, and the reason is what a future bump would have relied on.
test_door_c_pins_allow_reserved_false_against_the_guards_default locks both
halves: that the guard still defaults True, without which the override is a
no-op that would pass forever over nothing, and that Door C overrides it.
586 tests, mypy --strict clean, goldens byte-identical.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V2v1hrDhrff2H3y2TNJHkF
The §3 ownership scan globbed every *.md file regardless of which door
wrote it, then unconditionally unlinked whatever _is_ingest_owned agreed
to. Because _is_ingest_owned reads through the line-oriented parser that
flattens nested blocks (pinned in
test_two_nested_block_mappings_sharing_a_key_collide_in_the_scalar_parser),
a Door B/C file whose nested content happened to share a key name with
the ownership markers (generated, ingest_manifest) could get promoted to
top level and spoof ownership -- silently deleting content this door
never wrote.
Scoping the glob to ingest_prefix closes this by construction: a Door
B/C file is never even a candidate for the scan, regardless of what its
frontmatter parses to. Traced from a coordination tip from
portfolio-optimiser-claude about the same flattening mechanism hitting
their `type` field.
The code already normalizes filenames and titles to Unicode NFC
(materialize.reduce_to_id_grammar, inbox.process_inbox) because macOS/APFS
hands filenames over decomposed, which would otherwise split one visual
title into two generated filenames. The invariant was implemented but not
documented anywhere in the repo.
Guard v0.3.3 added allow_reserved (default True) to okf.import_bundle,
reversing the phase-2 plan's "reserved-name rejection is unconditional"
reading -- an unqualified call would now merge index.md/log.md instead
of refusing them. Decided: pin allow_reserved=False explicitly at the
pin bump, keeping the original commitment. No code change yet -- the
installed pin is still v0.2.0, where the kwarg does not exist.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KZPHJpPeSMzVqvbQRxh2Ux
Three plan statements the session's work overtook:
- D4 records what shipped, including the part deliberately left undone
(reading §10's block form) and the invariant that falls out of it.
- V6's "our leaning, for them to accept or overrule" is superseded:
refuse became import-and-report. The leaning had a problem the prose
could not see — §14 forbids rejecting a bundle over a broken
cross-link and does not settle whether `executor.resource` is one,
while §10.5 asks a consumer to surface. Reporting honours the
unambiguous rule without testing the ambiguous one.
- What stays with the guard is restated rather than assumed closed:
whether a non-`.md` code file is within `okf.import_bundle`'s mandate
is untouched by this, and the execution boundary still has no owner.
Also recorded: the report is key-level because the resource-level value
is the one the parser cannot recover in either canonical form. A
measured limit, not a preference.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KKKMwi7e7PVHoFW6dJK5XP
V6, settled by the operator today: import and report, not refuse.
Door C imports the POINTER to executable code and never the code — it
writes concepts verbatim and skips every non-`.md` file. So an imported
Attested Computation can name an `executor`/`attester` resource that did
not arrive, or one that RESOLVES against a file the destination tree
already holds under that path. The second is the outcome worth
surfacing: it looks valid.
Refusing was the plan's leaning and is not what shipped. §14 forbids a
consumer to reject a bundle over a broken cross-link and does not settle
whether `executor.resource` is one; §10.5 asks a consumer to surface
rather than silently drop. Reporting honours the second without testing
the first, and leaves the door's one invariant — verbatim bytes — alone.
`ImportResult.unverified_references` is an advisory over the merged set,
not a fifth bucket: every concept it names has already merged, the
bytes are unchanged, and a refused concept is never named (there is no
imported pointer to check).
The report is at KEY level, and that is a measured limit rather than a
choice. Resolving the resource means reading `executor.resource` — the
value the line-oriented parser cannot recover in either canonical form:
a block mapping flattens and collides, a flow mapping stays one opaque
string. A resource-level report would be empty or wrong on exactly the
forms upstream writes. Precision arrives with the structured reader
(D1b); the key-level signal is robust in both forms today.
[skip-docs] is on the CLAUDE.md half only: README carries the new
public surface (`unverified_references`), and the invariant this work
put in CLAUDE.md — flow form, never block — landed with the previous
commit and needs no restatement.
584 tests, mypy --strict clean.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KKKMwi7e7PVHoFW6dJK5XP
Upstream §10 adds a concept type carrying a sanctioned way to compute a
value. This lands its FORMAT: the five contract fields for emission and
round-trip, and §10.2's one requirement. No execution — upstream defers
the receipt and verdict wire formats, so there is nothing to build a
runtime against.
Two additions, both additive:
- The five fields (`runtime`, `parameters`, `computation`, `executor`,
`attester`) join `OKF_V0_2`'s emission order as one block, internally
in §10.2's own listing order. Without it they still emit — in `emit`'s
sorted tail, where `attester` precedes `runtime`, alphabetical order
standing in for the contract's own. No bundle that carries none of the
keys changes by a byte, and the v0.1 profiles gain nothing.
- `FrontmatterSchema.required_by_type` expresses "`runtime` is REQUIRED
for this type and no other" — the first rule here keyed off a
frontmatter VALUE rather than a key. It cannot be `required`, which
would demand `runtime` of every document. A type the mapping does not
name carries no extra requirement, which is what keeps it inside §14:
a consumer must not reject on an unknown `type`, so a conditional
keyed on an unknown type stays silent rather than guesses.
Also pinned, measured today: the line-oriented parser cannot read §10's
canonical BLOCK form. `executor` and `attester` both carry a `resource`,
and with no indentation model the second overwrites the first —
`executor.resource` is lost silently, no error. Characterized rather
than fixed: reading that form needs the structured reader (D1b), and a
half-reader that drops half a contract is worse than one that never
claimed to read it. CLAUDE.md gains the invariant that falls out of it:
we emit flow form, never block, or we write bundles we cannot read back.
578 tests, mypy --strict clean, goldens byte-identical.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KKKMwi7e7PVHoFW6dJK5XP
Upstream requires `pyyaml>=6.0`; 6.0.3 is what the measurement happened to run
under. Writing the latter as "the version upstream requires" is the same class
of imprecision the surrounding paragraph exists to correct.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012gwLPe5TY5aN3o3tejv9Nh
V-A8 was scheduled to be WEAKENED to parse-and-render on the standing claim
that "there is no validator in okf/". Enumerating the repository tree instead
of that one subdirectory falsified it: OKFDocument.validate() sits at
okf/src/reference_agent/bundle/document.py:58 inside a working v0.2 reader.
So V-A8 ran as written, and passed 13/13 against
examples/ingest-golden-okf-v0-2/ at pinned 3fcbb9f. It needs nothing installed
-- document.py imports only yaml -- so .venv and the one-runtime-dependency
rule are untouched. The load-bearing assertion is not validate() (which checks
a single key, `type`); it is that a REAL yaml parser recovers our inline flow
forms as structures: `generated` as a mapping, `sources` as a list of mappings.
Our own parser is line-oriented and reads both as opaque strings, so no test of
ours could ever have answered this.
Second falsified premise, in the A-E6 rationale itself: "yaml.safe_load returns
"0.2" whether or not it was quoted". Measured against PyYAML 6.0.3 (the version
upstream requires), unquoted loads as float 0.2 and quoted as str '0.2'. The
BOM half of the same sentence is true. Correcting it surfaces what it hid --
unquoted `0.10` loads as `0.1`, indistinguishable from v0.1, and the type is
not stable across version shapes (`0.2` float, `0.2.1` str). Upstream's only
written instance, SPEC.md:773, is quoted.
That changes nothing today and D5 is NOT requoted: at 0.2 both forms are
unambiguous, and neither consumer reading the key parses YAML. It is recorded
because okf_version's value belongs to catalog (E1), so it is a constraint we
owe them, not a choice we may make for them.
Runbook: Step 2 now enumerates the REPOSITORY root, not okf/ -- the same
mistake this step already warned about, repeated one level up (toolbox/ and
samples/ sit outside okf/; 265 tracked files, 48 py + 43 ts, none of it on any
list). New Step 3a carries the V-A8 procedure per upstream release, including
that it can never be a pytest test and why.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012gwLPe5TY5aN3o3tejv9Nh
v0.5.0a1 shipped the one actor value the spec owner had already excluded.
Caught before any pilot was notified, so it costs a tag, not a migration.
Commons decided <fast id> = process:okf-ingest on 2026-07-31, on this repo's
own proposal, superseding option (d) (process:llm-ingestion-okf) chosen here on
07-27. The exclusion is ingest-spec.md:7-8, frozen on the spec being
framework-neutral: normalising OUR repo name into the normative id would force
every other conformant implementation to write it into its own output. Verified
against three independent sources before touching anything — commons' coord
message 20260731T154140Z, their plan :215-216/:244, and their STATE :37.
Why this had to land before the pilot notifications rather than after:
actor is both the stamp written and the value owned back (OwnershipPolicy),
and recognition is one-way. A pilot that had run Test A against the excluded
id would hold bundles this library stops recognising the moment the id is
corrected — collision_unstamped on their OWN files. That is the A-E5 failure
mode, and we would have inflicted it.
Worse, it would not have shown up as a failure: the plan's A-E3 expectation
(:854) named the same excluded value as the code, so Test A would have PASSED
and confirmed the error. Expectation and implementation agreeing is not
evidence when both predate the decision.
Nothing in the wild carried the old value: OKF_V0_2 did not exist at v0.4.0, so
the profile has never been released. v0.5.0a1 is abandoned, not moved — a tag
already on a public remote does not get force-pushed, and the history should
say plainly that a1 was wrong.
A-E3 now records both corrections with dates. The V1 paragraph at :1169 is
superseded in place rather than rewritten: its reasoning still holds, only its
outcome moved.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CVTup4v7tW9QiVyBENk2LV
The tag was specified to land on 128109b, where the package still declared
0.4.0 in both places a version is written. The pilots install FROM the tag, so
they would have pinned a pre-release that reports the previous release.
Two requirements the "minimally requires" list did not cover, both stated
elsewhere in the plan:
- The CHANGELOG entry is load-bearing, not ceremony: the plan makes the
provisional status real by having the profile docstring AND the entry both
say the surface may change without a deprecation cycle, and name the pilot
repos. The docstring had it (profiles.py:694); the CHANGELOG stopped at
0.4.0.
- pyproject.toml and __init__.py both said 0.4.0.
Nothing in the run path reads __version__, which is why a stale one survives a
green suite. test_the_declared_version_agrees_with_the_packaged_one is the only
machine check on it — written failing first, against a one-sided bump. The tag
NAME remains a human step; no test can catch that one.
README keeps pointing at v0.4.0 on purpose: a pre-release for three named
pilots is not the general install line, and OKF_LATEST does not move until GA.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CVTup4v7tW9QiVyBENk2LV
Three corrections to the alignment plan, two of them because a fact a peer
repo gave us stopped being true.
**P1 dispositions.** F1 is fixed before the tag; the other five are not. The
line is whether a finding bites in code the pilots will pin. F1 did. F2/F3
do not: measured, all three `TypePolicy.rejection` call sites hard-code
`DEFAULT.types`, and both `DEFAULT` and `OKF_V0_2` set `allowed=None`, so the
closed-set branch is unreachable in shipped code and fires only for a caller
constructing `STRICT_V1` directly — which is what the sweep did. Dequoting in
`TypePolicy` would repair a write path that never sees a quote, and would fix
the meaning of a quote without a value model able to express one. F2/F3/F4
are one root cause and go to D1b; F5/F6 stay P4's.
**A-E6's reason did not survive, though the expectation did.** It justified
"unquoted" as a property of catalog's gate — their shape regex read quotes as
part of the value and so rejected upstream's own §12:773 example. Catalog
resolved that in `1ca27f6`: from spec 0.3 the value is unquoted before the
form check and both forms pass. The expectation stands on a different ground
now, supplied by commons the same day: `method-spec.md:90` parses frontmatter
line-oriented, so a quote is a character in the value rather than syntax a
parser removes, and upstream emits the same way. Recorded as a supersession
rather than swapped silently — reading a stale rationale as current is this
expectation's own defect class.
**TEST B must name the reader revision.** `okf-check.mjs` changed in the same
commit, and the reader's placement-blindness is now a deliberate choice
rather than an unanchored regex. A report that does not say which revision it
ran is not reproducible.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JqCmfJ2ukpFXeFjfab8wvy
