From da2833abfe50572760064f2e26e735496e836dd0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Kope=C4=87?= Date: Sun, 1 Nov 2026 21:31:36 +0100 Subject: [PATCH] Sync: local changes as of 2026-11-01T20:31:36Z Co-Authored-By: Claude Opus 5.5 --- .agents/modules/mcp/README.md | 2 +- .agents/modules/mcp/README.pl.md | 2 +- .agents/modules/mcp/server/kb.py | 2 +- .agents/modules/mcp/server/server.py | 18 +++-- .agents/skills/ckb-ingest/SKILL.md | 8 +++ .agents/skills/ckb-init/SKILL.md | 7 ++ .agents/skills/ckb-reset/SKILL.md | 7 +- .agents/skills/ckb-upgrade/SKILL.md | 8 ++- ABOUT.md | 64 ++++++++++++++++++ AGENTS.md | 7 ++ README.md | 6 ++ README.pl.md | 6 ++ VERSION | 2 +- docs/CHANGELOG.md | 3 +- docs/CHANGELOG.pl.md | 3 +- docs/MANUAL.md | 1 + docs/MANUAL.pl.md | 1 + docs/decisions/0010-about-file.md | 74 +++++++++++++++++++++ docs/decisions/README.md | 1 + wiki/overview.md | 5 +- workload/2026-10-30_michal-kopec_summary.md | 11 --- 21 files changed, 210 insertions(+), 28 deletions(-) create mode 100644 ABOUT.md create mode 100644 docs/decisions/0010-about-file.md delete mode 100644 workload/2026-10-30_michal-kopec_summary.md diff --git a/.agents/modules/mcp/README.md b/.agents/modules/mcp/README.md index 27f4a18..e221d60 100644 --- a/.agents/modules/mcp/README.md +++ b/.agents/modules/mcp/README.md @@ -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 | diff --git a/.agents/modules/mcp/README.pl.md b/.agents/modules/mcp/README.pl.md index f8c4937..2237d0b 100644 --- a/.agents/modules/mcp/README.pl.md +++ b/.agents/modules/mcp/README.pl.md @@ -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 | diff --git a/.agents/modules/mcp/server/kb.py b/.agents/modules/mcp/server/kb.py index 9f2910f..d5a8593 100644 --- a/.agents/modules/mcp/server/kb.py +++ b/.agents/modules/mcp/server/kb.py @@ -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')}") diff --git a/.agents/modules/mcp/server/server.py b/.agents/modules/mcp/server/server.py index 4d06e6f..9340153 100644 --- a/.agents/modules/mcp/server/server.py +++ b/.agents/modules/mcp/server/server.py @@ -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: diff --git a/.agents/skills/ckb-ingest/SKILL.md b/.agents/skills/ckb-ingest/SKILL.md index 2ed312a..5c618ab 100644 --- a/.agents/skills/ckb-ingest/SKILL.md +++ b/.agents/skills/ckb-ingest/SKILL.md @@ -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 diff --git a/.agents/skills/ckb-init/SKILL.md b/.agents/skills/ckb-init/SKILL.md index 955eadc..3c572fd 100644 --- a/.agents/skills/ckb-init/SKILL.md +++ b/.agents/skills/ckb-init/SKILL.md @@ -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. diff --git a/.agents/skills/ckb-reset/SKILL.md b/.agents/skills/ckb-reset/SKILL.md index 389b300..1844c59 100644 --- a/.agents/skills/ckb-reset/SKILL.md +++ b/.agents/skills/ckb-reset/SKILL.md @@ -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. diff --git a/.agents/skills/ckb-upgrade/SKILL.md b/.agents/skills/ckb-upgrade/SKILL.md index 8595e98..11c5c7a 100644 --- a/.agents/skills/ckb-upgrade/SKILL.md +++ b/.agents/skills/ckb-upgrade/SKILL.md @@ -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 diff --git a/ABOUT.md b/ABOUT.md new file mode 100644 index 0000000..2968b67 --- /dev/null +++ b/ABOUT.md @@ -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 + + + +## Purpose + + + +## Audience + + + +## Scope + +**In scope:** + + + +**Out of scope:** + + + +## Owners and contacts + + + +## Expected sources + + + +## Sensitivity + + + +## Language and terms + + diff --git a/AGENTS.md b/AGENTS.md index 6f4a8e0..8694159 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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//`. Connector-backed `libs//` folders are the exception: if a folder has diff --git a/README.md b/README.md index d44c25c..6202963 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/README.pl.md b/README.pl.md index 831e6da..e8cdc9e 100644 --- a/README.pl.md +++ b/README.pl.md @@ -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 diff --git a/VERSION b/VERSION index 3989355..3500250 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.20.0 +1.21.0 diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 8836526..f2fbb41 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -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__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__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 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//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 | diff --git a/docs/CHANGELOG.pl.md b/docs/CHANGELOG.pl.md index ef69de2..3bdf025 100644 --- a/docs/CHANGELOG.pl.md +++ b/docs/CHANGELOG.pl.md @@ -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__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__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 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//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 | diff --git a/docs/MANUAL.md b/docs/MANUAL.md index 034d544..d6f1fbc 100644 --- a/docs/MANUAL.md +++ b/docs/MANUAL.md @@ -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//` | 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__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. | diff --git a/docs/MANUAL.pl.md b/docs/MANUAL.pl.md index 268629e..9c19145 100644 --- a/docs/MANUAL.pl.md +++ b/docs/MANUAL.pl.md @@ -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//` | 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__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. | diff --git a/docs/decisions/0010-about-file.md b/docs/decisions/0010-about-file.md new file mode 100644 index 0000000..afc0535 --- /dev/null +++ b/docs/decisions/0010-about-file.md @@ -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. diff --git a/docs/decisions/README.md b/docs/decisions/README.md index f29b82d..020e211 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -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 | diff --git a/wiki/overview.md b/wiki/overview.md index 72e426d..54471dc 100644 --- a/wiki/overview.md +++ b/wiki/overview.md @@ -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 diff --git a/workload/2026-10-30_michal-kopec_summary.md b/workload/2026-10-30_michal-kopec_summary.md deleted file mode 100644 index a738e7c..0000000 --- a/workload/2026-10-30_michal-kopec_summary.md +++ /dev/null @@ -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.