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:
parent
eb607b19f3
commit
da2833abfe
21 changed files with 210 additions and 28 deletions
|
|
@ -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 |
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|
|
|
|||
|
|
@ -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')}")
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
64
ABOUT.md
Normal 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. -->
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
2
VERSION
2
VERSION
|
|
@ -1 +1 @@
|
|||
1.20.0
|
||||
1.21.0
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|
|
|
|||
|
|
@ -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. |
|
||||
|
|
|
|||
|
|
@ -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. |
|
||||
|
|
|
|||
74
docs/decisions/0010-about-file.md
Normal file
74
docs/decisions/0010-about-file.md
Normal 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.
|
||||
|
|
@ -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 |
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
Loading…
Add table
Reference in a new issue