The plan header named 'v0.2 alpha' as reportage of the ecosystem, not as a
choice. llm-ingestion-guard has since cut v0.3.0, and consumers now disagree
on pinning: the guard recommends v0.3.0, llm-ingestion-okf deliberately holds
>=0.2,<0.3 because the new active:* findings could quarantine ordinary
documents under its Door B preset.
Commons has no wiring, no tests and no dependency declaration, so it pins
nothing. Naming no version is more accurate than trading one stale number
for another. §3.2:90-91 already prescribed allow_reserved=True for a whole
received bundle, which is what v0.3.0 made the default.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XYkLsRfSBBUjULS219Fy8X
Mark the D3 proposal doc RATIFIED: the canonical 7-token set + the two
normative rules (§3.1 partial⇒owner+next-step, §3.2 deferred≠blocked) were
written into ~/.claude/coord/register.md (2026-07-24) as a new
"Status-vokabular" section, with `active` and the open-ended `…` removed and
a contract-source pointer back here. §7 ratification path steps 1–2 marked
done; step 3 (catalog builder enforcement of the §3.1 gate) remains as a
separate catalog-owned track.
Ground truth re-verified before the register write: only `planned` (5×) and
`not-applicable` (1×) in use across ~/repos/*/STATE.md; `active` unused →
safe to fold into `in-progress`. Register edit is local-only (coord metadata
never reaches a public surface); this repo doc is the public contract source.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016oMpAhQcJZVGBW182stSPn
Author the framework-neutral contract that fills the vocabulary reference
D2 left open. Both the D2 register-form fix and the ratified
~/.claude/coord/register.md defer the status-token set to "the D3 track"
without defining it (register.md lines 42-44, 73).
Canonical set: planned / in-progress / partial / blocked / deferred / done /
not-applicable. 'active' folded into 'in-progress' (redundant synonym).
Two normative rules:
- partial is transitional — its output-A prose MUST carry owner + next-step;
never a terminal resting state. Output-A-local, so no conflict with D2's
output-B public-safety gate.
- deferred != blocked — voluntary postponement vs involuntary external wait;
the distinction encodes decision information.
Verified against ground truth: only planned (5x) + not-applicable (1x) in
use across ~/repos/*/STATE.md; 'active' unused (safe to drop); no existing
marker falls outside the set. Definition-before-use, not a migration.
Contract only; no global convention edited. Ratification into register.md
(replace the candidate list + '...' with the canonical set and the two
rules) is the next step, per §7.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016oMpAhQcJZVGBW182stSPn
Author the framework-neutral contract that unblocks D2 (coordination
register). Root cause: D2 conflated marker durability with content
publicness. Fix decouples them via a two-output model — LOCAL-ONLY rich
roll-up (grep STATE, unchanged) + optional public status-token-only index
from minimal committed carriers. Register-builder tolerates three per-repo
modes (absent / minimal-committed / private-sidechannel), decided at build;
never forces a commit. Commons picks 'absent' → the STATE interim line
becomes the permanent design for the public-mirror class.
Contract only; no global convention edited. Ratification (register section
placement + catalog builder wiring) is the next step.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016oMpAhQcJZVGBW182stSPn
New fixture class for the D4 step-0 split (commons-owned; delivered into
catalog's corpus/runner). A nav-golden case is bundle in / expected-read-
context out — the shape that expresses "two conformant implementations MUST
produce an identical read-context" (method-spec §3 Step 1).
- nav-golden-hierarchy/ (positive): depth-first first-seen order, both link
forms (/ = bundle root vs relative), one segment per level, resolved-path
dedup, cycle termination, recursive verdict exclusion, missing-index binds
root alone, flat render.
- nav-golden-escape/ (negative, gate must go red): .. escapes and a
/etc/passwd root-relative trap; conformant returns only valid.md.
Both expected-read-context.md verified byte-for-byte against a conformant
navigator implementing §3 Step 1; the negative case verified to diverge
under a naive navigator.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VUCuNNvnCkayuUDy2WFgeU
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
