Ratified Q3 resolution: the navigator must traverse hierarchical bundles;
door A stays flat (ingest-spec unchanged). Replaces the path-separator ban
with resolve-and-boundary-check as one change (decision record §3 item 6):
link syntax normative (/ = bundle root, never fs-absolute; else relative;
nested allowed, escape not), depth-first first-seen traversal, dedup on
resolved path, one segment per level, missing index.md binds the root
alone, verdict-exclusion = type check per reached file (recursive, never a
graph property), flat read-context render. Robustness now covers malformed
targets (skipped never raised) — closes the null-byte class at spec level.
Two §11 seams. Framework-neutral; backward-compatible (golden unaffected).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VUCuNNvnCkayuUDy2WFgeU
Answering question 3 from the OKF round (flat vs hierarchical bundles) turned
up a conflict that is real in code, not just between two spec texts:
method-spec.md:66-69 skip any link target containing a path separator
okf.py:123-125 `if "/" in target: continue` — implemented as written
okf-index.mjs:110 okr emits `${sd}/index.md`
okf-links.mjs:23 okr *requires* a leading `/`
So every link okr produces is skipped by the navigator, and okr cannot write a
flat bundle at all (routeLevel always returns a subdirectory). Worse, the
robustness rule at :72-73 mandates that the skip be silent — a hierarchical
bundle yields a read-context of the root index and nothing else, with no error.
On okr's own okf-realistic fixture all 8 concept files vanish.
The separator ban is the wrong proxy for the security property it wants: it
conflates "contains a separator" with "escapes the bundle". Method-spec already
carries the precise rule two lines below (:73, boundary-checked, fail-closed),
and okr has correct prior art (okf-links.mjs:20-26).
Direction: let navigation traverse hierarchy; keep door A flat in v1. This is
also what makes a shared Python/Node fixture suite possible at all.
Neither spec is edited. Decision is the operator's.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HBJNsFsBRaAhqGKjjiGjoQ
llm-ingestion-okf is blocked: door A has no free-text connector. Assessment
requested by the implementation repo; this is direction, not a spec edit.
Recommendation: solve in the spec. The real defect is that §5 conflates source
type (transport) with body form — `http` already renders verbatim, so the
verbatim mode exists but is bound to the wrong axis. Separate them with an
extraction-level `render: table|verbatim`; no new source type needed.
Also specifies what §5 must say about verbatim render (strict UTF-8, CRLF→LF
vs the LF-only rule, deterministic fence width, mandatory fencing as a
navigation-injection defence per method-spec §3 Step 1, max_rows semantics),
and flags that free text is untrusted-by-origin over a local transport —
which may pull guard Trigger A forward.
ingest-spec.md is untouched. Decision is the operator's.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HBJNsFsBRaAhqGKjjiGjoQ
The Claude SDK implementation (claude-code-llm-wiki) runs the same adoption task
in parallel; it owns guard wiring in its repo-local modules (ingest.py/verdicts.py/
okf.py), while shared/ and the ingest-spec gate contract are commons-owned. Record
the reciprocal boundary in the adoption plan so the division of labor survives
between sessions.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Score the guard brief's §7 checklist against the commons-specified architecture:
all implemented ingest paths (file/sql) are first-party, so the decisive
untrusted-ingest box is currently NO. Record the two designed untrusted boundaries
where the guard belongs when built — the http/MCP connector (sanitize + scan-before-
persist at ingest materialization) and a received-external OKF bundle (okf.import_bundle)
— and explicitly exclude the promotion gate as a first-party path the guard must not
wire. Plan only; the guard is not implemented.
Add .gitignore keeping STATE.md LOCAL-ONLY (commons is subtree-consumed and
open-publish-intended; STATE must never reach a consumer's shared/ or a public mirror).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Framework-neutral specification of the deterministic ingest step that
materializes real data sources as OKF bundles in front of the loop:
polymorphic manifest schema (file/CSV, SQL, HTTP as optional extension
point), credential-reference rule, verdict-layer reservation + layer
separation, ingest provenance frontmatter with explicit timestamp,
index-generation requirement, and the golden-extraction format.
README contents list updated.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AaQCFnfsh3tfq1VfzdJpoi
The shared core now lives in this repository (source of truth). Each
implementation repo consumes it as a git subtree at shared/ and syncs
with 'git subtree pull --squash'. Never 'git subtree push' from a
consumer: its re-split can leak the consumer's entire history into
this repo (observed and force-push-cleaned 2026-07-03).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AaQCFnfsh3tfq1VfzdJpoi
Author shared/method-spec.md: the 8-step loop (normative, RFC-2119), the
verdict JSON contract incl. the id-minting algorithm and the chosen conflict
semantics, the inbox/outbox folder contract, the fail-closed promotion-gate
semantics, the IR projection + golden suite as the only ground truth (incl.
the reproducible Monte Carlo procedure), and the budget/stop, provenance and
startup-contract requirements — every normative claim cross-checked against
the load-bearing tests/code. The sibling implementation builds from this spec
alone.
Load-bearing trio (tests/test_method_spec_loadbearing.py, persona-trio
style): required structure, a name-shaped framework-neutrality guard over the
spec + the persona skill tree, and a cross-check-completeness test driven
from the REAL artifacts and the REAL verdict serializer (red on code drift).
All three detach points proven RED (missing file / framework name / dropped
field). shared/README.md: the "(planned)" line replaced with the real entry.
Suite 152 -> 155 passed / 4 skipped; ruff check+format clean; mypy src clean.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AaQCFnfsh3tfq1VfzdJpoi
The expert reviewer was only a hardcoded verdict_input dict inside the offline
simulation. Build it as the real, shared artifact target picture §8 calls for:
shared/skills/expert-reviewer/ — a SKILL.md persona prompt (energy-advisor / M&V
role + the realization-gap methodology the validator cannot compute) plus a
canonical references/example-verdict.json. shared/ stays pure data; the MAF side
reads it via portfolio_optimiser.persona.load_persona_example (call-time,
fail-fast) and the Claude-SDK sibling reads the same JSON with its own loader.
This de-stubs the simulation: its persona judgement (decision + rationale + traced
marker) is now sourced from the artifact at call time, not an inline literal — so
the shared persona is genuinely consumed and cannot rot silently. decision is
binary (approved/rejected, the FeedbackContract the run path accepts);
approved_with_adjustment is rejected there and lives only in the bundle seed
frontmatter + the promotion gate, so the realization correction is carried in the
rationale prose.
Load-bearing trio (tests/test_persona_skill_loadbearing.py), each proven RED on its
own detach: structure + framework-neutrality, the example is valid pipeline input
(incl. FeedbackContract, on a throwaway copy), and the simulation's marker follows
the artifact file. Suite 149->152.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MHR8iKxJRxDiDfNw8HZmWE
Cross-coordination with the marketplace OKF convention
(ktg-plugin-marketplace/catalog/docs/okf-second-brain/spec.md v0.1). The
bundle already passed the shared acceptance gate; the one spec MUST-gap was the
root index okf_version marker (spec §3). Added it.
Verified: `node catalog/scripts/okf-check.mjs <bundle>` -> okf_version: 0.1,
"OK: valid OKF bundle", exit 0. Bundle-consuming tests green (14).
Scope note (honest): portfolio-optimiser uses OKF for framework per-project
runtime knowledge, NOT the user "second brain" the marketplace convention is
scoped to. Same FORM (now conformant + gate-clean), different SCOPE. Two
recommended `resource` warnings left deliberately (spec §4 sanctions omission;
no canonical URI to assert without fabricating). The index.md frontmatter is a
known deviation from spec §6 (reserved index = no frontmatter) kept for now
because okf.py navigation classifies the index by its type.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MHR8iKxJRxDiDfNw8HZmWE
Persistent dev-fixture for energieffektivisering (energiledelse/M&V), valgt for
sin lærings-overflate: gapet mellom modellert besparelse (validatoren regner) og
faktisk realisert besparelse i drift (eksperten kjenner) — det ExpeL skal lære.
Ett kontorbygg, ett LED-retrofit-tiltak. OKF-bundle (index/project/hypothesis/
methodology/reference/verdict) bærer kontekst-laget; verdict-led-fro.md koder
realiseringsgraden (RR ≈ 0,82, forankret i National Grid SBS 2010) som ExpeL-frø.
Energi mappet inn i den EKSISTERENDE kost-IR-en uendret (affected = byggets totale
energikostnad, claimed = modellert besparelse ~10 % < 30 %-cap), så validatoren
kjører som-den-er — src/ urørt. golden.json fryser de seeded percentilene; testen
beviser at fixturen er konsumerbar (validerer, ikke Rejection), ikke bare til stede.
Domenetall verifisert mot primærkilder (EVO/IPMVP, DOE/NREL UMP, CPUC, fire
evalueringsstudier); norsk energipris mot SSB Q1 2026. README + shared/README
oppdatert (eksempel finnes, ikke lenger "planned"). Suite 121/4, ruff+mypy rene.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MHR8iKxJRxDiDfNw8HZmWE
Operatørens private Forgejo retter seg i praksis mot det norske markedet;
konseptnotatet er reader-facing for norske forretningslesere, så norsk gjør det
mer tilgjengelig. README (dev-facing shared-core-kontrakt) holdes engelsk inntil
videre.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019any9zfGNNwWJPX5Zq2QRz
First artifact in the framework-neutral shared core (R1 effectuated). CONCEPT.md
is a plain-language business description of the method for a non-specialist
audience; README.md documents the shared-core contract (consumed unchanged by
both the MAF impl and the future Claude Agents SDK sibling; extract to commons
repo via git subtree split when sibling work starts). English per the repo's
documentation-language convention + open-publish intent.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019any9zfGNNwWJPX5Zq2QRz
