Michał Kopeć
2c4d57acbc
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>
81 lines
5.2 KiB
Markdown
81 lines
5.2 KiB
Markdown
# 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.
|