michal/ckb
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
ckb/.agents/modules/software
History
Exact
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
..
fragments Restore point before wiki reset 2026-09-20 17:56:41 +02:00
scaffold Restore point before wiki reset 2026-09-20 17:56:41 +02:00
skills Adopt seven ideas from trailhq/Graft; schema 1.4 -> 1.5 2026-09-21 22:44:26 +02:00
module.yaml Restore point before wiki reset 2026-09-20 17:56:41 +02:00
README.md Restore point before wiki reset 2026-09-20 17:56:41 +02:00

README.md

software module

Opt-in. Install with "install the software module"; remove with "uninstall the software module". Nothing in here is active until installed — the skills below live in this folder, not in .agents/skills/, precisely so their descriptions stay out of context for knowledge bases that don't document software.

What it assumes

You are building software, and this KB holds the knowledge about it. The code itself lives in src/<repo>/ as plain clones — gitignored, each with its own remote and its own history. One KB can hold several.

The code is not part of the KB's history and may be absent entirely from a fresh clone. That is deliberate, and it is why the module writes a type: repository entity page for every repo: remote URL, default branch, language, build command, path, owner. That page is the durable artifact; the clone is a convenience.

What it adds

Skill Does
ckb-code-map Reads a src/<repo> clone and writes it into wiki/entities/ as a repository page plus component pages, stamped with the commit it was generated from so staleness is detectable.
ckb-spec Owns KB-root specs, delegates per-repo specs to OpenSpec, and bridges both into wiki/ — archived changes become decision records, current specs become type: spec pages.

Plus: src/ and openspec/ scaffold, a routing block in AGENTS.md, .gitignore rules for src/*, and the repository/component/spec types.

Two spec levels

Specs live at both levels, and the split is the point:

  • openspec/ at the KB root — what and why, across repos. Cross-cutting contracts that no single repo owns. Served by ckb-spec directly, because a root openspec/ is not a normal OpenSpec install: there is no code beneath it.
  • src/<repo>/openspec/ — how this repo implements it. OpenSpec's native case: travels with the code, rides along in the repo's own PRs. Served by OpenSpec's own instructions; ckb-spec defers to them and says so plainly when the CLI isn't installed rather than improvising a replacement.

The levels are linked by implements: / implemented_by: frontmatter, which becomes graph edges. This exists so that two spec levels produce a lint signal when they disagree, instead of two silently divergent truths. A KB-root spec with no implementer, or a repo-level spec whose parent was archived, is a finding.

What it does not do

  • src/ is not a cascade layer. It is primary evidence, like raw/archive/. ckb-retrieve may open and cite it to verify a claim; it never answers "what is entity X", and ckb-ingest does not treat code as inbox material. Without this rule every ingest would turn your codebase into wiki pages.
  • It does not commit or push src/ repos. They are separate repos with separate remotes. ckb-sync-changes never git adds under src/.

Setting up OpenSpec

See OPENSPEC.md (Polski) for install steps, the daily propose → apply → archive loop, and the reason openspec init must never run at the KB root.

Design record

  • D-0001 — why modules are files in the repo.
  • D-0002 — why gitignored clones, both spec levels, hybrid vendoring.

Licensed under the Apache License, Version 2.0 — see LICENSE.