docs(okf): method correction — the grep proved less than we claimed

p-o-claude re-measured their own source after our (b) finding and sent
back the root cause. It generalizes past them, including to us.

The counting error: their --bundle surface is four sites, not three
(run.py:554 default=None, run_s10.py:46 has a fixture default,
hitl.py:290 append/no default, contracts.py:81 required field).
Verified here against their tree, not their report.

The same blind spot in our own work: we greped both PO repos for the
installation-root signature (expanduser|Path.home|.claude/), got 0 hits,
and reported "no default". The grep was sound; the inference was wider
than it supported. Enumerating declarations instead surfaces one neither
side had reported — portfolio-optimiser's simulation.py:48
_default_bundle_dir() -> shared_root()/examples/bygg-energi-mikro, used
at simulation.py:293. Both PO repos carry a fixture-shaped default, not
just p-o-claude.

The headline is unchanged and survives contact: a fixture default aimed
at golden bytes creates no installation root and is not user-owned
second-brain state. Still one installation against three
non-installations; STEG 5 stays descriptive; §8 untouched. What changed
is the support — "caller-supplied with no default" was too strong, and
the accurate claim is the narrower one the grep actually proved: no
installation root anywhere in either src/.

Citations now pinned to commits rather than lines (PO 9e149c6, POC
bf50d2c) — portfolio-optimiser landed 8+ commits the same day and
already invalidated run.py:653, now run.py:679.

Verified: suite 73/73; check-versions 11 OK · 0 WARN · 0 ERROR.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CPHvLhn2U3j2XD3Cn8zeYa
This commit is contained in:
Kjell Tore Guttormsen 2026-07-25 15:25:53 +02:00
commit 9e98f51b9f

View file

@ -264,7 +264,8 @@ protocol; 🟢 is reserved for the independent gate-verified step (operator veri
reads `okf_version` at all (**0 hits** in `src/` for both), so neither is evidence for *or against*
marker-based discovery — though p-o-claude's fixture *carries* the marker, so a marker-based reader
would still recognise it. **(b)** p-o-claude's own account ("two entry points, both with no
default") is inexact: `run_s10.py:46` is a **third** `--bundle` entry point and it *does* carry a
default") is inexact: `run_s10.py:46` is a **third** `--bundle` entry point _(superseded — the full
set is **four**; see the method correction below)_ and it *does* carry a
default — `parents[2]/shared/examples/bygg-energi-mikro`, a repo-relative fixture. That leaves their
headline standing (no `~`/`$HOME`/`.claude` anywhere in `src/`) but it is the same
fixture-as-location class commons declined to answer from; returned to them.
@ -294,6 +295,35 @@ protocol; 🟢 is reserved for the independent gate-verified step (operator veri
here rather than in the spec: naming one consumer's internal resolution order in a scope section is
the same class of leak the format is meant to keep out. **Placement remains unmandated (§8);
nothing in the contract changed.** _(catalog session, on okr's correction.)_
- **2026-07-25** — **Method correction: a root-signature grep licenses "no installation root", not
"no default" — and we drew the wider conclusion too.** p-o-claude re-measured against their own
source after our (b) finding and reported the root cause, which turned out to generalize past them.
Citations pinned to commits, not lines — both consumer repos move faster than this doc
(portfolio-optimiser landed 8+ commits the same day, which already invalidated one line number
below).
- **The counting error.** p-o-claude's `--bundle` surface is **four** sites, not the three implied
above (@`bf50d2c`): `run.py:554` (`default=None`), `run_s10.py:46` (**has** a default —
`_DEFAULT_BUNDLE`, `run_s10.py:40`), `hitl.py:290` (`action="append"`, no default), and
`contracts.py:81` (required config field). Verified here against their tree; correction accepted
as theirs.
- **The same blind spot in our own measurement.** We greped both PO repos for the
installation-root signature (`expanduser|Path.home|.claude/`), got **0 hits**, and reported "no
default". The grep was sound; the inference was wider than the grep supported. Re-measuring
portfolio-optimiser by enumerating the declarations instead surfaces one **neither side had
reported**: `simulation.py:48` `_default_bundle_dir()``shared_root()/examples/bygg-energi-mikro`,
used at `simulation.py:293` (@`9e149c6`). So *both* PO repos carry a demo/fixture-shaped default,
not just p-o-claude.
- **Also stale:** the `run.py:653` citation above is now `run.py:679` (@`9e149c6`). The fact
(`--bundle-dir`, `default=None`) stands; the line does not.
**The headline is unchanged, and this is why it survives contact:** a fixture default resolved from
`__file__` or a re-pointable shared root aims at golden bytes, creates no installation root, and is
not user-owned second-brain state. The sample stays **one installation against three
non-installations**, STEG 5 stays descriptive, §8 is untouched. What changed is the *support*: "the
bundle dir is caller-supplied with no default" is too strong as written, and the accurate claim is
the narrower one the grep actually proved — **no installation root anywhere in either `src/`**.
Standing rule for the next round: ask for the enumeration, not the null result — a search shaped
like an install path cannot see a fixture path. _(catalog session, on p-o-claude's correction.)_
## Distilled architecture notes (OKF round, 2026-07)