diff --git a/.agents/skills/ckb-init/SKILL.md b/.agents/skills/ckb-init/SKILL.md index cc470ad..ff9c972 100644 --- a/.agents/skills/ckb-init/SKILL.md +++ b/.agents/skills/ckb-init/SKILL.md @@ -217,6 +217,10 @@ actual project entity): should point somewhere else - it's what lets the new KB's own `ckb-upgrade` find template updates later. - `MANUAL.md` and `MANUAL.pl.md` - the task-oriented user guide. +- `CHANGELOG.md` and `CHANGELOG.pl.md` - the full page schema reference plus + the schema and template version histories. Copy verbatim: the history + belongs to the template, not to the new KB, and a fresh KB starts on the + version that history ends at. - `VERSION` - copy the exact current value; the new KB starts life on the same template version it was just cloned from. diff --git a/.agents/skills/ckb-upgrade/SKILL.md b/.agents/skills/ckb-upgrade/SKILL.md index 309dce0..3f90ab0 100644 --- a/.agents/skills/ckb-upgrade/SKILL.md +++ b/.agents/skills/ckb-upgrade/SKILL.md @@ -16,8 +16,8 @@ neither: - **Template layer** — the schema/tooling that defines *how* the KB behaves: `AGENTS.md`/`CLAUDE.md`, `.agents/skills/*`, `LICENSE`, - `VERSION`, `README.md`/`README.pl.md`/`MANUAL.md`/`MANUAL.pl.md`, and the - base `.gitignore` rules. Compared via the root `VERSION` file. Freely + `VERSION`, `README.md`/`README.pl.md`/`MANUAL.md`/`MANUAL.pl.md`/ + `CHANGELOG.md`/`CHANGELOG.pl.md`, and the base `.gitignore` rules. Compared via the root `VERSION` file. Freely upgradable — these files hold no project-specific content. - **Content layer** — everything the KB has actually learned: `wiki/entities/`, `wiki/graph/edges.json`, `wiki/index.md`'s entity rows, @@ -149,8 +149,11 @@ The template layer is exactly these paths — never anything under `wiki/`, symlink) - `LICENSE` - `VERSION` -- `README.md`, `README.pl.md`, `MANUAL.md`, `MANUAL.pl.md` — whichever - exist upstream (an older local KB may not have some of these yet) +- `README.md`, `README.pl.md`, `MANUAL.md`, `MANUAL.pl.md`, + `CHANGELOG.md`, `CHANGELOG.pl.md` — whichever exist upstream (an older + local KB may not have some of these yet). Take the changelogs from + upstream wholesale rather than merging: they record the template's + history, which the upstream copy is authoritative about. - `.agents/skills//**` for every skill folder present in `tmp/ckb-upgrade-src/.agents/skills/` - `.agents/modules//**` for every optional module present upstream diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..aba5dd8 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,334 @@ +# Changelog & Schema Reference + +*Read this in: **English** | [Polski](CHANGELOG.pl.md)* + +This file tracks two things: the page schema exactly as it stands today, and +how this project arrived at its current version numbers. + +There are **two independent version numbers**, and they are not the same +thing: + +| Number | Lives in | Describes | Who bumps it | +|---|---|---|---| +| `kb_schema_version` | frontmatter of `wiki/index.md` | the **content contract** — what a page may contain and what those fields mean | `ckb-upgrade` (on a confirmed migration), `ckb-module` (additively, on install) | +| Template version | [`VERSION`](VERSION) | the **tooling layer** — `AGENTS.md`, the skills, the scripts, the docs | `ckb-upgrade`, when it pulls a newer template | + +They move independently on purpose. You can take a newer set of skills +without touching a single wiki page, and a wiki authored against an older +schema keeps working — that is what the schema version is for. + +**Versioning policy.** Bump the **minor** version for an additive change: a +new optional field, a new optional body section, a new optional scaffold +file. Bump the **major** version for a breaking one: changing or removing a +required field, or changing an existing reserved filename convention. There +has never been a major bump; every schema version to date has been additive, +so any page written since 2026-07-13 is still valid today. + +--- + +## Contents + +1. [Current page schema (1.5)](#current-page-schema-kb_schema_version-15) +2. [KB schema version history](#kb-schema-version-history) +3. [Template version history](#template-version-history) +4. [Migrating between versions](#migrating-between-versions) + +--- + +## Current page schema (`kb_schema_version: "1.5"`) + +### Frontmatter — every non-reserved page + +Every `.md` file under `wiki/` except the reserved ones (`index.md`, +`log.md`) carries YAML frontmatter. Only `type` is required; the rest are +optional, and preferred where meaningful. The parser is deliberately simple — +flat `key: value` pairs only, no nesting. + +| Field | Required | Meaning | +|---|---|---| +| `type` | **yes** | Open string: `person`, `project`, `concept`, `library`, `decision`, `playbook`, `repository`, `component`, … New values are always valid; readers tolerate unrecognised ones. | +| `resource` | no | Canonical URI of the authoritative external source this page describes, kept separate from the wiki's own commentary. | +| `tldr` | no | One-sentence summary optimised for LLM reading. This is what the index shows and what decides whether a page gets opened at all. | +| `confidence` | no | `0.0`–`1.0`. Source corroboration. Set on write, decays if nothing reinforces it, raised by a new source that agrees. | +| `quality` | no | `0.0`–`1.0`. Self-evaluation of the page's own structure and citations. Below `0.7` is flagged for review. | +| `supersedes` | no | Path to the older page this one replaces. | +| `superseded_by` | no | Path to the newer page that replaced this one. **Always set both sides.** | +| `last_updated` | no | `YYYY-MM-DD`. When the *page* last changed. | +| `freshness_window_days` | no | Days before lint flags the page as stale. Typical: 90 for a wiki page, 365 for a decision, 30 for a connector-indexed document. | +| `retention` | no | `high` / `medium` / `low`. A `low` page is archived (never deleted) after 2× its freshness window. | +| `source_fingerprint` | no | *(1.5)* Digest of the source this page was built from — `sha256:<8 hex>` for a local file, or `etag:` / `mtime:` for a connector item. | +| `source_checked` | no | *(1.5)* `YYYY-MM-DD` — when that digest was last verified. Distinct from `last_updated`: a re-check that finds nothing changed advances this and leaves `last_updated` alone. | + +`wiki/index.md` alone carries `kb_schema_version`. It is a bundle-level +declaration, not a per-page one — individual pages never carry it. + +### Frontmatter — decision pages + +Pages with `type: decision` live in `wiki/decisions/` as `NNNN-slug.md` and +add: + +| Field | Required | Meaning | +|---|---|---| +| `status` | **yes** | `proposed` / `accepted` / `rejected` / `superseded` / `reversed`. The vocabulary is defined in `wiki/decisions/index.md` and validated by lint. | +| `decided_on` | for `accepted`/`rejected`/`reversed` | `YYYY-MM-DD`, the date the call was made. | +| `decided_by` | when known | Comma-separated names. Where genuinely unknown, write `unknown` rather than omitting the field — "we don't know who decided this" is itself worth recording. | +| `affects` | no | Comma-separated wiki paths this decision constrains. | +| `review_on` | no | `YYYY-MM-DD` to revisit. Lint reports these once the date passes. | + +Decision records are **append-only**. A decision is never rewritten to match +a later change of mind: record a new one that supersedes it, and both stay on +the record. + +### Reserved body sections + +*(New in 1.5.)* Four `##` headings mean the same thing on every page in every +layer of the cascade. All are optional; where present, they mean exactly this +and nothing else. + +#### `## Sources` + +Where the page came from. One bullet per source, each carrying a fingerprint: + +```markdown +## Sources + +- `raw/archive/2026-09-21/kickoff-notes.md` — sha256:3f9a2c1e (checked 2026-09-21) +``` + +A freshness window is a guess that a source *might* have moved. A fingerprint +is a fact about whether it *did*. Lint recomputes local digests and flags what +actually changed, which is a different and more urgent finding than a page +that has merely aged. + +#### `## Crux` + +Verbatim excerpts from those sources — evidence, never paraphrase — attributed +to the source bullet they came from: + +```markdown +## Crux + +> FDEs need the VDI *and* a Jira account before day one; the VDI request +> alone takes ten working days. +— `raw/archive/2026-09-21/kickoff-notes.md`, under "Access" +``` + +Three to ten lines is the working range. A Crux approaching the length of the +summary above it has stopped being evidence and become a second copy of the +source. Two things follow from quoting rather than paraphrasing: a question +can often be answered from the page instead of the archive, and drift becomes +visible — a summary can wander from its source silently, a quote either still +matches or it does not. + +A page with no quotable source simply has no `## Crux`. An empty or +paraphrased one is worse than none, because it looks like evidence. + +#### `## Notes` + +Human-authored, and **protected**. No skill may rewrite, reflow, summarise or +drop this section; regeneration preserves it byte-for-byte. + +```markdown +## Notes + + +``` + +This matters most on pages the agent *regenerates* — connector indexes, code +maps — where everything else is discarded and rebuilt on the next run. It is +the only place an annotation survives. Decision pages deliberately have no +`## Notes`: nothing regenerates them, and an append-only record with a freely +editable annotation block invites exactly the retroactive revision the +append-only rule exists to prevent. + +### Edge vocabulary + +Relationships live in `wiki/graph/edges.json` (and each connector index's own +`graph/edges.json`). The vocabulary is closed, and each verb is defined by the +question it answers — if a proposed edge answers none of them, it belongs in +the page's prose instead. + +| Verb | Question it answers | Since | +|---|---|---| +| `part_of` | Where does this live? What is it a piece of? | 1.5 | +| `uses` | What does this reach for at runtime? | 1.1 | +| `depends_on` | What breaks if I change this? | 1.1 | +| `produces` | Where does this output come from? | 1.5 | +| `configures` | What changes this thing's behaviour? | 1.5 | +| `validates` | What checks, tests, or judges this? | 1.5 | +| `implements` | What contract must this honour? | 1.5 | +| `caused` | Why did this happen? | 1.1 | +| `contradicts` | What disagrees with this, unresolved? | 1.1 | +| `supersedes` | What replaced this, and what did it replace? | 1.1 | +| `decided_by` | Who made this call? | 1.4 | +| `affects` | What does this decision constrain? | 1.4 | +| `has_expertise_in` | Who can answer questions on this? | 1.3 | +| `owns` | Who is responsible for this? | 1.3 | +| `mentioned_in` | Which source document discusses this? | 1.2 (lib indexes only) | + +Record one direction per relationship — `part_of`, `supersedes`, +`depends_on` and `uses` are canonical, and the inverse is not stored as a +second edge. Record edges only from demonstrated evidence; an absent edge +beats a fabricated one, and a padded graph degrades retrieval rather than +improving it (in-degree is used as a ranking signal). + +### Reserved scaffold + +| Path | Since | Purpose | +|---|---|---| +| `wiki/index.md` | 1.1 | Routing table; the only page carrying `kb_schema_version` | +| `wiki/overview.md` | 1.1 | High-level map of the KB | +| `wiki/log.md` | 1.1 | Reverse-chronological change log for `wiki/` | +| `wiki/error-book.md` | 1.1 | Systemic issues with root cause and fix | +| `wiki/entities/` | 1.1 | Typed entity pages | +| `wiki/graph/` | 1.1 | `edges.json` plus the vocabulary in `index.md` | +| `wiki/query-gaps.md` | 1.2 | Questions the wiki could not answer, driving demand-driven ingest | +| `wiki/projects/` | 1.2 | Optional local query scopes | +| `wiki/decisions/` | 1.4 | Numbered, append-only decision records, with their own `log.md` | + +Every subdirectory that groups pages carries its own `index.md`, so +navigation stays lazy. + +--- + +## KB schema version history + +### 1.5 — 2026-09-21 · evidence, fingerprints, and a completed edge vocabulary + +Adopted from an analysis of [trailhq/Graft](https://github.com/trailhq/Graft), +a context layer for coding agents that keeps a derived code graph in sync via +content hashes rather than dates, and protects a user-authored block on every +regenerated node. Graft's store is disposable and regenerable; this one is not, +so most of its design does not transfer — but several mechanisms do, and two +of them closed real gaps here. + +**Added:** + +- **`## Crux`** — verbatim source excerpts alongside the synthesis. Lets + `ckb-retrieve` ground an answer without a round-trip to the archive (when + the fingerprint still matches), and makes drift detectable. +- **`## Notes`** — human-authored and protected everywhere. This closed a real + gap: `ckb-index-external` regenerates connector pages wholesale, so an + annotation written there was previously destroyed on the next refresh. +- **`## Sources`** — formalised as a reserved section with one fingerprinted + bullet per source. Previously an informal convention that `ckb-retrieve` + relied on but no skill actually specified. +- **`source_fingerprint` / `source_checked`** frontmatter. +- **Edge verbs** `part_of`, `produces`, `configures`, `validates`, + `implements`. `part_of` fixed a live inconsistency: `ckb-code-map` had been + writing it since template 1.7.0 while the schema never declared it. + +**Changed:** + +- `wiki/graph/index.md` rewritten as a question-per-verb table with + conventions on edge direction and evidence. +- `ckb-ingest` gained a blast-radius step: before writing, walk the graph + backwards from touched entities to find what the incoming material + confirms, extends or contradicts, and name the owners of affected pages. + Ingest had been additive-first, which is how a wiki accumulates two pages + that quietly disagree. +- `ckb-retrieve` fuses graph in-degree as one ranked list among several, + weighted below 1.0 — centrality is a prior, not evidence. +- Rule E (session start) now runs `lint_report.py --quick` alongside + `git status`: a deterministic one-line knowledge-rot signal costing no + model tokens. +- Lint gained checks 12 (fingerprint drift), 13 (crux verbatimness) and 14 + (the protected-`## Notes` rule). + +**Compatibility:** fully additive. A 1.4 page with none of the new sections or +fields is valid 1.5. A migration will never manufacture a `## Crux` — +inventing quotes is precisely the failure that section exists to prevent. + +### 1.4 — 2026-09-01 · decision records + +**Added:** `type: decision` pages under `wiki/decisions/` as `NNNN-slug.md`, +with `status`, `decided_on`, `decided_by`, `affects`, `review_on`; the +`decided_by` and `affects` edge verbs; `wiki/decisions/index.md` and its own +`log.md`; the append-only rule. Answers "why is it like this", "who decided", +and "what changed that decision" as direct lookups instead of a full-text +guess. Owned by the `ckb-decide` skill. + +### 1.3 — 2026-08-06 · people-to-topic edges + +**Added:** the `has_expertise_in` and `owns` edge verbs, making "who knows +about X" and "who owns X" a graph lookup rather than a full-text search. +Recorded only from demonstrated evidence — attending a meeting is not +expertise, and a job title is not ownership. + +### 1.2 — 2026-07-29 · query scopes, gaps, and connector-backed libs + +**Added:** `wiki/projects/` (optional local query scopes grouping related +pages, sources and graph areas); `wiki/query-gaps.md` (failed searches +recorded as future ingest targets); `raw/archive//` as the +agent-maintained filing destination; connector-backed `libs//` with a +user-authored `source.yaml`, an agent-owned generated index, and the +`mentioned_in` edge verb used inside those indexes. + +### 1.1 — 2026-07-13 · initial schema + +The first versioned contract, shipped with the initial commit. Established +the frontmatter field set (`type`, `resource`, `tldr`, `confidence`, +`quality`, `supersedes`/`superseded_by`, `last_updated`, +`freshness_window_days`, `retention`), the core edge verbs (`uses`, +`depends_on`, `caused`, `contradicts`, `supersedes`), the `wiki/` scaffold, +the cascade priority rule, and the recursive index-and-log convention. + +There was never a 1.0: versioning began with the first published schema. + +--- + +## Template version history + +The tooling layer — `AGENTS.md`/`CLAUDE.md`, the skills, the scripts, the +docs. Independent of the content schema above. + +| Version | Date | What landed | Schema | +|---|---|---|---| +| **1.8.0** | 2026-09-21 | Seven ideas adopted from Graft: crux/notes/fingerprints, `--quick` lint mode, in-degree ranking, ingest blast radius, completed edge vocabulary | → 1.5 | +| 1.7.0 | 2026-09-20 | Opt-in modules (`.agents/modules/`, `ckb-module`, `ckb.yaml`); the `software` module with `ckb-code-map` and `ckb-spec`; `ckb-reset`; OpenSpec docs | 1.4 | +| 1.6.1 | 2026-09-01 | Fixed false-positive broken-edge findings in the lint graph check | 1.4 | +| 1.6.0 | 2026-09-01 | `ckb-decide`; detection half of lint moved into `lint_report.py`; OKF export moved into `export_okf.py` | → 1.4 | +| 1.3.0 | 2026-08-06 | Rank fusion, dedupe and rerank in `ckb-retrieve`; expertise and ownership lookups | → 1.3 | +| 1.2.1 | 2026-07-29 | `AGENTS.md` compressed — workflows moved out into skills, leaving a small always-loaded rule set | 1.2 | +| 1.2.0 | 2026-07-29 | Project scopes, query gaps, source-verified retrieval | → 1.2 | +| 1.1.0 | 2026-07-20 | Connector-backed `libs/` with self-contained external source indexing (`ckb-index-external`) | 1.1 \* | +| 1.0.0 | 2026-07-17 | First tagged template: full skill set, `LICENSE`, `MANUAL`, bilingual docs | 1.1 | + +\* Connector-backed libs shipped as tooling in 1.1.0, but the schema only +recorded them — the `source.yaml` contract, the generated index shape, the +`mentioned_in` verb — at 1.2, nine days later. The two numbers catching up +with each other like this is normal, and is why the schema column shows what +was in effect *after* each template release rather than what the release was +about. + +Versions 1.4.0 and 1.5.0 were never published — the template jumped from +1.3.0 to 1.6.0 on 2026-09-01. + +--- + +## Migrating between versions + +Say **"upgrade the wiki"** or **"check for a newer template version"**. The +`ckb-upgrade` skill checks the canonical template repo, updates the tooling +layer in place, and — separately, and only after you explicitly confirm — +migrates existing `wiki/` content up to the current schema while preserving +every fact already collected. + +The two halves are deliberately separate. Taking newer skills never rewrites +your pages, and a content migration is never silent: it reports what it +intends to change, batches anything it had to infer (such as a missing `type`) +for your confirmation, and logs every touched page in `wiki/log.md` marked as +a schema-migration backfill rather than new knowledge. + +Because every schema version so far has been additive, an older wiki keeps +working unmigrated. Migration is worth doing to make the newer checks +meaningful — backfilled fingerprints are what give lint anything to verify — +not because anything is broken without it. + +--- + +## Version & License + +Current template version: [VERSION](VERSION). Current schema version: the +`kb_schema_version` field in `wiki/index.md`. Licensed under the +[Apache License 2.0](LICENSE). diff --git a/CHANGELOG.pl.md b/CHANGELOG.pl.md new file mode 100644 index 0000000..29e8c86 --- /dev/null +++ b/CHANGELOG.pl.md @@ -0,0 +1,341 @@ +# Historia zmian i referencja schematu + +*Przeczytaj to w: [English](CHANGELOG.md) | **Polski*** + +Ten plik śledzi dwie rzeczy: schemat strony dokładnie w takiej postaci, w +jakiej obowiązuje dziś, oraz to, jak projekt doszedł do swoich obecnych +numerów wersji. + +Istnieją **dwa niezależne numery wersji** i nie są tym samym: + +| Numer | Mieszka w | Opisuje | Kto go podnosi | +|---|---|---|---| +| `kb_schema_version` | frontmatter `wiki/index.md` | **kontrakt treści** — co strona może zawierać i co te pola znaczą | `ckb-upgrade` (przy potwierdzonej migracji), `ckb-module` (addytywnie, przy instalacji) | +| Wersja szablonu | [`VERSION`](VERSION) | **warstwa narzędziowa** — `AGENTS.md`, skille, skrypty, dokumentacja | `ckb-upgrade`, gdy pobiera nowszy szablon | + +Poruszają się niezależnie i jest to celowe. Możesz wziąć nowszy zestaw skilli +bez dotykania choćby jednej strony wiki, a wiki napisane pod starszy schemat +nadal działa — po to właśnie jest wersja schematu. + +**Polityka wersjonowania.** Podnoś wersję **pomniejszą** przy zmianie +addytywnej: nowe pole opcjonalne, nowa opcjonalna sekcja treści, nowy +opcjonalny plik szkieletu. Podnoś wersję **główną** przy zmianie łamiącej +kompatybilność: zmiana lub usunięcie pola wymaganego albo zmiana istniejącej +zastrzeżonej konwencji nazw plików. Nigdy nie było podniesienia wersji +głównej — każda dotychczasowa wersja schematu była addytywna, więc dowolna +strona napisana od 2026-07-13 jest dziś nadal poprawna. + +--- + +## Spis treści + +1. [Aktualny schemat strony (1.5)](#aktualny-schemat-strony-kb_schema_version-15) +2. [Historia wersji schematu KB](#historia-wersji-schematu-kb) +3. [Historia wersji szablonu](#historia-wersji-szablonu) +4. [Migracja między wersjami](#migracja-między-wersjami) + +--- + +## Aktualny schemat strony (`kb_schema_version: "1.5"`) + +### Frontmatter — każda strona niezastrzeżona + +Każdy plik `.md` w `wiki/` poza zastrzeżonymi (`index.md`, `log.md`) niesie +frontmatter YAML. Wymagane jest wyłącznie `type`; reszta jest opcjonalna i +preferowana tam, gdzie ma sens. Parser jest celowo prosty — wyłącznie płaskie +pary `klucz: wartość`, bez zagnieżdżeń. + +| Pole | Wymagane | Znaczenie | +|---|---|---| +| `type` | **tak** | Otwarty ciąg: `person`, `project`, `concept`, `library`, `decision`, `playbook`, `repository`, `component`, … Nowe wartości są zawsze poprawne; czytelnicy tolerują nierozpoznane. | +| `resource` | nie | Kanoniczny URI autorytatywnego źródła zewnętrznego, które opisuje ta strona, trzymany oddzielnie od własnego komentarza wiki. | +| `tldr` | nie | Jednozdaniowe streszczenie zoptymalizowane pod odczyt przez LLM. To ono trafia do indeksu i decyduje, czy strona w ogóle zostanie otwarta. | +| `confidence` | nie | `0.0`–`1.0`. Potwierdzenie przez źródła. Ustawiane przy zapisie, zanika, jeśli nic go nie wzmacnia, rośnie przy nowym zgodnym źródle. | +| `quality` | nie | `0.0`–`1.0`. Samoocena struktury i cytowań samej strony. Poniżej `0.7` oflagowane do przeglądu. | +| `supersedes` | nie | Ścieżka do starszej strony, którą ta zastępuje. | +| `superseded_by` | nie | Ścieżka do nowszej strony, która zastąpiła tę. **Zawsze ustawiaj obie strony.** | +| `last_updated` | nie | `YYYY-MM-DD`. Kiedy zmieniła się *strona*. | +| `freshness_window_days` | nie | Liczba dni, po której lint oznacza stronę jako nieaktualną. Typowo: 90 dla strony wiki, 365 dla decyzji, 30 dla dokumentu z indeksu konektora. | +| `retention` | nie | `high` / `medium` / `low`. Strona `low` jest archiwizowana (nigdy usuwana) po 2× swoim oknie świeżości. | +| `source_fingerprint` | nie | *(1.5)* Skrót źródła, z którego zbudowano stronę — `sha256:<8 hex>` dla pliku lokalnego albo `etag:` / `mtime:` dla elementu z konektora. | +| `source_checked` | nie | *(1.5)* `YYYY-MM-DD` — kiedy ten skrót był ostatnio zweryfikowany. To co innego niż `last_updated`: ponowne sprawdzenie, które nie wykryło zmiany, przesuwa to pole i zostawia `last_updated` w spokoju. | + +Wyłącznie `wiki/index.md` niesie `kb_schema_version`. To deklaracja na +poziomie całego zbioru, nie pojedynczej strony — same strony nigdy jej nie +niosą. + +### Frontmatter — strony decyzji + +Strony z `type: decision` mieszkają w `wiki/decisions/` jako `NNNN-slug.md` i +dodają: + +| Pole | Wymagane | Znaczenie | +|---|---|---| +| `status` | **tak** | `proposed` / `accepted` / `rejected` / `superseded` / `reversed`. Słownik zdefiniowany w `wiki/decisions/index.md` i walidowany przez lint. | +| `decided_on` | dla `accepted`/`rejected`/`reversed` | `YYYY-MM-DD`, data podjęcia decyzji. | +| `decided_by` | gdy wiadomo | Nazwiska po przecinku. Gdy naprawdę nie wiadomo, wpisz `unknown` zamiast pomijać pole — „nie wiemy, kto to zdecydował" samo w sobie warto zapisać. | +| `affects` | nie | Ścieżki wiki po przecinku, które ta decyzja ogranicza. | +| `review_on` | nie | `YYYY-MM-DD` do ponownego rozważenia. Lint zgłasza je po przekroczeniu daty. | + +Rekordy decyzji są **tylko do dopisywania**. Decyzji nigdy nie przepisuje się +pod późniejszą zmianę zdania: zapisz nową, która ją zastępuje, a obie zostają +na wokandzie. + +### Zastrzeżone sekcje treści + +*(Nowość w 1.5.)* Cztery nagłówki `##` znaczą to samo na każdej stronie w +każdej warstwie kaskady. Wszystkie są opcjonalne; tam, gdzie występują, +znaczą dokładnie to i nic innego. + +#### `## Sources` + +Skąd wzięła się strona. Po jednym punkcie na źródło, każdy ze skrótem: + +```markdown +## Sources + +- `raw/archive/2026-09-21/kickoff-notes.md` — sha256:3f9a2c1e (checked 2026-09-21) +``` + +Okno świeżości to przypuszczenie, że źródło *mogło* się zmienić. Skrót to +fakt, czy *się zmieniło*. Lint przelicza skróty lokalne i oznacza to, co +faktycznie się zmieniło — a to inne i pilniejsze znalezisko niż strona, która +jedynie się zestarzała. + +#### `## Crux` + +Dosłowne fragmenty tych źródeł — dowód, nigdy parafraza — przypisane do +punktu źródła, z którego pochodzą: + +```markdown +## Crux + +> FDEs need the VDI *and* a Jira account before day one; the VDI request +> alone takes ten working days. +— `raw/archive/2026-09-21/kickoff-notes.md`, sekcja „Access" +``` + +Roboczy zakres to od trzech do dziesięciu linijek. Crux zbliżający się +długością do streszczenia nad nim przestał być dowodem i stał się drugą kopią +źródła. Z cytowania zamiast parafrazowania wynikają dwie rzeczy: na pytanie +często da się odpowiedzieć ze strony zamiast z archiwum, a odpływ od źródła +staje się widoczny — streszczenie może po cichu oddalić się od źródła, cytat +albo wciąż się zgadza, albo nie. + +Strona bez cytowalnego źródła po prostu nie ma `## Crux`. Pusty albo +sparafrazowany jest gorszy niż żaden, bo wygląda jak dowód. + +#### `## Notes` + +Pisane przez człowieka i **chronione**. Żaden skill nie może tej sekcji +nadpisać, przeformatować, streścić ani usunąć; regeneracja zachowuje ją co do +bajtu. + +```markdown +## Notes + + +``` + +Ma to największe znaczenie na stronach, które agent *regeneruje* — indeksy +konektorów, mapy kodu — gdzie cała reszta jest odrzucana i budowana od nowa +przy kolejnym przebiegu. To jedyne miejsce, w którym adnotacja przetrwa. +Strony decyzji celowo nie mają `## Notes`: nic ich nie regeneruje, a rekord +tylko-do-dopisywania ze swobodnie edytowalnym blokiem adnotacji zaprasza +dokładnie do tej wstecznej korekty, której zasada append-only ma zapobiegać. + +### Słownik krawędzi + +Relacje mieszkają w `wiki/graph/edges.json` (oraz we własnym +`graph/edges.json` każdego indeksu konektora). Słownik jest zamknięty, a każdy +czasownik zdefiniowany przez pytanie, na jakie odpowiada — jeśli proponowana +krawędź nie odpowiada na żadne z nich, jej miejsce jest w tekście strony. + +| Czasownik | Pytanie, na jakie odpowiada | Od | +|---|---|---| +| `part_of` | Gdzie to mieszka? Czego jest częścią? | 1.5 | +| `uses` | Po co to sięga w czasie działania? | 1.1 | +| `depends_on` | Co się zepsuje, jeśli to zmienię? | 1.1 | +| `produces` | Skąd bierze się ten wynik? | 1.5 | +| `configures` | Co zmienia zachowanie tej rzeczy? | 1.5 | +| `validates` | Co to sprawdza, testuje albo ocenia? | 1.5 | +| `implements` | Jakiego kontraktu to musi dotrzymać? | 1.5 | +| `caused` | Dlaczego to się stało? | 1.1 | +| `contradicts` | Co jest z tym sprzeczne i nierozstrzygnięte? | 1.1 | +| `supersedes` | Co to zastąpiło i co ono zastąpiło? | 1.1 | +| `decided_by` | Kto podjął tę decyzję? | 1.4 | +| `affects` | Co ta decyzja ogranicza? | 1.4 | +| `has_expertise_in` | Kto potrafi odpowiedzieć na pytania o to? | 1.3 | +| `owns` | Kto za to odpowiada? | 1.3 | +| `mentioned_in` | Który dokument źródłowy o tym mówi? | 1.2 (tylko indeksy libs) | + +Zapisuj po jednym kierunku na relację — `part_of`, `supersedes`, +`depends_on` i `uses` są kanoniczne, a odwrotność nie jest przechowywana jako +druga krawędź. Zapisuj krawędzie wyłącznie na podstawie wykazanych dowodów; +brak krawędzi jest lepszy niż krawędź zmyślona, a napompowany graf pogarsza +wyszukiwanie zamiast je poprawiać (stopień wejściowy jest sygnałem +rankingowym). + +### Zastrzeżony szkielet + +| Ścieżka | Od | Do czego służy | +|---|---|---| +| `wiki/index.md` | 1.1 | Tabela routingu; jedyna strona niosąca `kb_schema_version` | +| `wiki/overview.md` | 1.1 | Mapa KB z lotu ptaka | +| `wiki/log.md` | 1.1 | Dziennik zmian `wiki/` w odwrotnej chronologii | +| `wiki/error-book.md` | 1.1 | Problemy systemowe wraz z przyczyną i naprawą | +| `wiki/entities/` | 1.1 | Typowane strony encji | +| `wiki/graph/` | 1.1 | `edges.json` plus słownik w `index.md` | +| `wiki/query-gaps.md` | 1.2 | Pytania, na które wiki nie umiało odpowiedzieć, napędzające ingest sterowany popytem | +| `wiki/projects/` | 1.2 | Opcjonalne lokalne zakresy zapytań | +| `wiki/decisions/` | 1.4 | Numerowane rekordy decyzji tylko-do-dopisywania, z własnym `log.md` | + +Każdy podkatalog grupujący strony niesie własny `index.md`, dzięki czemu +nawigacja pozostaje leniwa. + +--- + +## Historia wersji schematu KB + +### 1.5 — 2026-09-21 · dowody, skróty źródeł i dokończony słownik krawędzi + +Zaadaptowane z analizy [trailhq/Graft](https://github.com/trailhq/Graft), +warstwy kontekstu dla agentów kodujących, która utrzymuje wyprowadzony graf +kodu w zgodzie ze źródłem przez skróty treści, a nie daty, i chroni blok +pisany przez użytkownika na każdym regenerowanym węźle. Magazyn Graftu jest +jednorazowy i odtwarzalny; ten nie jest, więc większość jego projektu się nie +przenosi — ale kilka mechanizmów tak, a dwa z nich zamknęły tu realne luki. + +**Dodano:** + +- **`## Crux`** — dosłowne fragmenty źródeł obok syntezy. Pozwala + `ckb-retrieve` ugruntować odpowiedź bez powrotu do archiwum (gdy skrót się + wciąż zgadza) i czyni odpływ od źródła wykrywalnym. +- **`## Notes`** — pisane przez człowieka i chronione wszędzie. To zamknęło + realną lukę: `ckb-index-external` regeneruje strony konektora w całości, + więc napisana tam adnotacja ginęła dotąd przy kolejnym odświeżeniu. +- **`## Sources`** — sformalizowane jako sekcja zastrzeżona z jednym + punktem ze skrótem na źródło. Wcześniej nieformalna konwencja, na której + `ckb-retrieve` polegało, ale której żaden skill faktycznie nie określał. +- **`source_fingerprint` / `source_checked`** we frontmatterze. +- **Czasowniki krawędzi** `part_of`, `produces`, `configures`, `validates`, + `implements`. `part_of` naprawiło żywą niespójność: `ckb-code-map` + zapisywał go od szablonu 1.7.0, a schemat nigdy go nie deklarował. + +**Zmieniono:** + +- `wiki/graph/index.md` przepisany jako tabela pytanie-na-czasownik wraz z + konwencjami dotyczącymi kierunku krawędzi i dowodów. +- `ckb-ingest` dostał krok promienia rażenia: przed zapisem przejdź graf + wstecz od dotkniętych encji, żeby ustalić, co nadchodzący materiał + potwierdza, rozszerza albo z czym jest sprzeczny, i wskaż właścicieli + dotkniętych stron. Ingest był dotąd przede wszystkim addytywny, a tak + właśnie wiki gromadzi dwie strony, które po cichu się ze sobą nie zgadzają. +- `ckb-retrieve` wtapia stopień wejściowy grafu jako jedną z rankowanych list, + z wagą poniżej 1.0 — centralność jest przesłanką, nie dowodem. +- Reguła E (start sesji) uruchamia teraz `lint_report.py --quick` obok + `git status`: deterministyczny jednoliniowy sygnał gnicia wiedzy, niekosztujący + żadnych tokenów modelu. +- Lint zyskał kontrole 12 (odpływ skrótu źródła), 13 (dosłowność sekcji Crux) + i 14 (zasada chronionego `## Notes`). + +**Kompatybilność:** w pełni addytywna. Strona 1.4 bez żadnej z nowych sekcji +i pól jest poprawną stroną 1.5. Migracja nigdy nie wytworzy `## Crux` — +zmyślanie cytatów to dokładnie ta porażka, której ta sekcja ma zapobiegać. + +### 1.4 — 2026-09-01 · rekordy decyzji + +**Dodano:** strony `type: decision` w `wiki/decisions/` jako `NNNN-slug.md`, +z `status`, `decided_on`, `decided_by`, `affects`, `review_on`; czasowniki +krawędzi `decided_by` i `affects`; `wiki/decisions/index.md` wraz z własnym +`log.md`; zasadę append-only. Odpowiada na „dlaczego jest tak, jak jest", +„kto zdecydował" i „co zmieniło tę decyzję" bezpośrednim wyszukaniem zamiast +zgadywania pełnotekstowego. Właścicielem jest skill `ckb-decide`. + +### 1.3 — 2026-08-06 · krawędzie osoba–temat + +**Dodano:** czasowniki krawędzi `has_expertise_in` i `owns`, dzięki którym +„kto wie o X" i „kto jest właścicielem X" to wyszukanie w grafie, a nie +przeszukiwanie pełnotekstowe. Zapisywane wyłącznie na podstawie wykazanych +dowodów — obecność na spotkaniu to nie ekspertyza, a stanowisko to nie +własność. + +### 1.2 — 2026-07-29 · zakresy zapytań, luki i libs oparte na konektorach + +**Dodano:** `wiki/projects/` (opcjonalne lokalne zakresy zapytań grupujące +powiązane strony, źródła i obszary grafu); `wiki/query-gaps.md` (nieudane +wyszukiwania zapisane jako przyszłe cele ingestu); +`raw/archive//` jako utrzymywane przez agenta miejsce +archiwizacji; `libs//` oparte na konektorach, z pisanym przez +użytkownika `source.yaml`, należącym do agenta generowanym indeksem oraz +czasownikiem krawędzi `mentioned_in` używanym wewnątrz tych indeksów. + +### 1.1 — 2026-07-13 · pierwszy schemat + +Pierwszy wersjonowany kontrakt, wydany wraz z pierwszym commitem. Ustanowił +zestaw pól frontmatteru (`type`, `resource`, `tldr`, `confidence`, `quality`, +`supersedes`/`superseded_by`, `last_updated`, `freshness_window_days`, +`retention`), podstawowe czasowniki krawędzi (`uses`, `depends_on`, `caused`, +`contradicts`, `supersedes`), szkielet `wiki/`, zasadę priorytetu kaskady i +rekurencyjną konwencję indeksu i dziennika. + +Wersji 1.0 nigdy nie było: wersjonowanie zaczęło się od pierwszego +opublikowanego schematu. + +--- + +## Historia wersji szablonu + +Warstwa narzędziowa — `AGENTS.md`/`CLAUDE.md`, skille, skrypty, dokumentacja. +Niezależna od schematu treści powyżej. + +| Wersja | Data | Co weszło | Schemat | +|---|---|---|---| +| **1.8.0** | 2026-09-21 | Siedem pomysłów zaadaptowanych z Graftu: crux/notes/skróty źródeł, tryb `--quick` lintu, ranking po stopniu wejściowym, promień rażenia w ingeście, dokończony słownik krawędzi | → 1.5 | +| 1.7.0 | 2026-09-20 | Opcjonalne moduły (`.agents/modules/`, `ckb-module`, `ckb.yaml`); moduł `software` z `ckb-code-map` i `ckb-spec`; `ckb-reset`; dokumentacja OpenSpec | 1.4 | +| 1.6.1 | 2026-09-01 | Naprawa fałszywie dodatnich znalezisk uszkodzonych krawędzi w kontroli grafu | 1.4 | +| 1.6.0 | 2026-09-01 | `ckb-decide`; wykrywająca połowa lintu przeniesiona do `lint_report.py`; eksport OKF przeniesiony do `export_okf.py` | → 1.4 | +| 1.3.0 | 2026-08-06 | Fuzja rankingów, deduplikacja i ponowny ranking w `ckb-retrieve`; wyszukiwanie ekspertyzy i własności | → 1.3 | +| 1.2.1 | 2026-07-29 | `AGENTS.md` skompresowany — przepływy przeniesione do skilli, zostawiając mały, zawsze ładowany zestaw reguł | 1.2 | +| 1.2.0 | 2026-07-29 | Zakresy projektów, luki zapytań, wyszukiwanie weryfikowane względem źródła | → 1.2 | +| 1.1.0 | 2026-07-20 | `libs/` oparte na konektorach z samodzielnym indeksowaniem źródeł zewnętrznych (`ckb-index-external`) | 1.1 \* | +| 1.0.0 | 2026-07-17 | Pierwszy otagowany szablon: pełny zestaw skilli, `LICENSE`, `MANUAL`, dokumentacja dwujęzyczna | 1.1 | + +\* `libs/` oparte na konektorach weszły jako narzędzia w 1.1.0, ale schemat +zapisał je — kontrakt `source.yaml`, kształt generowanego indeksu, czasownik +`mentioned_in` — dopiero w 1.2, dziewięć dni później. Takie doganianie się +tych dwóch numerów jest normalne i dlatego kolumna schematu pokazuje, co +obowiązywało *po* danym wydaniu szablonu, a nie czego to wydanie dotyczyło. + +Wersje 1.4.0 i 1.5.0 nigdy nie zostały opublikowane — szablon przeskoczył z +1.3.0 na 1.6.0 dnia 2026-09-01. + +--- + +## Migracja między wersjami + +Powiedz **„upgrade the wiki"** albo **„check for a newer template version"**. +Skill `ckb-upgrade` sprawdza kanoniczne repozytorium szablonu, aktualizuje +warstwę narzędziową w miejscu i — osobno, i wyłącznie po twoim wyraźnym +potwierdzeniu — migruje istniejącą treść `wiki/` do bieżącego schematu, +zachowując każdy już zebrany fakt. + +Te dwie połowy są celowo rozdzielone. Wzięcie nowszych skilli nigdy nie +przepisuje twoich stron, a migracja treści nigdy nie jest cicha: zgłasza, co +zamierza zmienić, zbiera wszystko, co musiała wywnioskować (na przykład +brakujące `type`), do twojego potwierdzenia i loguje każdą dotkniętą stronę w +`wiki/log.md` z adnotacją, że to uzupełnienie migracyjne schematu, a nie nowa +wiedza. + +Ponieważ każda dotychczasowa wersja schematu była addytywna, starsze wiki +działa bez migracji. Migrację warto zrobić po to, żeby nowsze kontrole miały +sens — uzupełnione skróty źródeł dają lintowi cokolwiek do weryfikacji — a +nie dlatego, że bez niej coś jest zepsute. + +--- + +## Wersja i licencja + +Aktualna wersja szablonu: [VERSION](VERSION). Aktualna wersja schematu: pole +`kb_schema_version` w `wiki/index.md`. Licencja: +[Apache License 2.0](LICENSE). diff --git a/MANUAL.md b/MANUAL.md index 82064f0..1734897 100644 --- a/MANUAL.md +++ b/MANUAL.md @@ -6,8 +6,9 @@ This is the human-facing manual for working with a Cascade Knowledge Base (this repo). It's written for the *person* using the wiki, not the agent — for the agent's own operating rules, see [AGENTS.md](AGENTS.md) / [CLAUDE.md](CLAUDE.md). For a feature-by-feature technical overview, see -[README.md](README.md). This document is task-oriented: "I want to do X — -what do I say, and what happens?" +[README.md](README.md). For the page schema in full and the version +histories behind it, see [CHANGELOG.md](CHANGELOG.md). This document is +task-oriented: "I want to do X — what do I say, and what happens?" Everywhere below, "say" means typing it to whatever AI coding agent you're using against this repo (Claude Code, or another agent that reads diff --git a/MANUAL.pl.md b/MANUAL.pl.md index e093dd3..b59401e 100644 --- a/MANUAL.pl.md +++ b/MANUAL.pl.md @@ -6,7 +6,9 @@ To jest podręcznik dla *człowieka* korzystającego z Cascade Knowledge Base (tego repozytorium) — nie dla agenta. Zasady działania samego agenta znajdziesz w [AGENTS.md](AGENTS.md) / [CLAUDE.md](CLAUDE.md). Techniczny, funkcja-po-funkcji przegląd znajdziesz w [README.md](README.md) (lub -[README.pl.md](README.pl.md)). Ten dokument jest zorientowany na zadania: +[README.pl.md](README.pl.md)). Pełny schemat strony wraz z historią obu +numerów wersji znajdziesz w [CHANGELOG.pl.md](CHANGELOG.pl.md). Ten dokument +jest zorientowany na zadania: „chcę zrobić X — co mam powiedzieć i co się wtedy stanie?” Wszędzie poniżej „powiedz” oznacza napisanie tego do dowolnego agenta AI, diff --git a/README.md b/README.md index 276e2ab..8330c22 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,9 @@ If this KB documents software you're building, the optional `software` module adds `src/` repositories and spec-driven development — see [OPENSPEC.md](OPENSPEC.md) ([Polski](OPENSPEC.pl.md)). +For the page schema in full, and for how both version numbers got where they +are, see [CHANGELOG.md](CHANGELOG.md) ([Polski](CHANGELOG.pl.md)). + --- ## Directory Structure diff --git a/README.pl.md b/README.pl.md index e1a7cbc..c211de6 100644 --- a/README.pl.md +++ b/README.pl.md @@ -19,6 +19,9 @@ Jeśli ta baza dokumentuje tworzone przez Ciebie oprogramowanie, opcjonalny modu `software` dodaje repozytoria w `src/` i pracę sterowaną specyfikacją — zobacz [OPENSPEC.pl.md](OPENSPEC.pl.md) ([English](OPENSPEC.md)). +Pełny schemat strony oraz historię obu numerów wersji znajdziesz w +[CHANGELOG.pl.md](CHANGELOG.pl.md) ([English](CHANGELOG.md)). + --- ## Struktura katalogów diff --git a/workload/2026-09-21_summary.md b/workload/2026-09-21_summary.md index 7ebcabd..4c15c63 100644 --- a/workload/2026-09-21_summary.md +++ b/workload/2026-09-21_summary.md @@ -53,3 +53,29 @@ 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.