open/ktg-plugin-marketplace
1
0
Fork 0
Code Issues Releases Activity

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

Browse source 
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
Download patch file Download diff file Expand all files Collapse all files

2
docs/okf-second-brain/spec.md
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