michal/ckb
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ckb/workload/2026-09-21_summary.md
Michał Kopeć 2c4d57acbc Add bilingual CHANGELOG with full schema and version history 
Two version numbers exist in this project and are easy to confuse:
kb_schema_version (the content contract, in wiki/index.md) and VERSION
(the tooling layer). Until now neither had a written history, and the
page schema was documented in four places at three levels of detail.

CHANGELOG.md / CHANGELOG.pl.md consolidate both: the current schema in
full (frontmatter for all pages and for decisions, the three reserved
body sections, the closed edge vocabulary with a "since" column, the
reserved scaffold), then the schema history 1.1-1.5 and the template
history 1.0.0-1.8.0.

The history is reconstructed from git rather than from memory, so it
records what actually happened rather than a tidied version of it:

- There was never a schema 1.0; versioning began at 1.1 on 2026-07-13.
- Template 1.4.0 and 1.5.0 were never published — VERSION jumped from
  1.3.0 to 1.6.0 on 2026-09-01.
- Connector-backed libs shipped as tooling in 1.1.0, but the schema only
  recorded them at 1.2 nine days later. The schema column shows what was
  in effect after each release, with a footnote on the lag.

Registered with ckb-init (copied verbatim into a new KB) and ckb-upgrade
(taken wholesale from upstream rather than merged, since upstream is
authoritative about its own history). Cross-linked from both READMEs and
both MANUALs.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-21 23:16:43 +02:00

5.2 KiB
Raw Permalink Blame History

2026-09-21 Session Summary

[2026-09-21] Analysis — Graft (trailhq/Graft) vs. this KB structure

  • Type: read-only analysis. No wiki/ writes, so no wiki/log.md entry.
  • Read: wiki/index.md, wiki/graph/index.md, wiki/entities/index.md, .agents/skills/ckb-retrieve/SKILL.md, .agents/skills/ckb-lint/SKILL.md, .agents/modules/software/skills/ckb-code-map/SKILL.md, repo tree.
  • External source: https://github.com/trailhq/Graft (README, fetched 2026-09-21).
  • Finding: Graft is a derived, disposable code-context graph (tree-sitter pass + optional LLM pass, gitignored, regenerated per developer); CKB is a durable, curated knowledge layer over non-regenerable material. Architectures are not competitors.
  • Seven portable ideas identified, ranked: (1) verbatim ## Crux/evidence excerpts in pages; (2) protected ## Notes block on agent-regenerated pages; (3) content-hash fingerprints on ## Sources for mechanical staleness; (4) cheap deterministic pre-pass + a ckb check freshness signal at session start; (5) graph in-degree as a rank-fusion signal in ckb-retrieve; (6) blast-radius pass during ingest; (7) complete + question-oriented edge vocabulary in wiki/graph/index.md.
  • Defect spotted: wiki/graph/index.md documents uses/depends_on/caused/ contradicts/supersedes but omits part_of, which ckb-code-map Step 6 writes.
  • Rejected as non-portable: gitignored/regenerable store, MCP server + CLI daemon, tree-sitter parsing, statusline/hooks, telemetry.
  • Status: analysis only, no changes proposed to disk yet. Awaiting user decision on which ideas to implement.
  • Git: branch main clean at session start; this summary is the only new file.

[2026-09-21] Implementation — Graft ideas 1-7 on branch graft-ideas

Branched from main at c998489. Schema bumped 1.4 -> 1.5 (additive; every 1.4 page stays valid). VERSION 1.7.0 -> 1.8.0.

# Idea Where it landed
1 ## Crux verbatim evidence AGENTS.md §2, ckb-ingest Step 5, ckb-decide, ckb-retrieve Step 6 shortcut, lint check 13
2 Protected ## Notes AGENTS.md §2, ckb-index-external regeneration rule, ckb-code-map, lint check 14
3 Source fingerprints source_fingerprint/source_checked frontmatter, ckb-ingest, ckb-index-external (etag/mtime/sha256), ckb-decide, lint check 12
4 Cheap pre-pass + ckb check lint_report.py --quick, wired into Rule E at session start; ckb-index-external skips unchanged docs by fingerprint
5 In-degree rank fusion ckb-retrieve Step 3 builds the list, Step 4 fuses at weight ~0.5; in_degree() in the lint script surfaces hubs
6 Blast radius new ckb-ingest Step 4 (reverse graph walk, confirms/extends/contradicts/untouched + owners), reported in Step 8
7 Edge vocabulary wiki/graph/index.md rewritten as a question-per-verb table; added part_of (the live inconsistency with ckb-code-map), produces, configures, validates, implements

Also updated for consistency: ckb-init/ckb-reset (graph vocabulary is now scaffold contract, copied verbatim), ckb-upgrade (new step b2, the 1.4->1.5 migration), ckb-export-okf (two new passthrough fields), README.md, README.pl.md, MANUAL.md, MANUAL.pl.md, wiki/overview.md.

Verification: new lint checks exercised against a synthetic fixture in the scratchpad — a good page (clean), a page with a stale digest + missing file + missing fingerprint + a fabricated quote, and a page with a paraphrased Crux. All five findings fired, the good page produced none. Repo's own wiki lints clean; both exporters run clean.

Not done: ideas beyond 1-7 (Graft's token-budgeted map view was idea 8 and out of scope). No wiki content was fingerprinted, because this wiki is an empty scaffold — the conventions take effect on the next ingest.

[2026-09-21] Docs — CHANGELOG.md / CHANGELOG.pl.md

Added a bilingual changelog + schema reference at the repo root, following the existing .md/.pl.md doc convention. Contents: the full current page schema (frontmatter for all pages and for decisions, the three reserved body sections, the closed edge vocabulary with a "since" column, the reserved scaffold), the KB schema version history 1.1-1.5, the template VERSION history 1.0.0-1.8.0, and a migration section.

History reconstructed from git, not from memory: VERSION and wiki/index.md were read back at each commit that changed them, and each release's diff was inspected to describe what it actually contained.

Two facts worth keeping:

  • There was never a schema 1.0. Versioning began at 1.1 (c56348b, 2026-07-13).
  • Template 1.4.0 and 1.5.0 were never published — VERSION jumped 1.3.0 -> 1.6.0 on 2026-09-01. Recorded as a note rather than papered over.
  • Connector-backed libs shipped in template 1.1.0 but the schema only recorded them at 1.2, nine days later; the table's schema column shows what was in effect after each release, with a footnote explaining the lag.

Registered the new files with ckb-init (copied verbatim into a new KB) and ckb-upgrade (taken wholesale from upstream, never merged — upstream is authoritative about its own history). Cross-linked from README.md, README.pl.md, MANUAL.md, MANUAL.pl.md.