docs(okf): §1 — okr's two roots are not one ordering

The reference impl read the STEG 5 text and objected to one word: §1 said
okr "runs per-root over a project root … ahead of a home root". Verified
here against their code rather than their report, the objection holds —
that phrasing fused three distinct behaviours into one.

- profile axis is precedence (inject-okr-context.mjs:54-56 short-circuits
  on the project hit)
- retrieval axis is union (okr-second-brain-search/SKILL.md:94 globs both
  roots; they carry different content — project is cwd-bound cycle/work
  data, home is org identity that survives reinstall)
- checking is neither (okf-check.mjs:11 runs each root independently)

So "ahead of" was true of exactly one axis and false as a statement about
the only implementation §1 describes.

Fixed by deletion, not elaboration: §1's job is that placement is not in
this contract, and that claim never needed an ordering. The axis detail
goes to log.md instead — naming one consumer's internal resolution order
in a scope section is the same class of leak the format exists to keep
out.

Placement remains unmandated (§8); nothing in the contract changed.

Verified: suite 73/73 across the six test files; check-versions 11 OK ·
0 WARN · 0 ERROR (okr released v1.8.0 mid-session and bumped the catalog
ref themselves in 8afd4f0).

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:17:15 +02:00
commit 3aea016074
2 changed files with 22 additions and 1 deletions

View file

@ -273,6 +273,27 @@ protocol; 🟢 is reserved for the independent gate-verified step (operator veri
measured population is dominated by that chain's first link, an explicit caller-supplied param. It
also bears on **Stage 2 (§10)**: the evidence points *away* from a Stage-3 discovery convention,
since three of four consumers have nothing to discover. _(catalog session.)_
- **2026-07-25****§1 corrected again: okr's two roots are not one ordering.** The reference impl
read the STEG 5 text and objected to a single word — §1 said okr "runs per-root over a project root
*ahead of* a home root". Verified here against their code, not their report, and the objection
holds: that phrasing **fused three distinct behaviours into one**.
- **Profile axis — precedence.** `hooks/scripts/inject-okr-context.mjs:54-56` resolves
`existsSync(projectConfigPath) ? projectConfigPath : (existsSync(homeConfigPath) ? … : null)`.
Genuine most-specific-wins; the project hit ends the lookup.
- **Retrieval axis — union.** `skills/okr-second-brain-search/SKILL.md:94` says "**Glob both
roots**" and does *not* short-circuit on the project root. The roots carry **different content**,
not two versions of the same: project = cycle/work data (cwd-bound), home = org identity
(survives reinstall). Their own source comment states it (`inject-okr-context.mjs:51-53`: "only
the org PROFILE resolves to home").
- **Checking — neither.** `scripts/okf-check.mjs:11` ("Kjoeres PER ROT") runs each root
*independently*: no precedence, no union.
So "ahead of" was true of exactly one of the three axes and false as a general statement about the
only implementation §1 describes. Fixed by **deletion, not elaboration** — §1's job is that
placement is not in this contract, and that claim never needed an ordering. The axis detail lives
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.)_
## Distilled architecture notes (OKF round, 2026-07)

View file

@ -18,7 +18,7 @@ retrieval skill (if ever justified — §10) has one contract to build against.
- **In scope:** the user's own context/data — the per-user second brain. **Where** that brain sits on
disk is *not* part of this contract (§8): the reference impl (okr) runs per-root over a **project**
root (`.claude/okr/`, cwd-relative) *ahead of* a home root (`~/.claude/okr/org/`), and other
root (`.claude/okr/`, cwd-relative) and a home root (`~/.claude/okr/org/`), and other
consumers install no root at all. A single `~/.claude/<plugin>/…` example would misstate both.
- **Explicitly out of scope:** each plugin's **domain reference files** (skill `references/*`). Those
stay native Claude Code skill-references (Anthropic-recommended progressive disclosure). The decisive