ckb/workload/2026-07-13_summary.md

Session Summary — 2026-07-13

Actions Taken

• Researched Google Cloud's Open Knowledge Format (OKF v0.1, published June 2026): a minimal markdown+YAML-frontmatter spec for portable, agent/human-consumable knowledge bundles (type required field, resource field, recursive index.md/log.md, root-absolute links, formal conformance criteria, okf_version).
• Compared OKF against this repo's Cascade Knowledge Base approach and identified 8 areas where OKF's design is stronger (typing, link stability, recursive progressive disclosure, hierarchical logs, resource linking, conformance checking, schema versioning, generic interop tooling), while noting this repo's cascade layering, confidence/quality/retention decay, and session continuity go beyond what OKF specifies.
• Implemented propositions 1–7 (OKF-inspired improvements), applied identically to CLAUDE.md and AGENTS.md:
  1. Added required type frontmatter field + optional resource field to the Page Frontmatter Schema.
  2. Added resource field (see above, same schema change).
  3. Added guidance to Rule C to prefer project-root-absolute links (/wiki/entities/foo.md) for intra-wiki cross-references over relative paths.
  4. Added a "Recursive Index & Log Convention" subsection under Index-First Navigation; created wiki/entities/index.md and wiki/graph/index.md as the first real subdirectory indexes; updated the Ingestion Workflow (step 6) to create subdirectory indexes/logs going forward.
  5. Made wiki/log.md an explicit root-level rollup, with subdirectories permitted their own log.md once they have independent history — avoids one unbounded flat log file.
  6. Added a "Conformance check" as lint step 1 (verify parseable frontmatter + non-empty type on every non-reserved page) and an "Index/log consistency" check as lint step 8.
  7. Added a kb_schema_version field (bundle-level, on wiki/index.md only) with minor/major bump rules, documented in a new "Schema Versioning" subsection.
• Propagated the same documentation updates to wiki/index.md, wiki/overview.md, and README.md for consistency, and logged each wiki-level change in wiki/log.md.

Proposition 8 — planned and implemented

• User asked for a plan for proposition 8 (OKF export) and raised the question of whether it belongs as CLAUDE.md/AGENTS.md prose or as a command/skill. Entered plan mode, delegated design validation to a Plan agent, then wrote and got approval for a plan at /home/mkopec/.claude/plans/twinkly-wobbling-harbor.md.
• Decision: implemented as a project-scoped Claude Code Skill (.claude/skills/export-okf/SKILL.md), not new CLAUDE.md/AGENTS.md prose. Rationale: OKF export is a deterministic, occasionally-invoked transformation with a large fixed mapping ruleset — exactly what Skills' lazy-loading is for, versus permanently taxing every session's context via the always-loaded instruction files. Project-scoped (not ~/.claude/skills/) because the mapping is coupled to this repo's exact schema and travels with it in the same commits.
• Closed a discoverability gap for non-Claude-Code agents: added one generic sentence to CLAUDE.md/AGENTS.md §1 (outputs/ line) pointing at .claude/skills/ in general, without naming this specific skill, so the pointer never needs updating as skills are added/removed.
• Fixed a prerequisite gap discovered during planning: wiki/overview.md and wiki/error-book.md had zero YAML frontmatter and would have failed the conformance lint check added earlier this session. Retrofitted both with type/tldr/last_updated.
• Updated README.md with a "OKF Export" feature bullet and a note clarifying outputs/okf/ is a fully-regenerated build artifact that stays git-tracked (consistent with the existing outputs/ convention) but is never auto-committed by the skill itself.
• Wrote the full export-okf SKILL.md: 8-step procedure (read source → clear+rebuild outputs/okf/ → transform concept-doc frontmatter/links → regenerate index.md files → regenerate log.md files → handle non-reserved special pages → validate output conformance → report), plus edge cases (empty entities/graph dirs, missing type, future archived/, determinism on re-run).
• Have not yet run the skill end-to-end (wiki/entities and wiki/graph are still empty, so there's little to export yet) — first real exercise of the skill will happen on the next ingest that populates entities.

sync-changes skill — planned and implemented

• User asked for a second local skill: on "sync changes," reconcile this repo's own git history with its origin remote (pull remote commits, commit local changes, resolve conflicts with the user, push).
• Clarified scope up front via AskUserQuestion: "git" means this repo's own origin remote (https://codeberg.org/Valdec/llm-wiki-cascade.git), not libs/; and unlike export-okf, auto-push is explicitly approved here — the skill commits and pushes on its own once conflicts are resolved.
• Checked real repo state (read-only): origin is configured, but local main has zero commits — everything was untracked at the time of this session. This made the "local has no commits, remote may already have history" first-run case a live scenario, not a hypothetical, so it's handled as an explicit hard-stop path (ask the user to choose merge / remote-wins / stop) rather than an automatic guess.
• Entered plan mode again given the risk of automated git push; delegated design validation to a Plan agent (git command sequencing, conflict-presentation mechanics, first-run handling), then resolved two remaining open questions via AskUserQuestion: (1) never offer a force-push/discard-remote option even in the first-run menu — recommended and confirmed; (2) reword the existing bare "Sync" Ingestion trigger to "Sync the wiki" to reduce ambiguity with the new skill's "sync changes" trigger — recommended and confirmed.
• Implemented: .claude/skills/sync-changes/SKILL.md (5-step procedure: pre-flight safety checks incl. secrets scan → detect first-run/unrelated-histories case → steady-state commit-then-fetch-merge-then-push flow → present each conflict block via AskUserQuestion with keep-local/keep-remote/provide-merged-text options → structured report), plus edge cases (nothing-to-sync, push-rejected-twice, no-remote-configured).
• Updated CLAUDE.md/AGENTS.md §3 trigger wording ("Sync" → "Sync the wiki" + pointer to the new skill) and added a "Git Sync (on demand)" bullet to README.md, matching the export-okf precedent.
• Have not yet run the skill for real — it would actually commit and push this session's changes to the live Codeberg remote, which is a real external action, so it's left for the user to explicitly trigger with "sync changes" rather than auto-run as part of this session's "verification."

Decisions Made

• Keep CLAUDE.md and AGENTS.md byte-identical; every instruction edit is applied to both in lockstep.
• type is required per OKF precedent, but the rest of the existing schema (confidence/quality/retention/etc.) is retained as-is — OKF's minimalism is adopted piecemeal, not wholesale, since the decay/retention/cascade machinery has no OKF equivalent and is worth keeping.
• kb_schema_version lives only on wiki/index.md (bundle-level), not on every page, matching OKF's okf_version convention — and is dropped (not relocated) when exporting to OKF, since OKF's root index.md frontmatter is spec-limited to okf_version only.
• OKF export lives in .claude/skills/export-okf/, project-scoped rather than global, so it stays co-versioned with this repo's schema.
• Git-level sync lives in .claude/skills/sync-changes/, project-scoped for the same reason, and is explicitly authorized to auto-commit/auto-push (unlike export-okf) per direct user confirmation — but never force-pushes and always stops to ask on the first-run unrelated-histories case.