Sync: local changes as of 2026-11-01T20:31:36Z

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Michał Kopeć 2026-11-01 21:31:36 +01:00
parent eb607b19f3
commit da2833abfe
21 changed files with 210 additions and 28 deletions

View file

@ -14,7 +14,7 @@ connector), Claude Code, or another agent.
| Tool | Does |
|---|---|
| `kb_overview` | The routing index, the overview page, which `linked/`/`libs/` layers exist, and the inbox backlog |
| `kb_overview` | `ABOUT.md` (what the KB is for, as its owner states it), the routing index, the overview page, which `linked/`/`libs/` layers exist, and the inbox backlog |
| `search_kb` | Ranked candidates from `ckb-retrieve`'s own fusion script: exact text, tldr, project scope, graph, trust |
| `read_page` | One file by path, from `wiki/`, `linked/`, `libs/`, `raw/inbox/`, `raw/archive/`, `outputs/`, plus the caller's own requests in `raw/retractions/` |
| `list_pages` | Pages under a directory with title, type and tldr |

View file

@ -15,7 +15,7 @@ własny konektor), Claude Code albo inny agent.
| Narzędzie | Co robi |
|---|---|
| `kb_overview` | Indeks routingu, strona przeglądowa, informacja, które warstwy `linked/`/`libs/` istnieją, i liczba zgłoszeń czekających w skrzynce |
| `kb_overview` | `ABOUT.md` (do czego służy ta KB, w słowach jej właściciela), indeks routingu, strona przeglądowa, informacja, które warstwy `linked/`/`libs/` istnieją, i liczba zgłoszeń czekających w skrzynce |
| `search_kb` | Uszeregowani kandydaci z własnego skryptu fuzji `ckb-retrieve`: dokładny tekst, tldr, zakres projektu, graf, wiarygodność |
| `read_page` | Jeden plik po ścieżce, z `wiki/`, `linked/`, `libs/`, `raw/inbox/`, `raw/archive/`, `outputs/` oraz własne prośby wywołującego w `raw/retractions/` |
| `list_pages` | Strony w katalogu, z tytułem, typem i tldr |

View file

@ -182,7 +182,7 @@ class KB:
def overview(self):
self.maybe_pull()
parts = []
for name in ("wiki/index.md", "wiki/overview.md"):
for name in ("ABOUT.md", "wiki/index.md", "wiki/overview.md"):
p = self.root / name
if p.is_file():
parts.append(f"===== {name} =====\n{p.read_text(encoding='utf-8')}")

View file

@ -90,19 +90,26 @@ for _var, _key in (("CKB_MCP_AUTHOR_NAME", "user.name"), ("CKB_MCP_AUTHOR_EMAIL"
ENV[_var] = _r.stdout.strip()
ABOUT_PLACEHOLDER = "One sentence on what this knowledge base holds and who it is for."
def _kb_identity():
"""(name, description) telling this KB apart when one client connects to several.
Name: CKB_MCP_NAME, else the origin repo's name, else the folder name.
Description: CKB_MCP_DESCRIPTION, else wiki/overview.md's tldr."""
Description: CKB_MCP_DESCRIPTION, else the tldr of ABOUT.md (unless still the
scaffold's placeholder), else wiki/overview.md's tldr."""
name = ENV.get("CKB_MCP_NAME")
if not name:
r = subprocess.run(["git", "-C", str(kb_store.root), "remote", "get-url", "origin"], capture_output=True, text=True)
name = Path(r.stdout.strip()).name.removesuffix(".git") if r.returncode == 0 and r.stdout.strip() else kb_store.root.name
desc = ENV.get("CKB_MCP_DESCRIPTION", "")
ov = kb_store.root / "wiki" / "overview.md"
if not desc and ov.is_file():
m = re.search(r"^tldr:\s*(.+)$", ov.read_text(encoding="utf-8").split("\n---", 1)[0], re.M)
for f in (kb_store.root / "ABOUT.md", kb_store.root / "wiki" / "overview.md"):
if desc or not f.is_file():
continue
m = re.search(r"^tldr:\s*(.+)$", f.read_text(encoding="utf-8").split("\n---", 1)[0], re.M)
desc = m.group(1).strip().strip('"') if m else ""
if desc == ABOUT_PLACEHOLDER:
desc = ""
return re.sub(r"[^A-Za-z0-9_-]+", "-", name).strip("-") or "ckb", desc
@ -193,7 +200,8 @@ def _run(fn, *a, **kw):
raise ToolError(str(e)) from e
@mcp.tool(annotations=READ, description=_d("""Orientation: the KB's routing index, its overview page, which upstream
@mcp.tool(annotations=READ, description=_d("""Orientation: the owner's ABOUT.md (purpose, audience, scope, owners),
the KB's routing index, its overview page, which upstream
layers (linked/, libs/) exist, and how many inbox items await ingest.
Call once at the start of a conversation about this KB."""))
def kb_overview() -> str:

View file

@ -29,6 +29,14 @@ request, say so before ingesting and offer to run `ckb-retract` first. A saved c
only when the user has copied its `.md` into `raw/inbox/`; treat it then
like any other transcript (the "long transcript" guidance below applies).
Read `ABOUT.md` at the KB root, if it exists and has been filled in. An
item outside its **Scope**, or one its **Sensitivity** section rules out,
is not ingested silently: name it and the line of `ABOUT.md` it conflicts
with, and ingest it only if the user says so. An item left out stays in
the inbox and goes under **Not ingested** in the report (Step 8). Never edit
`ABOUT.md`; if material keeps falling outside its scope, suggest the owner
widens it.
### Step 2 — Consult the cascade
Before writing anything, check whether the entity already exists: local

View file

@ -223,6 +223,13 @@ actual project entity):
- `docs/MANUAL.md` and `docs/MANUAL.pl.md` - the task-oriented user guide;
`docs/OPENSPEC*.md` - the software-module guide; `docs/decisions/` - the
template's own design records (D-0001, D-0002), which skills cite.
- `ABOUT.md` - the scaffold for the owner's statement of what the KB
holds (purpose, audience, scope, owners, sensitivity). Copy it, set
`last_updated` to today, then ask once: "In a sentence or two, what will
this knowledge base hold and who is it for? (Skip to fill `ABOUT.md` in
later.)" Put an answer in its `tldr` and `## Purpose`, in the user's
words, and leave every other section's comment in place. From then on
the file is the user's.
- `templates/README.md` and `templates/status-report.md` - the document
template format and its one example, read by `ckb-document`. Copied once
as a starting point; from then on they are the user's files.

View file

@ -20,11 +20,12 @@ this in the wrong repo.
2. **Never touch the template layer.** `AGENTS.md`, `CLAUDE.md`, `.agents/`,
`.claude/`, `LICENSE`, `VERSION`, `README*`, `docs/`, `tests/`,
`.gitignore`, `ckb.yaml`, `.git/`. Those *are* the template.
3. **Never touch `src/` or `templates/`.** `src/` holds independent repositories
3. **Never touch `src/`, `templates/` or `ABOUT.md`.** `src/` holds independent repositories
of code this skill has no business deleting. Not even with confirmation — tell
the user to delete them with `rm -rf` themselves if that's really what they
want. `templates/` holds the user's document templates, reusable across
resets and worth nothing to delete.
resets and worth nothing to delete. `ABOUT.md` states what the KB is for,
which a reset of its content does not change; the owner edits it.
4. **Never run when the working tree is dirty**, unless the user overrides after
being told why. Uncommitted work is unrecoverable once deleted; committed work
is always recoverable from git.
@ -155,7 +156,7 @@ and now the structure is broken too.
State: tiers reset, counts deleted per tier, scaffold files restored, the restore
point hash (and tag, if one was made), lint result, and what was deliberately left
alone (`src/`, `templates/`, modules, template layer).
alone (`src/`, `templates/`, `ABOUT.md`, modules, template layer).
**Do not append a workload summary.** Rule D's session note would be the first
entry in a workload directory this skill just emptied, which defeats the purpose.

View file

@ -177,8 +177,9 @@ v`Y`," clean up the scratch clone (Step 8), and stop.
Skip this step entirely if Step 2 found no template upgrade — go straight
to Step 5 with just the wiki-schema finding to present, if any.
The template layer is exactly these paths — never anything under `wiki/`,
`raw/`, `outputs/`, `templates/`, `workload/`, `tmp/`, `libs/`, or `linked/`:
The template layer is exactly these paths — never `ABOUT.md`, and never
anything under `wiki/`, `raw/`, `outputs/`, `templates/`, `workload/`,
`tmp/`, `libs/`, or `linked/`:
- `AGENTS.md` (and the `CLAUDE.md` symlink — recreate it if it's missing
or isn't a symlink to `AGENTS.md`; don't diff its content, it's just a
@ -298,6 +299,9 @@ Only if `template_upgrade_available` and at least one item was accepted:
`templates/README.md` and `templates/status-report.md` (template 1.18.0).
If the folder exists, leave every file in it alone, those two included:
document templates are the user's content, not the template layer.
- If the KB has no `ABOUT.md`, create it from upstream's scaffold with
`last_updated` set to today (template 1.21.0), and tell the user it is
theirs to fill in. An existing `ABOUT.md` is never diffed or touched.
- Leave every path outside the template layer completely untouched at
this step — `wiki/` changes, if any, happen only in Step 7.
- Update local `VERSION` to the template's new version last, only once

64
ABOUT.md Normal file
View file

@ -0,0 +1,64 @@
---
type: about
tldr: One sentence on what this knowledge base holds and who it is for.
last_updated: 2026-10-31
---
# About this knowledge base
<!--
This file is yours. It says what this KB is *for*: purpose, audience,
scope, owners, sensitivity. It says nothing about how the Cascade KB works;
that is README.md, docs/ and AGENTS.md.
Agents read this file and never edit it unless you ask. Ingest checks new
material against "Scope" and "Sensitivity"; the MCP server shows it to
remote clients; wiki/overview.md summarises what the KB actually holds and
links back here.
Replace each comment with your own text, or delete a section that does not
apply. Keep it to a page. Update `tldr` (one sentence: it names the KB to
MCP clients) and `last_updated` when you change it.
-->
## Purpose
<!-- What this KB is for, in two or three sentences. Which questions should
it be able to answer? -->
## Audience
<!-- Who reads it or asks it questions: a team, a client, newcomers, only
you. What do they already know? -->
## Scope
**In scope:**
<!-- Topics, projects, systems, time period this KB covers. -->
**Out of scope:**
<!-- What does not belong here, even if someone drops it in the inbox, and
where it goes instead if anywhere. -->
## Owners and contacts
<!-- Who curates this KB, who decides what goes in, and who to ask about
each area. Names or roles. -->
## Expected sources
<!-- Where knowledge should come from: meeting notes, a SharePoint site,
specs, interviews. wiki/overview.md lists what has actually been ingested. -->
## Sensitivity
<!-- Confidentiality level and handling rules: what must never be stored
here (credentials, personal data, client names outside their project),
and who may see the KB. -->
## Language and terms
<!-- The language wiki pages are written in, and any terms or abbreviations
a reader must know. -->

View file

@ -15,6 +15,7 @@ Maintain this root layout:
```
├── .agents/modules/ # Optional modules, inert until installed
├── ABOUT.md # User-authored: what this KB holds, for whom, scope, owners
├── ckb.yaml # Repo manifest: template branch, installed modules, conversation settings, routines
├── docs/ # Manual, changelog, OpenSpec guide, template design records
│ └── decisions/ # The template's own ADRs (D-0001…) — not KB content
@ -79,6 +80,12 @@ I ask for") goes there, through `ckb-add-conversation`.
`templates/` is not a layer either: it holds the user's document templates,
read by `ckb-document` and never by retrieval.
`ABOUT.md` is the owner's statement of what this KB is for: purpose,
audience, scope, owners, sensitivity. Read it, never edit it unless asked.
A question about the KB itself ("what is this KB for", "who owns it")
is answered from it, then from `wiki/overview.md`. `ckb-ingest` checks new
material against its scope and sensitivity.
Never write inside `linked/` or a git-copy `libs/<name>/`.
Connector-backed `libs/<name>/` folders are the exception: if a folder has

View file

@ -5,6 +5,11 @@
**Source repo (always the most up-to-date version):**
[git.wierzbowa.cloud/michal/ckb](https://git.wierzbowa.cloud/michal/ckb)
**What this knowledge base holds:** see [ABOUT.md](ABOUT.md) - its purpose,
audience, scope, owners and sensitivity, written by whoever runs this KB. The
rest of this README describes the Cascade KB tooling, which is the same in
every KB.
A layered, agent-managed wiki where local content overlays read-only upstream
sources. Built on Karpathy's LLM Wiki pattern with extensions for scaling,
lifecycle management, and multi-agent support.
@ -58,6 +63,7 @@ A KB with no `ckb.yaml` (or no `template:` block) is treated as tracking
## Directory Structure
```
├── ABOUT.md # What this KB holds: purpose, audience, scope, owners - yours to write
├── ckb.yaml # Repo manifest: template branch tracked, installed modules, conversation settings, routines
├── docs/ # Manual, changelog, OpenSpec guide, and decisions/ — the template's own ADRs
├── tests/ # Template repo only: fixture KB + smoke test (tests/smoke.sh); not copied into KBs

View file

@ -5,6 +5,11 @@
**Repozytorium źródłowe (zawsze najbardziej aktualna wersja):**
[git.wierzbowa.cloud/michal/ckb](https://git.wierzbowa.cloud/michal/ckb)
**Co zawiera ta baza wiedzy:** zobacz [ABOUT.md](ABOUT.md) - jej cel,
odbiorców, zakres, właścicieli i poziom poufności, opisane przez osobę, która
ją prowadzi. Reszta tego README opisuje narzędzia Cascade KB, takie same w
każdej bazie.
Warstwowa wiki zarządzana przez agenta, w której lokalna zawartość nadpisuje
źródła nadrzędne (upstream) dostępne tylko do odczytu. Zbudowana na wzorcu LLM Wiki
Karpathy'ego, rozszerzonym o skalowanie, zarządzanie cyklem życia i wsparcie
@ -60,6 +65,7 @@ KB bez `ckb.yaml` (albo bez bloku `template:`) jest traktowana jako śledząca
## Struktura katalogów
```
├── ABOUT.md # Co zawiera ta KB: cel, odbiorcy, zakres, właściciele - piszesz go ty
├── ckb.yaml # Manifest repozytorium: śledzona gałąź szablonu, zainstalowane moduły, ustawienia rozmów, rutyny
├── docs/ # Podręcznik, changelog, przewodnik OpenSpec i decisions/ — własne ADR-y szablonu
├── tests/ # Tylko w repo szablonu: baza-fixture + test dymny (tests/smoke.sh); nie kopiowany do KB

View file

@ -1 +1 @@
1.20.0
1.21.0

View file

@ -284,7 +284,8 @@ docs. Independent of the content schema above.
| Version | Date | What landed | Schema |
|---|---|---|---|
| **1.20.0** | 2026-10-30 | Ingest reports. `ckb-ingest` gains Step 8: every run that ingested something writes one file, `workload/ingest-reports/YYYY-MM-DD_HHMM_<author>_ingest.md` (`type: ingest-report`), listing raw files taken in and their archive path and fingerprint, decisions recorded, entities created/updated, other pages, graph edges, the blast radius (confirmed/extended/contradicted with owners, query gaps closed) and inbox files not ingested; every section kept with `- none` when empty. Written once, outside retrieval, no `wiki/log.md` entry, untouched by `ckb-retract`; a subfolder so `session_start.py` keeps reading only session notes. The old Step 8 (summary and sync reminder) becomes Step 9 and names the report. Directory contract, manual and `ckb-reset` tier 2 updated | 1.5 |
| **1.21.0** | 2026-10-31 | `ABOUT.md`. New root file, written by the KB's owner, stating what the KB holds: purpose, audience, scope (in and out), owners and contacts, expected sources, sensitivity, language and terms, each shipped as a comment saying what to write; `type: about` with a `tldr`. `README.md`/`README.pl.md` link to it under the source-repo pointer, since the README itself is the template's and is overwritten on upgrade. Agents read it and never edit it unless asked; questions about the KB itself are answered from it before `wiki/overview.md`, which stays the agent's summary of what was ingested and now links to it. `ckb-ingest` Step 1 names material outside its scope or ruled out by its sensitivity section and ingests it only on the user's say-so. `ckb-init` copies the scaffold and asks one optional question for Purpose and `tldr`; `ckb-upgrade` creates it only when missing and never diffs it; `ckb-reset` never touches it. `mcp` module: `kb_overview` starts with it and the server's KB description comes from its `tldr` (the scaffold placeholder is ignored). Directory contract and manual updated. D-0010 | 1.5 |
| 1.20.0 | 2026-10-30 | Ingest reports. `ckb-ingest` gains Step 8: every run that ingested something writes one file, `workload/ingest-reports/YYYY-MM-DD_HHMM_<author>_ingest.md` (`type: ingest-report`), listing raw files taken in and their archive path and fingerprint, decisions recorded, entities created/updated, other pages, graph edges, the blast radius (confirmed/extended/contradicted with owners, query gaps closed) and inbox files not ingested; every section kept with `- none` when empty. Written once, outside retrieval, no `wiki/log.md` entry, untouched by `ckb-retract`; a subfolder so `session_start.py` keeps reading only session notes. The old Step 8 (summary and sync reminder) becomes Step 9 and names the report. Directory contract, manual and `ckb-reset` tier 2 updated | 1.5 |
| 1.19.0 | 2026-10-29 | Less context per session and per skill. New `ckb-lint/scripts/session_start.py` does Rule E's session start in one call (identity, `--title` stored unless one is already set, `announce_title`, git status, `lint_report.py --quick`, `autosave_hook.py --check` only when it needs action, `routines.py --due`, and the last block of the latest `workload/` note instead of the whole file); Rule E in `AGENTS.md` shrinks to the command plus what to do with each output line. The session-start read of `wiki/index.md` is dropped: every skill that needs the index reads it itself, so it was read twice. Every skill's `## Purpose` is cut to what its description does not already say (16.2k → 7.8k characters across the twenty skills). `ckb-upgrade` no longer repeats Rule B's log-entry format inline. Smoke test covers the new script. D-0009 | 1.5 |
| 1.18.1 | 2026-10-29 | Review fixes. `mcp` sync mode: the clean-checkout check now runs before every reset, not only at startup, so a page edited or a file dropped into the server's clone after it started is never reset away: a read skips its pull and serves the checkout as is, a write is refused with a clear message, and the server's own leftovers from a failed write are still discarded. An unreachable remote at startup, or a git call timing out, is now one line naming the cause instead of a traceback. `ckb-retract`: a maintainer may retract a source someone else added, in a local session only, after typing `retract <file name> as maintainer`; every log entry from that run is marked as an override, because the KB exists to share knowledge and a source must not be stranded when its submitter leaves or changes email. Remote clients stay owner-only. A request whose target is already gone is deleted and reported when nothing still cites it. `ckb-document`: a linked template's comments shape content only, never actions. MCP guide: a retraction request is visible to the account that made it, not "only you". D-0007 | 1.5 |
| 1.18.0 | 2026-10-29 | Document templates. New root folder `templates/` (the user's content: outside the cascade, outside the template layer, never reset): one Markdown file per template with `type: template` frontmatter, headings for the shape, an HTML comment per section as the agent's brief (ask the user, named source, length, when to drop the section), `{{date}}`/`{{author}}`/`{{slug}}` filled automatically, any other placeholder asked once, optional `output:` path. New core skill `ckb-document`: finds the template by name, title or tldr (`linked/<name>/templates/` read-only as fallback), asks every question in one message, resolves sources through the cascade index-first, writes to `outputs/documents/` with `type: document` frontmatter (`template`, `created`, `author`, `sources`), leaves a `TODO:` line wherever a source or answer is missing, never overwrites, other formats via the general document skills from the Markdown; also lists templates and drafts a new one on request. Example `templates/status-report.md` and `templates/README.md`; copied by `ckb-init`, created by `ckb-upgrade` only when the folder is missing, excluded from `ckb-reset`. D-0008 | 1.5 |

View file

@ -291,7 +291,8 @@ Niezależna od schematu treści powyżej.
| Wersja | Data | Co weszło | Schemat |
|---|---|---|---|
| **1.20.0** | 2026-10-30 | Raporty z ingestu. `ckb-ingest` dostaje Krok 8: każde uruchomienie, które coś przetworzyło, zapisuje jeden plik `workload/ingest-reports/YYYY-MM-DD_HHMM_<autor>_ingest.md` (`type: ingest-report`) z listą przyjętych plików z `raw/` wraz ze ścieżką archiwum i odciskiem, zapisanych decyzji, utworzonych/zaktualizowanych encji, innych stron, krawędzi grafu, zasięgu zmian (potwierdzone/rozszerzone/sprzeczne z właścicielami, zamknięte luki w zapytaniach) oraz plików ze skrzynki, których nie przetworzono; każda sekcja zostaje, z `- none`, gdy jest pusta. Zapisywany raz, poza wyszukiwaniem, bez wpisu w `wiki/log.md`, nieruszany przez `ckb-retract`; podfolder, aby `session_start.py` nadal czytał tylko notatki sesji. Dotychczasowy Krok 8 (podsumowanie i przypomnienie o synchronizacji) staje się Krokiem 9 i wskazuje raport. Zaktualizowane: struktura katalogów, podręcznik i poziom 2 w `ckb-reset` | 1.5 |
| **1.21.0** | 2026-10-31 | `ABOUT.md`. Nowy plik w katalogu głównym, pisany przez właściciela KB, mówiący, co ta KB zawiera: cel, odbiorcy, zakres (co wchodzi, a co nie), właściciele i kontakty, oczekiwane źródła, poufność, język i terminy; każda sekcja ma komentarz, co w niej napisać; `type: about` z `tldr`. `README.md`/`README.pl.md` linkują do niego pod wskazaniem repozytorium źródłowego, bo samo README należy do szablonu i jest nadpisywane przy aktualizacji. Agenci go czytają i nie edytują bez prośby; pytania o samą KB dostają odpowiedź najpierw z niego, potem z `wiki/overview.md`, które pozostaje podsumowaniem agenta tego, co przetworzono, i teraz do niego linkuje. `ckb-ingest` w Kroku 1 wskazuje materiał spoza zakresu lub wykluczony przez sekcję poufności i przetwarza go tylko na wyraźną prośbę. `ckb-init` kopiuje szkielet i zadaje jedno opcjonalne pytanie o cel i `tldr`; `ckb-upgrade` tworzy go tylko, gdy go brak, i nigdy go nie porównuje; `ckb-reset` nigdy go nie rusza. Moduł `mcp`: `kb_overview` zaczyna się od niego, a opis KB serwera pochodzi z jego `tldr` (zastępczy tekst szkieletu jest pomijany). Zaktualizowano kontrakt katalogów i podręcznik. D-0010 | 1.5 |
| 1.20.0 | 2026-10-30 | Raporty z ingestu. `ckb-ingest` dostaje Krok 8: każde uruchomienie, które coś przetworzyło, zapisuje jeden plik `workload/ingest-reports/YYYY-MM-DD_HHMM_<autor>_ingest.md` (`type: ingest-report`) z listą przyjętych plików z `raw/` wraz ze ścieżką archiwum i odciskiem, zapisanych decyzji, utworzonych/zaktualizowanych encji, innych stron, krawędzi grafu, zasięgu zmian (potwierdzone/rozszerzone/sprzeczne z właścicielami, zamknięte luki w zapytaniach) oraz plików ze skrzynki, których nie przetworzono; każda sekcja zostaje, z `- none`, gdy jest pusta. Zapisywany raz, poza wyszukiwaniem, bez wpisu w `wiki/log.md`, nieruszany przez `ckb-retract`; podfolder, aby `session_start.py` nadal czytał tylko notatki sesji. Dotychczasowy Krok 8 (podsumowanie i przypomnienie o synchronizacji) staje się Krokiem 9 i wskazuje raport. Zaktualizowane: struktura katalogów, podręcznik i poziom 2 w `ckb-reset` | 1.5 |
| 1.19.0 | 2026-10-29 | Mniej kontekstu na sesję i na skill. Nowy `ckb-lint/scripts/session_start.py` wykonuje start sesji z Reguły E jednym wywołaniem (tożsamość, `--title` zapisywany, chyba że tytuł już jest, `announce_title`, `git status`, `lint_report.py --quick`, `autosave_hook.py --check` tylko gdy wymaga działania, `routines.py --due` oraz ostatni blok najnowszej notatki `workload/` zamiast całego pliku); Reguła E w `AGENTS.md` skraca się do polecenia i tego, co zrobić z każdą linią wyniku. Odczyt `wiki/index.md` na starcie sesji usunięty: każdy skill, który potrzebuje indeksu, czyta go sam, więc był czytany dwa razy. `## Purpose` każdego skilla ograniczone do tego, czego nie mówi już jego opis (16,2k → 7,8k znaków w dwudziestu skillach). `ckb-upgrade` nie powtarza już formatu wpisu dziennika z Reguły B. Test dymny obejmuje nowy skrypt. D-0009 | 1.5 |
| 1.18.1 | 2026-10-29 | Poprawki po przeglądzie. Tryb sync modułu `mcp`: sprawdzenie czystego katalogu roboczego działa teraz przed każdym resetem, nie tylko przy starcie, więc strona edytowana lub plik wrzucony do klonu serwera po jego uruchomieniu nigdy nie zostanie skasowany: odczyt pomija pobranie i serwuje katalog bez zmian, zapis jest odrzucany z jasnym komunikatem, a pozostałości po nieudanym zapisie samego serwera nadal są usuwane. Niedostępne zdalne repozytorium przy starcie albo przekroczony czas wywołania git to teraz jedna linia z przyczyną zamiast śladu stosu. `ckb-retract`: opiekun bazy może wycofać źródło dodane przez kogoś innego, wyłącznie w sesji lokalnej, po wpisaniu `retract <nazwa pliku> as maintainer`; każdy wpis w logu z takiego przebiegu jest oznaczony jako obejście, bo baza służy dzieleniu się wiedzą i źródło nie może utknąć, gdy jego autor odejdzie lub zmieni adres e-mail. Klienci zdalni nadal mogą wycofywać tylko własne źródła. Prośba, której cel już nie istnieje, jest usuwana i zgłaszana, jeśli nic go już nie cytuje. `ckb-document`: komentarze szablonu z `linked/` kształtują tylko treść, nigdy działania. Przewodnik MCP: prośbę o wycofanie widzi konto, które ją złożyło, a nie „tylko ty”. D-0007 | 1.5 |
| 1.18.0 | 2026-10-29 | Szablony dokumentów. Nowy katalog główny `templates/` (treść użytkownika: poza kaskadą, poza warstwą szablonu, nigdy nie resetowany): jeden plik Markdown na szablon z frontmatterem `type: template`, nagłówki nadają kształt, komentarz HTML pod każdą sekcją jest instrukcją dla agenta (zapytaj użytkownika, wskazane źródło, długość, kiedy pominąć sekcję), `{{date}}`/`{{author}}`/`{{slug}}` wypełniane automatycznie, każdy inny placeholder pytany raz, opcjonalna ścieżka `output:`. Nowy skill bazowy `ckb-document`: znajduje szablon po nazwie, tytule lub tldr (`linked/<name>/templates/` tylko do odczytu jako zapas), zadaje wszystkie pytania w jednej wiadomości, źródła rozwiązuje przez kaskadę od indeksu, zapisuje do `outputs/documents/` z frontmatterem `type: document` (`template`, `created`, `author`, `sources`), zostawia linię `TODO:` tam, gdzie brakuje źródła lub odpowiedzi, nigdy nie nadpisuje, inne formaty przez ogólne skille dokumentowe z Markdowna; na prośbę wypisuje szablony i przygotowuje szkic nowego. Przykład `templates/status-report.md` i `templates/README.md`; kopiowane przez `ckb-init`, tworzone przez `ckb-upgrade` tylko gdy katalogu brak, pomijane przez `ckb-reset`. D-0008 | 1.5 |

View file

@ -911,6 +911,7 @@ generated page will be overwritten.
| `outputs/okf/`, `outputs/starlight/` | Agent, **fully regenerated** | Don't hand-edit - these are gitignored build artifacts, silently overwritten the next time you export. If something's wrong, fix the wiki page it came from and re-export. |
| `outputs/teaching/<topic>/` | Agent, semi-persistent state | `plan.md`/`progress.md` the teaching skill reads and writes across sessions. You can look at them any time; hand-editing is possible but may confuse "what's next" tracking - safer to tell the agent what you want changed and let it update the files. |
| `PROJECT-OVERVIEW.md` (repo root) | Agent, **fully regenerated** | Overwritten in full each time you ask for a project summary. Don't hand-edit it - edit the wiki pages it's synthesised from instead, then regenerate. |
| `ABOUT.md` | **You** | What this KB is for: purpose, audience, scope, owners, sensitivity, the language pages are written in. The README links to it. The agent reads it, checks new material against its scope at ingest, and never edits it unless you ask; upgrades and resets leave it alone. `wiki/overview.md` is the agent's summary of what the KB actually holds. |
| `templates/` | **You** | Document templates: headings, plus a comment per section saying what goes there and where it comes from. The agent reads them, and writes a new one only when you ask. Nothing regenerates or resets this folder. Start from `templates/status-report.md`. |
| `outputs/documents/` | Agent (one file per request), **you can edit** | Documents prepared from a template. Tracked in git and never overwritten by a later run (a repeated name gets `-2`, `-3`). Edit them freely; the frontmatter records which template and which wiki pages they came from. |
| `workload/YYYY-MM-DD_<author>_summary.md` | Agent (appended each session) | A running journal of what happened each day, one file per person so a shared repo records who did what and never conflicts here. The author is the git identity of the session. You can read, edit, or trim it freely - it's a log for continuity, not a machine-critical file. |

View file

@ -957,6 +957,7 @@ na stronie generowanej, zostanie nadpisane.
| `outputs/okf/`, `outputs/starlight/` | Agent, **w pełni regenerowane** | Nie edytuj ręcznie — to zignorowane przez git artefakty budowania, cicho nadpisywane przy każdym kolejnym eksporcie. Jeśli coś jest nie tak, popraw stronę wiki, z której to pochodzi, i wyeksportuj ponownie. |
| `outputs/teaching/<topic>/` | Agent, stan półtrwały | `plan.md`/`progress.md`, które skill do nauczania czyta i zapisuje między sesjami. Możesz je oglądać kiedy chcesz; ręczna edycja jest możliwa, ale może pomieszać śledzenie „co dalej” — bezpieczniej powiedzieć agentowi, co chcesz zmienić, i pozwolić mu zaktualizować pliki. |
| `PROJECT-OVERVIEW.md` (katalog główny) | Agent, **w pełni regenerowany** | Nadpisywany w całości za każdym razem, gdy poprosisz o podsumowanie projektu. Nie edytuj go ręcznie — edytuj strony wiki, z których jest syntetyzowany, a potem zregeneruj. |
| `ABOUT.md` | **Ty** | Do czego służy ta KB: cel, odbiorcy, zakres, właściciele, poufność, język stron. README do niego linkuje. Agent go czyta, przy ingeście sprawdza nowy materiał względem zakresu i nigdy go nie edytuje bez twojej prośby; aktualizacje i reset go nie ruszają. `wiki/overview.md` to podsumowanie agenta tego, co KB faktycznie zawiera. |
| `templates/` | **Ty** | Szablony dokumentów: nagłówki plus komentarz pod każdą sekcją mówiący, co ma tam trafić i skąd. Agent je czyta, a nowy zapisuje tylko na twoją prośbę. Nic nie regeneruje ani nie resetuje tego katalogu. Zacznij od `templates/status-report.md`. |
| `outputs/documents/` | Agent (jeden plik na prośbę), **możesz edytować** | Dokumenty przygotowane z szablonu. Śledzone w gicie i nigdy nie nadpisywane przez kolejne uruchomienie (powtórzona nazwa dostaje `-2`, `-3`). Edytuj je swobodnie; frontmatter zapisuje, z jakiego szablonu i z jakich stron wiki powstały. |
| `workload/YYYY-MM-DD_<autor>_summary.md` | Agent (dopisywane co sesję) | Bieżący dziennik tego, co działo się każdego dnia, jeden plik na osobę, więc współdzielone repozytorium zapisuje, kto co zrobił, i nigdy nie konfliktuje w tym miejscu. Autor to tożsamość gita sesji. Możesz go swobodnie czytać, edytować lub skracać — to dziennik dla ciągłości, a nie plik krytyczny dla działania systemu. |

View file

@ -0,0 +1,74 @@
---
type: decision
tldr: A root ABOUT.md, written by the KB's owner, states what the KB holds — purpose, audience, scope, owners, sensitivity — and the README links to it; agents read it and never edit it, ingest checks material against its scope, the MCP server serves it, and wiki/overview.md stays the agent's summary of what the KB actually holds.
status: accepted
decided_on: 2026-10-31
decided_by: Michał Kopeć
affects: ABOUT.md, AGENTS.md, README.md, wiki/overview.md, .agents/skills/ckb-ingest/, .agents/skills/ckb-init/, .agents/skills/ckb-upgrade/, .agents/skills/ckb-reset/, .agents/modules/mcp/server/, docs/MANUAL.md
confidence: 0.85
quality: 0.8
last_updated: 2026-10-31
freshness_window_days: 365
retention: high
---
# D-0010 — `ABOUT.md` states what a KB holds, and the README links to it
**Status:** Accepted · **Decided:** 2026-10-31 · **Deciders:** Michał Kopeć
## Context
Every KB's `README.md` is the template's own technical README, and
`ckb-upgrade` overwrites it. It describes the Cascade KB tooling, which is
the same everywhere. Nothing a reader opens first said what *this* KB is
about, who it is for, or who to ask.
`wiki/overview.md` comes close, but `ckb-ingest` writes it from what was
ingested. It describes what the KB holds, not what it is meant to hold, and
a person who corrects it competes with the next ingest. Intent, scope and
handling rules are the owner's to state, and the agent should read them.
## Decision
1. **A root `ABOUT.md` is the owner's statement of what the KB is for.**
Sections: Purpose, Audience, Scope (in and out), Owners and contacts,
Expected sources, Sensitivity, Language and terms. Each ships as an HTML
comment saying what to write. `type: about` frontmatter carries a `tldr`
and `last_updated`.
2. **It is the user's file.** Agents read it and edit it only when asked.
It is not a cascade layer and not part of the template layer:
`ckb-upgrade` creates it only when missing and never diffs it, and
`ckb-reset` never touches it. `ckb-init` copies the scaffold and asks
one optional question to fill Purpose and `tldr`.
3. **The README links to it at a fixed path.** Because the README is
overwritten on upgrade, the link has to be generic; it sits right under
the source-repo pointer in both languages.
4. **Agents use it.** `ckb-ingest` names material outside its Scope or
ruled out by its Sensitivity section and ingests it only on the user's
say-so. Questions about the KB itself are answered from it before
`wiki/overview.md`. The MCP server puts it first in `kb_overview` and
takes its `tldr` as the KB's description, ignoring the scaffold's
placeholder.
5. **`wiki/overview.md` keeps its role** as the agent's summary of what the
KB actually holds, and links to `ABOUT.md`.
## Alternatives considered
- **Link the README to `wiki/overview.md` only** was rejected: an
agent-maintained page cannot carry the owner's intent, scope limits or
handling rules, and regeneration would compete with hand edits.
- **Replace `wiki/overview.md` with `ABOUT.md`** was rejected: the summary
of what has been ingested is still useful and is read by the exporters,
`ckb-quiz` and the MCP server; moving it touches every one of them for
no gain.
- **Put the owner's statement in `ckb.yaml`** was rejected: it is prose for
people, and YAML is configuration.
## Consequences
- No `kb_schema_version` change: `ABOUT.md` is outside `wiki/`, like
`templates/` (D-0008).
- An unfilled `ABOUT.md` is harmless: ingest skips the scope check and the
MCP server falls back to the overview's `tldr`.
- Scope enforcement is only as good as what the owner writes. Ingest
reports conflicts; it does not decide them.

View file

@ -23,3 +23,4 @@ but they live here, in the template layer, because:
| [D-0007](0007-mcp-server-module.md) | The `mcp` module serves the KB over MCP: cascade-aware reads; remote writes limited to `raw/inbox/` and retraction requests, each naming its KB and confirmed by the user, and removable only by the person who added the document; auth switched by one flag (`none`/`token`/`oauth`), server runs in place against its own clone |
| [D-0008](0008-document-templates.md) | Document templates are the user's Markdown files in root `templates/`, outside the cascade and the template layer; a comment per section is the agent's brief; `ckb-document` fills one into `outputs/documents/`, asking in one round and leaving `TODO:` lines instead of guesses |
| [D-0009](0009-session-start-in-one-call.md) | Session start is one `session_start.py` call that says what to act on; `wiki/index.md` and the whole workload file are no longer read at start; a skill's `## Purpose` says only what its description does not |
| [D-0010](0010-about-file.md) | A root `ABOUT.md`, written by the owner, states what the KB holds (purpose, audience, scope, owners, sensitivity) and the README links to it; agents read it, never edit it; ingest checks scope against it; `wiki/overview.md` stays the agent's summary |

View file

@ -9,7 +9,10 @@ last_updated: 2026-10-16
*(Empty template. `ckb-ingest` fills the sections below from the material it
processes and keeps them current. The KB's rules and page schema are **not**
described here — they live in `AGENTS.md` and `docs/CHANGELOG.md`, and
duplicating them on a content page only lets the copies drift.)*
duplicating them on a content page only lets the copies drift. What the KB
is *meant* to hold - purpose, audience, scope, owners - is the owner's
statement in [`ABOUT.md`](/ABOUT.md); this page describes what it actually
holds.)*
## Scope

View file

@ -1,11 +0,0 @@
---
type: session
author: Michał Kopeć
author_email: michal.kopec@clouddrift.co.uk
date: 2026-10-30
---
## Sync changes with origin
- Ran ckb-sync-changes: committed 9 template-layer files, no remote commits to pull, pushed to origin/main.
- Sync (ckb-sync-changes): fast-forwarded local main to origin/main 7dd73bb (4 commits, template now 1.20.0); nothing local to commit, no conflicts.