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ć 474630e2bb Adopt seven ideas from trailhq/Graft; schema 1.4 -> 1.5 
Graft keeps a derived, disposable code graph in sync with a content hash
rather than a calendar, and keeps a protected block on every regenerated
node. This KB is the opposite kind of store — durable, curated, built from
material that cannot be regenerated — but several of Graft's mechanisms
port cleanly, and two of them close real gaps here.

Schema 1.5 is additive: every 1.4 page remains valid.

1. `## Crux` — verbatim source excerpts alongside the synthesis. A summary
   can drift silently; a quote either still matches its source or it does
   not. Lets `ckb-retrieve` ground an answer without a round-trip to the
   archive, and makes drift mechanically detectable.
2. `## Notes` — human-authored and protected everywhere. Closes a real
   gap: `ckb-index-external` regenerates connector pages wholesale, so an
   annotation written there was previously destroyed on the next refresh.
3. `source_fingerprint`/`source_checked` — a digest of the material a page
   was built from. Freshness by date says a page has aged; a fingerprint
   says whether its evidence moved. Most valuable for connector-backed
   libs, where documents change with no notice.
4. `lint_report.py --quick` — a deterministic one-line session-start
   signal, wired into Rule E next to the existing `git status` check.
5. In-degree as a rank-fusion signal in `ckb-retrieve`, weighted below 1.0:
   centrality is a prior, not evidence.
6. Blast radius — a new `ckb-ingest` step walking the graph backwards from
   touched entities to find what the incoming material contradicts, before
   writing anything. Ingest was additive-first, which is how a wiki
   accumulates two pages that quietly disagree.
7. Edge vocabulary in `wiki/graph/index.md` rewritten as a question per
   verb, and completed: `part_of` was written by `ckb-code-map` but never
   declared. Added `produces`, `configures`, `validates`, `implements`.

Lint gains checks 12 (fingerprint drift), 13 (crux verbatimness) and 14
(the protected-Notes rule), verified against a synthetic fixture covering
stale digests, missing sources, fabricated quotes and paraphrased evidence.

Not adopted: the gitignored regenerable store, the MCP server and CLI
daemon, tree-sitter parsing, statusline hooks, telemetry.

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

3.8 KiB
Raw 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.