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

docs(okf): STEG 5 — placement is descriptive, not normative

Browse source 
The sample does not support a mandated path form. Of the four consumers
polled, exactly one installs a bundle anywhere (okr: project .claude/okr/
ahead of home ~/.claude/okr/org/); the other three install none — the
bundle dir is a caller-supplied argument per run, with no default, no
discovery, and no $HOME/~ expansion in their sources (verified by grep in
each repo, not taken from their reports).

One installation and three non-installations makes the standing criterion
("three installations before normative text") unmeetable from this
population, so no normative path form was written.

- spec.md §1: correct the in-scope example. A lone `~/.claude/<plugin>/…`
  misstates okr's project-first precedence, i.e. it contradicts the only
  real implementation — a fix that stands on its own regardless of n.
- spec.md §8: placement unmandated; "no installation root" named a
  conforming consumer shape; installing vs. writing marked separate axes
  (a consumer may write into a bundle it never placed).
- log.md: the measured sample with file:line evidence, plus two findings
  the responses did not supply — neither portfolio-optimiser repo reads
  okf_version at all (so neither is evidence for or against marker-based
  discovery), and p-o-claude has a third --bundle entry point that does
  carry a fixture default, contra its own account.

Confirms distilled note 3 ("discovery, not placement") rather than
extending it, and bears on Stage 2 (§10): three of four consumers have
nothing to discover.

Verified: suite 73/73 across the six test files; check-versions 10 OK ·
1 WARN · 0 ERROR (okr 1.8.0 untagged — their release is still in flight).

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 12:28:28 +02:00
commit 3ccb5f6afa
2 changed files with 52 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

38
docs/okf-second-brain/log.md
View file

@ -235,6 +235,44 @@ protocol; 🟢 is reserved for the independent gate-verified step (operator veri
`check-versions.mjs`/`release-plugin.mjs` operate only over `marketplace.json` entries).
Verified: full suite **73/73** across the six test files; `check-versions` 11 OK · 0 WARN · 0 ERROR.
_(catalog session.)_
- **2026-07-25** — **STEG 5 (installation root) settled as _descriptive_, not normative: the sample
does not support a mandated path form.** The ecosystem was asked where each consumer installs its
bundle. Every answer was given **against code, not docs**, and each was re-verified here before
being acted on:
- **okr** — the only real installation. Two roots: project `.claude/okr/` **ahead of** home
`~/.claude/okr/org/`, each checked per-root (okr `scripts/okf-check.mjs:11`,
`lib/innboks-write.mjs:44`).
- **portfolio-optimiser-commons** — declined, correctly. Spec owner with no runnable pipeline; its
only bundle-shaped bytes are conformance fixtures, so answering would have codified a **test
artifact as an installation site**.
- **portfolio-optimiser** — **no root.** `--bundle-dir` defaults to `None` (`run.py:653`); absent
it, the feature is simply off. Verified here: **0 hits** for `expanduser|Path.home|.claude/`
across `src/`.
- **portfolio-optimiser-claude** — **no root.** `--bundle` defaults to `None` (`run.py:554`);
`bundle_dir` is a required non-empty config field (`contracts.py:81`). Verified here: **0 hits**
for the same patterns across `src/`.
**One installation, three non-installations** — so the standing acceptance criterion ("three
installations before normative text") is not merely unmet, it is **unmeetable from this
population**. Landed in `spec.md` as exactly two things: the §1 in-scope example corrected (it
showed a lone `~/.claude/<plugin>/…` form that misstates okr's project-first precedence), and a new
§8 bullet naming placement unmandated, **"no installation root" a conforming consumer shape**, and
*installing* vs. *writing* separate axes (a consumer may write into a bundle it never placed).
**No normative path form was written.**
Two things the responses did not supply, both found here: **(a)** neither portfolio-optimiser repo
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 — `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.
This **confirms distilled note 3 ("discovery, not placement") rather than extending it** — the
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.)_
## Distilled architecture notes (OKF round, 2026-07)