Compare commits
9 commits
| Author | SHA1 | Date | |
|---|---|---|---|
| 60490c75ce | |||
| aca5237ad2 | |||
| 9d4999b8ce | |||
| a41893ec2e | |||
| e557fd1eb1 | |||
| a8aa3ef5c3 | |||
| 5e15b137f6 | |||
| 80b9974a61 | |||
| cd7ae4dd44 |
55 changed files with 313 additions and 3983 deletions
|
|
@ -1,82 +0,0 @@
|
|||
# `convert` module
|
||||
|
||||
*Read this in: **English** | [Polski](README.pl.md)*
|
||||
|
||||
Opt-in. Install with "install the convert module"; remove with "uninstall
|
||||
the convert module". Nothing in here is active until installed.
|
||||
|
||||
## What it does
|
||||
|
||||
The KB writes Markdown. The people you send things to want a Word file or a
|
||||
PDF that looks like the rest of your company's documents. This module turns
|
||||
any Markdown file in the KB into **`.docx`, `.odt`, PDF or HTML** through
|
||||
[pandoc](https://pandoc.org), in a **house style**, so nobody picks fonts,
|
||||
sizes or margins by hand.
|
||||
|
||||
| Skill | Does |
|
||||
|---|---|
|
||||
| `ckb-convert` | Converts a file in a named style; creates a style from a few settings or from your company's Word template; changes, checks and lists styles. |
|
||||
|
||||
Say "give me the status report as a Word file" or "convert this answer to
|
||||
PDF". The first time, it asks once how the house style should look.
|
||||
|
||||
## Styles
|
||||
|
||||
A style is a Word file, `templates/styles/<name>.docx`. pandoc takes fonts,
|
||||
sizes, colours, spacing, page size, margins, header and footer from it and
|
||||
ignores its text. You get one in one of three ways:
|
||||
|
||||
- **Describe it**: "make a house style with Georgia 11pt, navy headings, A4".
|
||||
- **Bring your own**: "use Company.dotx as the house style". The agent copies
|
||||
it in and tells you which styles pandoc needs that your template lacks.
|
||||
- **Edit it by hand** in Word or LibreOffice: change the *styles* (Normal,
|
||||
Body Text, Title, Heading 1–6, Table), not the text, and save as `.docx`.
|
||||
|
||||
Several styles can live side by side ("convert it in the board style").
|
||||
`<name>.css` styles HTML, and an optional `<name>.odt` styles ODT directly.
|
||||
|
||||
PDF and ODT are made from the styled `.docx` with LibreOffice, so all formats
|
||||
look the same. Without LibreOffice, PDF falls back to a pandoc PDF engine and
|
||||
won't follow the Word style. You'll be told when that happens.
|
||||
|
||||
## What changes on the way
|
||||
|
||||
The Markdown file is never changed and is always kept. In the converted
|
||||
copy:
|
||||
|
||||
- frontmatter becomes the title, author (without the e-mail) and date, and the
|
||||
first `# Heading` becomes the title when there's none;
|
||||
- `<!-- comments -->` left over from a template are dropped;
|
||||
- `[[Wikilinks]]` and links to KB paths become plain text, because they'd be
|
||||
dead in a Word file (say "keep the links" to keep them); web links stay;
|
||||
- code blocks, tables, task lists and images come through as they are.
|
||||
|
||||
## Settings
|
||||
|
||||
In `ckb.yaml`, under the module's entry. Change them by asking ("make PDF
|
||||
the default", "always add a table of contents"):
|
||||
|
||||
```yaml
|
||||
config:
|
||||
style: house # templates/styles/house.docx
|
||||
format: docx # docx | odt | pdf | html
|
||||
out_dir: outputs/documents/ # a file already in outputs/ converts beside itself
|
||||
toc: false
|
||||
number_sections: false
|
||||
keep_links: false
|
||||
```
|
||||
|
||||
## Requirements
|
||||
|
||||
- **pandoc**, for every conversion. The install doesn't need it, so a
|
||||
teammate without it can still clone the KB; they're told how to get it the
|
||||
first time they convert.
|
||||
- **LibreOffice**, optional, for PDF and ODT in the house style.
|
||||
- Python 3.8+ like every other KB script. Nothing is installed without asking.
|
||||
|
||||
## Good to know
|
||||
|
||||
- **Fonts aren't embedded** in a `.docx`. Choose fonts your readers have.
|
||||
- **Uninstalling keeps your styles**: `templates/styles/` stays.
|
||||
- **Macro templates** (`.docm`, `.dotm`) are refused; save a copy as `.docx`
|
||||
or `.dotx` first.
|
||||
|
|
@ -1,86 +0,0 @@
|
|||
# Moduł `convert`
|
||||
|
||||
*Przeczytaj w: [English](README.md) | **Polski***
|
||||
|
||||
Opcjonalny. Instalacja: „install the convert module”, usunięcie: „uninstall
|
||||
the convert module”. Dopóki nie jest zainstalowany, nic z tego folderu nie
|
||||
działa.
|
||||
|
||||
## Co robi
|
||||
|
||||
Baza pisze w Markdownie. Ludzie, do których coś wysyłasz, chcą pliku Worda
|
||||
albo PDF-a, który wygląda jak reszta dokumentów w firmie. Ten moduł zamienia
|
||||
dowolny plik Markdown z bazy na **`.docx`, `.odt`, PDF lub HTML** przez
|
||||
[pandoc](https://pandoc.org), w **stylu firmowym**, więc nikt nie dobiera
|
||||
ręcznie czcionek, rozmiarów ani marginesów.
|
||||
|
||||
| Skill | Co robi |
|
||||
|---|---|
|
||||
| `ckb-convert` | Konwertuje plik w wybranym stylu; tworzy styl z kilku ustawień albo z firmowego szablonu Worda; zmienia, sprawdza i wypisuje style. |
|
||||
|
||||
Powiedz „give me the status report as a Word file” albo „convert this answer
|
||||
to PDF”. Za pierwszym razem padnie jedno pytanie o to, jak ma wyglądać styl
|
||||
firmowy.
|
||||
|
||||
## Style
|
||||
|
||||
Styl to plik Worda, `templates/styles/<nazwa>.docx`. pandoc bierze z niego
|
||||
czcionki, rozmiary, kolory, odstępy, format strony, marginesy, nagłówek i
|
||||
stopkę, a jego treść pomija. Styl można zdobyć na trzy sposoby:
|
||||
|
||||
- **Opisać go**: „make a house style with Georgia 11pt, navy headings, A4”.
|
||||
- **Przynieść własny**: „use Company.dotx as the house style”. Agent go
|
||||
skopiuje i powie, których stylów potrzebnych pandocowi brakuje w szablonie.
|
||||
- **Poprawić ręcznie** w Wordzie lub LibreOffice: zmieniać *style* (Normal,
|
||||
Body Text, Title, Heading 1–6, Table), nie treść, i zapisać jako `.docx`.
|
||||
|
||||
Stylów może być kilka („convert it in the board style”). `<nazwa>.css`
|
||||
ustala wygląd HTML, a opcjonalny `<nazwa>.odt` wygląd ODT.
|
||||
|
||||
PDF i ODT powstają ze sformatowanego `.docx` przez LibreOffice, więc
|
||||
wszystkie formaty wyglądają tak samo. Bez LibreOffice PDF robi silnik PDF
|
||||
pandoca i styl Worda nie jest stosowany. Agent o tym powie.
|
||||
|
||||
## Co się zmienia po drodze
|
||||
|
||||
Plik Markdown nigdy się nie zmienia i zawsze zostaje. W skonwertowanej
|
||||
kopii:
|
||||
|
||||
- frontmatter staje się tytułem, autorem (bez adresu e-mail) i datą, a
|
||||
pierwszy nagłówek `#` staje się tytułem, gdy frontmatter go nie ma;
|
||||
- komentarze `<!-- … -->` pozostałe z szablonu znikają;
|
||||
- `[[Wikilinki]]` i linki do ścieżek w bazie stają się zwykłym tekstem, bo w
|
||||
pliku Worda byłyby martwe („keep the links” je zostawia); linki do stron
|
||||
WWW zostają;
|
||||
- bloki kodu, tabele, listy zadań i obrazy przechodzą bez zmian.
|
||||
|
||||
## Ustawienia
|
||||
|
||||
W `ckb.yaml`, we wpisie modułu. Zmienia się je prośbą („make PDF the
|
||||
default”, „always add a table of contents”):
|
||||
|
||||
```yaml
|
||||
config:
|
||||
style: house # templates/styles/house.docx
|
||||
format: docx # docx | odt | pdf | html
|
||||
out_dir: outputs/documents/ # plik już leżący w outputs/ trafia obok siebie
|
||||
toc: false
|
||||
number_sections: false
|
||||
keep_links: false
|
||||
```
|
||||
|
||||
## Wymagania
|
||||
|
||||
- **pandoc** do każdej konwersji. Instalacja modułu go nie wymaga, więc
|
||||
osoba z zespołu bez pandoca nadal może sklonować bazę; przy pierwszej
|
||||
konwersji dowie się, jak go zainstalować.
|
||||
- **LibreOffice**, opcjonalnie, do PDF i ODT w stylu firmowym.
|
||||
- Python 3.8+, jak każdy skrypt bazy. Nic nie jest instalowane bez pytania.
|
||||
|
||||
## Warto wiedzieć
|
||||
|
||||
- **Czcionki nie są osadzane** w `.docx`. Wybieraj czcionki, które mają
|
||||
czytelnicy.
|
||||
- **Odinstalowanie zostawia style**: `templates/styles/` zostaje.
|
||||
- **Szablony z makrami** (`.docm`, `.dotm`) są odrzucane; najpierw zapisz
|
||||
kopię jako `.docx` lub `.dotx`.
|
||||
|
|
@ -1,16 +0,0 @@
|
|||
## MODULE: convert
|
||||
|
||||
Markdown in this KB becomes Word, ODT, PDF or HTML through pandoc, in a house
|
||||
style: `templates/styles/<name>.docx`. Settings are under the `convert`
|
||||
entry of `kb_modules:` in `ckb.yaml`.
|
||||
|
||||
- A request for a document as `.docx`, `.odt`, `.pdf` or `.html` ("as a Word
|
||||
file", "send me a PDF") goes through `ckb-convert`, after the Markdown is
|
||||
final (after `ckb-voice`, when that module is installed). The Markdown is
|
||||
always kept beside the converted file.
|
||||
- Styles are the user's files: create or change one only on request, and
|
||||
never edit a style the user supplied (`--from`) unless asked.
|
||||
|
||||
| User intent | Skill |
|
||||
|---|---|
|
||||
| Convert Markdown to Word/ODT/PDF/HTML, or create, change, check or list a house style | `ckb-convert` |
|
||||
|
|
@ -1 +0,0 @@
|
|||
# convert module: nothing extra to ignore (styles in templates/styles/ are tracked).
|
||||
|
|
@ -1,56 +0,0 @@
|
|||
# Cascade KB module manifest — read by `ckb-module` on install/uninstall.
|
||||
# See docs/decisions/0021-convert-module.md.
|
||||
name: convert
|
||||
title: Document conversion with house styles
|
||||
version: 1.0.0
|
||||
requires_kb_schema: "1.7"
|
||||
summary: >
|
||||
Turns any Markdown file in the KB (a document from a template, a kept
|
||||
answer, a report, a wiki page) into Word, OpenDocument, PDF or HTML through
|
||||
pandoc, in a named house style kept in templates/styles/, so nobody has to
|
||||
pick fonts, sizes or margins by hand.
|
||||
|
||||
skills:
|
||||
- ckb-convert
|
||||
|
||||
# Created on install, never removed on uninstall: it holds the user's styles.
|
||||
scaffold:
|
||||
- path: templates/styles/
|
||||
from: scaffold/styles-README.md
|
||||
as: templates/styles/README.md
|
||||
note: House styles, one NAME.docx per style (NAME.odt and NAME.css optional).
|
||||
|
||||
agents_fragment: fragments/agents-routing.md
|
||||
gitignore_fragment: fragments/gitignore.snippet
|
||||
|
||||
# Written under this module's `config:` in ckb.yaml on install; ckb-convert
|
||||
# owns them afterwards ("make PDF the default", "use the board style").
|
||||
default_config:
|
||||
style: house # templates/styles/<style>.docx, used when the request names none
|
||||
format: docx # docx | odt | pdf | html
|
||||
out_dir: outputs/documents/ # for files outside outputs/; a file in outputs/ converts beside itself
|
||||
toc: false # table of contents
|
||||
number_sections: false
|
||||
keep_links: false # true = keep links to KB paths (dead outside the KB)
|
||||
|
||||
schema_additions:
|
||||
types: []
|
||||
fields: []
|
||||
|
||||
depends_on:
|
||||
- name: pandoc
|
||||
scope: all
|
||||
check: "command -v pandoc"
|
||||
optional: true
|
||||
note: >
|
||||
Does every conversion, so nothing converts without it. Optional only for
|
||||
the install: the module is committed and shared, and a teammate without
|
||||
pandoc is told how to get it when they first convert. Never installed
|
||||
without asking.
|
||||
- name: libreoffice
|
||||
scope: pdf-and-odt
|
||||
check: "command -v soffice || command -v libreoffice"
|
||||
optional: true
|
||||
note: >
|
||||
Turns the styled .docx into PDF or ODT so every format looks the same.
|
||||
Without it PDF needs a pandoc PDF engine and ignores the Word style.
|
||||
|
|
@ -1,26 +0,0 @@
|
|||
# House styles
|
||||
|
||||
One file per style, used by `ckb-convert` (the `convert` module) to turn
|
||||
Markdown into Word, OpenDocument, PDF or HTML:
|
||||
|
||||
| File | Used for | Required |
|
||||
|---|---|---|
|
||||
| `<name>.docx` | Word, and PDF/ODT made from it with LibreOffice | yes |
|
||||
| `<name>.odt` | ODT, when you want a separate LibreOffice style | no |
|
||||
| `<name>.css` | HTML | no |
|
||||
|
||||
pandoc takes fonts, sizes, colours, spacing, page size, margins, header and
|
||||
footer from the `.docx` and ignores any text in it.
|
||||
|
||||
Three ways to get a style:
|
||||
|
||||
- **Say what you want**: "make a house style with Georgia 11pt, navy
|
||||
headings, A4". The agent builds the `.docx`.
|
||||
- **Use your company's template**: "use Company.dotx as the house style". The
|
||||
agent copies it here and tells you which styles pandoc needs that it lacks.
|
||||
- **Edit by hand**: open `<name>.docx` in Word or LibreOffice, change the
|
||||
*styles* (Normal, Body Text, Title, Heading 1–6, Table…), not the text, and
|
||||
save it as `.docx`.
|
||||
|
||||
Fonts aren't embedded in a `.docx`. Choose fonts your readers have, or
|
||||
they'll see a substitute.
|
||||
|
|
@ -1,151 +0,0 @@
|
|||
---
|
||||
name: ckb-convert
|
||||
description: Convert a Markdown file from the KB (a document from a template, a kept answer, a report, a wiki page) into Word .docx, OpenDocument .odt, PDF or HTML through pandoc, in a house style kept in templates/styles/ so fonts, sizes, colours and margins are never picked by hand; also creates, changes, checks and lists house styles, including one made from a company .docx/.dotx. Use for "convert this to Word", "give me this as a docx/PDF", "export the status report as a Word file", "make a house style with Georgia and navy headings", "use our company template for documents", "list the styles", "make PDF the default".
|
||||
---
|
||||
|
||||
# Convert skill (module: convert)
|
||||
|
||||
## Purpose
|
||||
|
||||
People outside the KB want a Word file or a PDF that looks like the rest of
|
||||
their company's documents. pandoc does the conversion; the look comes from a
|
||||
**style**, a reference `.docx` in `templates/styles/<name>.docx` that the
|
||||
user never has to open. The Markdown stays the source: it's always kept, and
|
||||
the converted file is made from it again whenever it changes.
|
||||
|
||||
Nothing here touches `wiki/`, so Rule B doesn't apply; Rule D does.
|
||||
|
||||
## Settings
|
||||
|
||||
Under the `convert` entry of `kb_modules:` in `ckb.yaml`, `config:`:
|
||||
|
||||
| Key | Default | Meaning |
|
||||
|---|---|---|
|
||||
| `style` | `house` | Style used when the request names none |
|
||||
| `format` | `docx` | `docx`, `odt`, `pdf` or `html` when the request names none |
|
||||
| `out_dir` | `outputs/documents/` | Where a file from outside `outputs/` is written; a file already in `outputs/` converts beside itself |
|
||||
| `toc` | `false` | Add a table of contents |
|
||||
| `number_sections` | `false` | Number the headings |
|
||||
| `keep_links` | `false` | Keep links to KB paths, which are dead in a Word file |
|
||||
|
||||
The request wins over a setting ("as a PDF", "with a table of contents").
|
||||
"Make PDF the default" or "use the board style by default" edits only that
|
||||
key's value in `ckb.yaml` and says so in one line.
|
||||
|
||||
## The script
|
||||
|
||||
```bash
|
||||
<python> .agents/skills/ckb-convert/scripts/convert.py <command> …
|
||||
```
|
||||
|
||||
Resolve `<python>` per "Scripts and the Python Runtime" in `AGENTS.md`. Run it
|
||||
from the KB root (or pass `--root`). Exit codes: `0` done, `1` refused (the
|
||||
message says why), `3` a program is missing or failed.
|
||||
|
||||
| Command | Does |
|
||||
|---|---|
|
||||
| `doctor` | pandoc version, LibreOffice, how PDF will be made, styles present |
|
||||
| `styles` | Lists `templates/styles/` |
|
||||
| `convert FILE --to FMT --style NAME [--toc] [--number-sections] [--keep-links] [--out PATH \| --out-dir DIR] [--force]` | Converts one file |
|
||||
| `new-style NAME [--from FILE] [settings]` | Creates a style from pandoc's default, or from a company `.docx`/`.dotx` |
|
||||
| `edit-style NAME settings` | Changes a style |
|
||||
| `check-style NAME` | Lists the styles pandoc uses that NAME doesn't define |
|
||||
|
||||
Settings: `--body-font F`, `--heading-font F`, `--size PT` (body text),
|
||||
`--heading-color RRGGBB`, `--paper a4|letter`, `--margin-cm CM`.
|
||||
|
||||
## How to run this skill
|
||||
|
||||
### Step 1 — Check the tools once per session
|
||||
|
||||
Run `doctor`. If pandoc is missing, stop and tell the user how to install it
|
||||
on their system (the error names the commands). Never install it yourself.
|
||||
If LibreOffice is missing and they asked for PDF or ODT, say once that the
|
||||
file won't follow the Word style and how to install LibreOffice, then go on.
|
||||
|
||||
### Step 2 — Make sure there's a style
|
||||
|
||||
If the style to use exists, go to Step 3. If `templates/styles/` has no style
|
||||
at all, ask **one** question before converting:
|
||||
|
||||
> There's no house style yet. Use a plain default (Calibri 11pt, dark-blue
|
||||
> headings, A4), tell me fonts/colours/paper, or give me your company's Word
|
||||
> template (.docx or .dotx)?
|
||||
|
||||
- Default: `new-style house --body-font Calibri --heading-font Calibri
|
||||
--size 11 --heading-color 1F3864 --paper a4 --margin-cm 2.5`.
|
||||
- Their own settings: the same command with their values. A colour named in
|
||||
words becomes hex ("navy" → `1F3864`); a page size other than A4/Letter isn't
|
||||
supported, so say so and use the closer one.
|
||||
- A company template: `new-style house --from <file>`. Report the `check:`
|
||||
lines it prints in plain words: a missing *Heading 1* means headings will
|
||||
use pandoc's look, not the company's. Offer to fill only the missing ones
|
||||
with settings (`edit-style`), never to change the ones that exist.
|
||||
|
||||
If other styles exist but not the one named, list them and ask which to use.
|
||||
|
||||
### Step 3 — Convert
|
||||
|
||||
Check that the Markdown is final first. If it was just written and the `voice`
|
||||
module is installed, the voice pass comes before conversion.
|
||||
|
||||
```bash
|
||||
<python> .agents/skills/ckb-convert/scripts/convert.py convert <file.md> --to <fmt> --style <style> [flags from settings]
|
||||
```
|
||||
|
||||
Several files, or several formats of one file: one call each.
|
||||
|
||||
- **`refused: exists`** — the converted file is already there. Ask once:
|
||||
replace it (`--force`) or keep both (`--out` with `-2` before the
|
||||
extension). A file made earlier may have been edited in Word since.
|
||||
- **`note:` lines** — pass them on in plain words. A `pandoc:` note about a
|
||||
missing image names the file; check the path.
|
||||
|
||||
What the script changes on the way, so you can explain it if asked: the
|
||||
frontmatter becomes the title, author (without the e-mail) and date; the
|
||||
first `# Heading` becomes the title when the frontmatter has none; `<!--
|
||||
comments -->` are dropped; `[[Wikilinks]]` and links to KB paths become plain
|
||||
text (`--keep-links` keeps the links); web links stay; code blocks stay as
|
||||
they are. Sections such as `## Sources` are content and stay. If the reader
|
||||
shouldn't see them, offer a copy of the Markdown without them, and never edit
|
||||
the original for that.
|
||||
|
||||
### Step 4 — Report
|
||||
|
||||
One line per file: path, format, style. Add the notes that matter. For a
|
||||
`.docx` with `--toc`, say the reader may have to accept "update fields" when
|
||||
Word opens it. Offer nothing else.
|
||||
|
||||
## Changing a style
|
||||
|
||||
"Make the headings green", "use Georgia", "switch to Letter paper":
|
||||
`edit-style <name>` with only the settings asked for, then offer to
|
||||
reconvert the last file. Ask first if the style came from the user's own
|
||||
template (`--from`): they may want their file left as it is.
|
||||
|
||||
For anything the settings can't do (a logo in the header, a cover page, line
|
||||
spacing, table borders), tell the user to open `templates/styles/<name>.docx`
|
||||
in Word or LibreOffice, change the **styles** (not the text), and save it as
|
||||
`.docx`. pandoc reads fonts, sizes, colours, spacing, page size, margins,
|
||||
header and footer from it and ignores its text.
|
||||
|
||||
`.odt` and `.css` styles are optional and hand-made: `NAME.odt` is used for
|
||||
ODT instead of going through LibreOffice, and `NAME.css` for HTML.
|
||||
|
||||
## Edge cases
|
||||
|
||||
- **The file isn't Markdown** (a `.docx` to turn into PDF): pandoc can't keep
|
||||
the look that way. Offer LibreOffice directly (`soffice --headless
|
||||
--convert-to pdf`) or the general document skills.
|
||||
- **A wiki page** is converted like any file. The output goes to `out_dir`,
|
||||
never into `wiki/`.
|
||||
- **Mermaid diagrams** stay as code blocks; pandoc doesn't draw them. Say so
|
||||
if the file has one.
|
||||
- **Fonts aren't embedded** in `.docx`. A font the reader lacks shows as a
|
||||
substitute; in PDF, LibreOffice substitutes on this machine. Suggest common
|
||||
fonts if the user picks something rare.
|
||||
- **A `.docm`/`.dotm`** (macros) is refused: ask for a copy saved as `.docx`
|
||||
or `.dotx`.
|
||||
- **Without Python**: run pandoc by hand,
|
||||
`pandoc <file.md> -o <out.docx> --reference-doc templates/styles/<style>.docx`,
|
||||
and say the KB clean-up (frontmatter, wikilinks, comments) was skipped.
|
||||
|
|
@ -1,746 +0,0 @@
|
|||
#!/usr/bin/env python3
|
||||
"""Turn a KB Markdown file into a Word, OpenDocument, PDF or HTML file in a
|
||||
house style, through pandoc. The style is a file the user never has to open:
|
||||
|
||||
convert.py convert FILE.md [--to docx|odt|pdf|html] [--style NAME] [--out PATH]
|
||||
[--out-dir DIR] [--toc] [--number-sections]
|
||||
[--keep-links] [--force]
|
||||
convert.py new-style NAME [--from FILE.docx|.dotx] [--body-font F] [--heading-font F]
|
||||
[--size PT] [--heading-color RRGGBB] [--paper a4|letter]
|
||||
[--margin-cm CM] [--force]
|
||||
convert.py edit-style NAME [same options as new-style, without --from]
|
||||
convert.py check-style NAME # which styles pandoc uses are missing from NAME.docx
|
||||
convert.py styles # list templates/styles/
|
||||
convert.py doctor # pandoc, LibreOffice, PDF route
|
||||
|
||||
Styles live in templates/styles/: NAME.docx (the Word reference document,
|
||||
required), NAME.odt and NAME.css (optional, for odt and html). pandoc takes
|
||||
fonts, sizes, colours, spacing, page size, margins, header and footer from the
|
||||
reference document and ignores its text.
|
||||
|
||||
Before conversion the Markdown is cleaned for a reader outside the KB: the
|
||||
frontmatter becomes title/author/date/lang metadata, the first `# H1` becomes
|
||||
the title when the frontmatter has none, HTML comments are dropped,
|
||||
[[Wikilinks]] become plain text, and links to KB paths become their label
|
||||
(they would be dead in a Word file; --keep-links keeps them). Code blocks are
|
||||
never touched.
|
||||
|
||||
PDF and ODT go through the Word style: pandoc writes the .docx and LibreOffice
|
||||
converts it, so all formats look the same. Without LibreOffice, PDF falls back
|
||||
to a pandoc PDF engine (style not applied, said so) and ODT to pandoc's own.
|
||||
|
||||
Exit 0 = written, 1 = refused (output exists, unknown style, bad input),
|
||||
2 = usage, 3 = a required program is missing or failed.
|
||||
Python 3.8+, standard library only; needs pandoc, optionally LibreOffice.
|
||||
"""
|
||||
import argparse
|
||||
import json
|
||||
import re
|
||||
import shutil
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import zipfile
|
||||
from datetime import date
|
||||
from pathlib import Path
|
||||
|
||||
STYLES_DIR = Path("templates") / "styles"
|
||||
DEFAULT_OUT_DIR = Path("outputs") / "documents"
|
||||
FORMATS = ("docx", "odt", "pdf", "html")
|
||||
PDF_ENGINES = ("typst", "weasyprint", "wkhtmltopdf", "xelatex", "lualatex", "pdflatex")
|
||||
SOFFICE_TIMEOUT = 180
|
||||
|
||||
# The paragraph/character/table styles pandoc's docx writer uses. A reference
|
||||
# document without one of them gets pandoc's own definition for it.
|
||||
PANDOC_STYLES = [
|
||||
"Normal", "Body Text", "First Paragraph", "Compact", "Title", "Subtitle", "Author",
|
||||
"Date", "Abstract", "heading 1", "heading 2", "heading 3", "heading 4", "heading 5",
|
||||
"heading 6", "Block Text", "Source Code", "Verbatim Char", "Hyperlink", "Footnote Text",
|
||||
"Footnote Reference", "Caption", "Table Caption", "Image Caption", "Table", "TOC Heading",
|
||||
]
|
||||
KEY_STYLES = {"Normal", "Body Text", "Title", "heading 1", "heading 2", "heading 3", "Table"}
|
||||
|
||||
# Child order inside <w:rPr> and <w:sectPr> (ECMA-376). Word rejects a file
|
||||
# whose children are out of order, so inserts respect it.
|
||||
RPR_ORDER = ("rStyle rFonts b bCs i iCs caps smallCaps strike dstrike outline shadow emboss "
|
||||
"imprint noProof snapToGrid vanish webHidden color spacing w kern position sz szCs "
|
||||
"highlight u effect bdr shd fitText vertAlign rtl cs em lang eastAsianLayout "
|
||||
"specVanish oMath").split()
|
||||
SECTPR_ORDER = ("headerReference footerReference footnotePr endnotePr type pgSz pgMar paperSrc "
|
||||
"pgBorders lnNumType pgNumType cols formProt vAlign noEndnote titlePg "
|
||||
"textDirection bidi rtlGutter docGrid printerSettings sectPrChange").split()
|
||||
PAPER = {"a4": (11906, 16838), "letter": (12240, 15840)}
|
||||
HEADING_STYLE_IDS = ["Title", "Subtitle"] + ["Heading%d" % i for i in range(1, 10)]
|
||||
DOCX_CT = "application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"
|
||||
DOTX_CT = "application/vnd.openxmlformats-officedocument.wordprocessingml.template.main+xml"
|
||||
|
||||
|
||||
class Refused(Exception):
|
||||
"""Exit 1 with a message."""
|
||||
|
||||
|
||||
class Missing(Exception):
|
||||
"""Exit 3 with a message."""
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- tools
|
||||
|
||||
def pandoc_version():
|
||||
exe = shutil.which("pandoc")
|
||||
if not exe:
|
||||
return None
|
||||
try:
|
||||
out = subprocess.run([exe, "--version"], capture_output=True, timeout=30,
|
||||
encoding="utf-8", errors="replace").stdout
|
||||
except (OSError, subprocess.SubprocessError):
|
||||
return None
|
||||
m = re.search(r"pandoc(?:\.exe)?\s+(\d+(?:\.\d+)*)", out)
|
||||
return tuple(int(x) for x in m.group(1).split(".")) if m else (0,)
|
||||
|
||||
|
||||
def soffice():
|
||||
for name in ("soffice", "libreoffice"):
|
||||
exe = shutil.which(name)
|
||||
if exe:
|
||||
return exe
|
||||
for p in ("/Applications/LibreOffice.app/Contents/MacOS/soffice",
|
||||
r"C:\Program Files\LibreOffice\program\soffice.exe",
|
||||
r"C:\Program Files (x86)\LibreOffice\program\soffice.exe"):
|
||||
if Path(p).exists():
|
||||
return p
|
||||
return None
|
||||
|
||||
|
||||
def need_pandoc():
|
||||
v = pandoc_version()
|
||||
if v is None:
|
||||
raise Missing("pandoc not found. Install it from https://pandoc.org/installing.html "
|
||||
"(Fedora: dnf install pandoc; Debian/Ubuntu: apt install pandoc; "
|
||||
"macOS: brew install pandoc; Windows: winget install JohnMacFarlane.Pandoc).")
|
||||
return v
|
||||
|
||||
|
||||
def run(cmd, timeout=300):
|
||||
try:
|
||||
p = subprocess.run(cmd, capture_output=True, timeout=timeout, encoding="utf-8", errors="replace")
|
||||
except subprocess.TimeoutExpired:
|
||||
raise Missing("%s timed out after %ds" % (Path(cmd[0]).name, timeout))
|
||||
except OSError as e:
|
||||
raise Missing("could not run %s: %s" % (cmd[0], e))
|
||||
if p.returncode != 0:
|
||||
raise Missing("%s failed (exit %d):\n%s" % (Path(cmd[0]).name, p.returncode,
|
||||
(p.stderr or p.stdout).strip()))
|
||||
return p
|
||||
|
||||
|
||||
def soffice_convert(exe, src, fmt, workdir):
|
||||
"""Convert src with LibreOffice into workdir; return the new file's path.
|
||||
A private profile keeps it from colliding with a LibreOffice the user has open."""
|
||||
profile = (Path(workdir) / "lo-profile").resolve().as_uri()
|
||||
outdir = Path(workdir) / ("lo-out-" + fmt)
|
||||
outdir.mkdir(exist_ok=True)
|
||||
run([exe, "-env:UserInstallation=" + profile, "--headless", "--norestore",
|
||||
"--convert-to", fmt, "--outdir", str(outdir), str(src)], timeout=SOFFICE_TIMEOUT)
|
||||
out = outdir / (Path(src).stem + "." + fmt)
|
||||
if not out.exists():
|
||||
raise Missing("LibreOffice did not produce %s (is another conversion stuck?)" % out.name)
|
||||
return out
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- Markdown
|
||||
|
||||
def split_frontmatter(text):
|
||||
if not text.startswith("---\n"):
|
||||
return {}, text
|
||||
end = text.find("\n---", 4)
|
||||
if end < 0:
|
||||
return {}, text
|
||||
meta = {}
|
||||
for line in text[4:end].split("\n"):
|
||||
m = re.match(r"^([A-Za-z_][\w-]*):\s*(.*?)\s*$", line)
|
||||
if m:
|
||||
v = m.group(2)
|
||||
if len(v) >= 2 and v[0] == v[-1] and v[0] in "\"'":
|
||||
v = v[1:-1]
|
||||
meta[m.group(1)] = v
|
||||
rest = text[end + 4:]
|
||||
return meta, rest[1:] if rest.startswith("\n") else rest
|
||||
|
||||
|
||||
def split_fences(body):
|
||||
"""Yield (is_code, chunk). Fenced code blocks are passed through untouched."""
|
||||
out, buf, fence = [], [], None
|
||||
for line in body.split("\n"):
|
||||
m = re.match(r"^\s{0,3}(`{3,}|~{3,})", line)
|
||||
if fence is None and m:
|
||||
if buf:
|
||||
out.append((False, "\n".join(buf)))
|
||||
buf, fence = [line], m.group(1)
|
||||
elif fence is not None and re.match(r"^\s{0,3}" + re.escape(fence[0]) + "{%d,}\\s*$" % len(fence), line):
|
||||
buf.append(line)
|
||||
out.append((True, "\n".join(buf)))
|
||||
buf, fence = [], None
|
||||
else:
|
||||
buf.append(line)
|
||||
if buf:
|
||||
out.append((fence is not None, "\n".join(buf)))
|
||||
return out
|
||||
|
||||
|
||||
def is_external(target):
|
||||
return bool(re.match(r"^(?:[a-z][a-z0-9+.-]*:|#)", target, re.I))
|
||||
|
||||
|
||||
def wikilink_text(m):
|
||||
target, label = m.group(1), m.group(2)
|
||||
return label or target.rstrip("/").split("/")[-1].replace(".md", "")
|
||||
|
||||
|
||||
def clean_prose(text, keep_links):
|
||||
text = re.sub(r"<!--.*?-->\n?", "", text, flags=re.S)
|
||||
# Rule C pairs a wikilink with a Markdown link to the same page: keep one label.
|
||||
def pair(m):
|
||||
label = wikilink_text(m)
|
||||
return "[%s](%s)" % (label, m.group(3)) if keep_links else label
|
||||
text = re.sub(r"\[\[([^\]|\n]+)(?:\|([^\]\n]+))?\]\]\s*\(\[[^\]\n]*\]\(([^)\s]+)\)\)", pair, text)
|
||||
text = re.sub(r"\[\[([^\]|\n]+)(?:\|([^\]\n]+))?\]\]", wikilink_text, text)
|
||||
if not keep_links:
|
||||
def local(m):
|
||||
return m.group(0) if is_external(m.group(2)) else m.group(1)
|
||||
text = re.sub(r"(?<!!)\[([^\]\n]+)\]\(([^)\s]+)(?:\s+\"[^\"]*\")?\)", local, text)
|
||||
return text
|
||||
|
||||
|
||||
def prepare(text, keep_links):
|
||||
"""Return (metadata for pandoc, cleaned Markdown body)."""
|
||||
fm, body = split_frontmatter(text.lstrip("\ufeff").replace("\r\n", "\n"))
|
||||
meta = {}
|
||||
title = fm.get("title", "").strip()
|
||||
if not title:
|
||||
m = re.search(r"^# +(.+?)\s*#*\s*$", body, re.M)
|
||||
if m and not body[:m.start()].strip().strip("-").strip():
|
||||
title = m.group(1).strip()
|
||||
body = body[:m.start()] + body[m.end():].lstrip("\n")
|
||||
if title:
|
||||
meta["title"] = re.sub(r"\[\[([^\]|]+)(?:\|([^\]]+))?\]\]", wikilink_text, title)
|
||||
for key in ("subtitle",):
|
||||
if fm.get(key):
|
||||
meta[key] = fm[key]
|
||||
author = fm.get("author", "").strip()
|
||||
if author:
|
||||
meta["author"] = re.sub(r"\s*<[^>]*>", "", author).strip()
|
||||
when = fm.get("date") or fm.get("created") or ""
|
||||
if when:
|
||||
meta["date"] = when
|
||||
if fm.get("lang"):
|
||||
meta["lang"] = fm["lang"]
|
||||
parts = [chunk if code else clean_prose(chunk, keep_links) for code, chunk in split_fences(body)]
|
||||
return meta, "\n".join(parts).strip("\n") + "\n"
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- docx XML
|
||||
|
||||
def children(inner):
|
||||
"""Direct <w:*> children of an element's inner XML as (name, start, end)."""
|
||||
out, pos = [], 0
|
||||
tag = re.compile(r"<w:([A-Za-z]+)\b[^>]*?(/?)>")
|
||||
while True:
|
||||
m = tag.search(inner, pos)
|
||||
if not m:
|
||||
return out
|
||||
if m.group(2) == "/":
|
||||
end = m.end()
|
||||
else:
|
||||
close = inner.find("</w:%s>" % m.group(1), m.end())
|
||||
end = len(inner) if close < 0 else close + len(m.group(1)) + 6
|
||||
out.append((m.group(1), m.start(), end))
|
||||
pos = end
|
||||
|
||||
|
||||
def set_child(inner, name, element, order):
|
||||
"""Replace every <w:name> child with element, placed in schema order."""
|
||||
for n, s, e in reversed(children(inner)):
|
||||
if n == name:
|
||||
inner = inner[:s] + inner[e:]
|
||||
rank = order.index(name)
|
||||
kids = children(inner)
|
||||
for n, s, _ in kids:
|
||||
if n in order and order.index(n) > rank:
|
||||
return inner[:s] + element + inner[s:]
|
||||
known = [e for n, _, e in kids if n in order]
|
||||
at = known[-1] if known else len(inner)
|
||||
return inner[:at] + element + inner[at:]
|
||||
|
||||
|
||||
def edit_block(xml, open_re, tag, fn):
|
||||
"""Apply fn to the inner XML of the first <w:tag> matched by open_re."""
|
||||
m = re.search(open_re, xml, re.S)
|
||||
if not m:
|
||||
return xml, False
|
||||
if m.group(0).endswith("/>"):
|
||||
new = "<w:%s>%s</w:%s>" % (tag, fn(""), tag)
|
||||
return xml[:m.start()] + new + xml[m.end():], True
|
||||
close = xml.find("</w:%s>" % tag, m.end())
|
||||
return xml[:m.end()] + fn(xml[m.end():close]) + xml[close:], True
|
||||
|
||||
|
||||
def style_span(xml, style_id):
|
||||
m = re.search(r'<w:style\b[^>]*w:styleId="%s"[^>]*>' % re.escape(style_id), xml)
|
||||
if not m:
|
||||
return None
|
||||
return m.start(), xml.find("</w:style>", m.end()) + len("</w:style>")
|
||||
|
||||
|
||||
def edit_style_rpr(xml, style_id, edits):
|
||||
span = style_span(xml, style_id)
|
||||
if not span:
|
||||
return xml, False
|
||||
block = xml[span[0]:span[1]]
|
||||
if not re.search(r"<w:rPr\s*/?>", block):
|
||||
block = block[:-len("</w:style>")] + "<w:rPr></w:rPr></w:style>"
|
||||
|
||||
def apply(inner):
|
||||
for name, element in edits:
|
||||
inner = set_child(inner, name, element, RPR_ORDER)
|
||||
return inner
|
||||
block, _ = edit_block(block, r"<w:rPr\s*/?>", "rPr", apply)
|
||||
return xml[:span[0]] + block + xml[span[1]:], True
|
||||
|
||||
|
||||
def fonts_el(font):
|
||||
f = xml_attr(font)
|
||||
return '<w:rFonts w:ascii="%s" w:hAnsi="%s" w:eastAsia="%s" w:cs="%s"/>' % (f, f, f, f)
|
||||
|
||||
|
||||
def xml_attr(s):
|
||||
return s.replace("&", "&").replace('"', """).replace("<", "<")
|
||||
|
||||
|
||||
def patch_styles(xml, opts, notes):
|
||||
rpr_edits = []
|
||||
if opts.body_font:
|
||||
rpr_edits.append(("rFonts", fonts_el(opts.body_font)))
|
||||
if opts.size:
|
||||
half = str(int(round(opts.size * 2)))
|
||||
rpr_edits += [("sz", '<w:sz w:val="%s"/>' % half), ("szCs", '<w:szCs w:val="%s"/>' % half)]
|
||||
if rpr_edits:
|
||||
def apply(inner):
|
||||
for name, element in rpr_edits:
|
||||
inner = set_child(inner, name, element, RPR_ORDER)
|
||||
return inner
|
||||
m = re.search(r"<w:rPrDefault>(.*?)</w:rPrDefault>", xml, re.S)
|
||||
if m:
|
||||
seg, _ = edit_block(m.group(1) if "<w:rPr" in m.group(1) else "<w:rPr></w:rPr>",
|
||||
r"<w:rPr\s*/?>", "rPr", apply)
|
||||
xml = xml[:m.start(1)] + seg + xml[m.end(1):]
|
||||
else:
|
||||
notes.append("no document defaults found; body font/size set on Normal only")
|
||||
# A template may pin its own font or size on Normal; the request wins there too.
|
||||
xml, _ = edit_style_rpr(xml, "Normal", rpr_edits)
|
||||
heading_edits = []
|
||||
if opts.heading_font:
|
||||
heading_edits.append(("rFonts", fonts_el(opts.heading_font)))
|
||||
if opts.heading_color:
|
||||
heading_edits.append(("color", '<w:color w:val="%s"/>' % opts.heading_color))
|
||||
if heading_edits:
|
||||
found = []
|
||||
for sid in HEADING_STYLE_IDS:
|
||||
xml, ok = edit_style_rpr(xml, sid, heading_edits)
|
||||
if ok:
|
||||
found.append(sid)
|
||||
if not found:
|
||||
notes.append("no Title or Heading styles found; heading settings not applied")
|
||||
return xml
|
||||
|
||||
|
||||
def patch_theme(xml, opts):
|
||||
for which, font in (("major", opts.heading_font), ("minor", opts.body_font)):
|
||||
if font:
|
||||
xml = re.sub(r'(<a:%sFont>\s*<a:latin typeface=")[^"]*(")' % which,
|
||||
lambda m: m.group(1) + xml_attr(font) + m.group(2), xml)
|
||||
return xml
|
||||
|
||||
|
||||
def patch_document(xml, opts):
|
||||
sects = list(re.finditer(r"<w:sectPr\b[^>]*?(/?)>", xml))
|
||||
if not sects:
|
||||
at = xml.rfind("</w:body>")
|
||||
if at < 0:
|
||||
return xml
|
||||
xml = xml[:at] + "<w:sectPr></w:sectPr>" + xml[at:]
|
||||
sects = list(re.finditer(r"<w:sectPr\b[^>]*?(/?)>", xml))
|
||||
m = sects[-1]
|
||||
if m.group(1) == "/":
|
||||
xml = xml[:m.start()] + "<w:sectPr>" + "</w:sectPr>" + xml[m.end():]
|
||||
m = list(re.finditer(r"<w:sectPr\b[^>]*?(/?)>", xml))[-1]
|
||||
close = xml.find("</w:sectPr>", m.end())
|
||||
inner = xml[m.end():close]
|
||||
if opts.paper:
|
||||
w, h = PAPER[opts.paper]
|
||||
inner = set_child(inner, "pgSz", '<w:pgSz w:w="%d" w:h="%d"/>' % (w, h), SECTPR_ORDER)
|
||||
if opts.margin_cm is not None:
|
||||
t = int(round(opts.margin_cm * 567))
|
||||
inner = set_child(inner, "pgMar", '<w:pgMar w:top="%d" w:right="%d" w:bottom="%d" w:left="%d" '
|
||||
'w:header="709" w:footer="709" w:gutter="0"/>' % (t, t, t, t), SECTPR_ORDER)
|
||||
return xml[:m.end()] + inner + xml[close:]
|
||||
|
||||
|
||||
def rewrite_zip(path, edits):
|
||||
"""edits: {member name: function(str) -> str}. Rewrites the zip in place."""
|
||||
tmp = Path(str(path) + ".tmp")
|
||||
with zipfile.ZipFile(path) as zin, zipfile.ZipFile(tmp, "w", zipfile.ZIP_DEFLATED) as zout:
|
||||
for info in zin.infolist():
|
||||
data = zin.read(info.filename)
|
||||
if info.filename in edits:
|
||||
data = edits[info.filename](data.decode("utf-8")).encode("utf-8")
|
||||
zout.writestr(info, data)
|
||||
tmp.replace(path)
|
||||
|
||||
|
||||
def style_settings_given(opts):
|
||||
return any(v is not None for v in (opts.body_font, opts.heading_font, opts.size,
|
||||
opts.heading_color, opts.paper, opts.margin_cm))
|
||||
|
||||
|
||||
def apply_settings(path, opts):
|
||||
notes = []
|
||||
with zipfile.ZipFile(path) as z:
|
||||
names = set(z.namelist())
|
||||
if "word/styles.xml" not in names or "word/document.xml" not in names:
|
||||
raise Refused("%s is not a Word document (no word/styles.xml)" % path)
|
||||
edits = {"word/styles.xml": lambda x: patch_styles(x, opts, notes)}
|
||||
if opts.paper or opts.margin_cm is not None:
|
||||
edits["word/document.xml"] = lambda x: patch_document(x, opts)
|
||||
if "word/theme/theme1.xml" in names and (opts.body_font or opts.heading_font):
|
||||
edits["word/theme/theme1.xml"] = lambda x: patch_theme(x, opts)
|
||||
rewrite_zip(path, edits)
|
||||
return notes
|
||||
|
||||
|
||||
def style_names(path):
|
||||
with zipfile.ZipFile(path) as z:
|
||||
xml = z.read("word/styles.xml").decode("utf-8")
|
||||
return {n.lower() for n in re.findall(r'<w:name w:val="([^"]*)"', xml)}
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- commands
|
||||
|
||||
def styles_dir(root):
|
||||
return Path(root) / STYLES_DIR
|
||||
|
||||
|
||||
def valid_name(name):
|
||||
if not re.match(r"^[a-z0-9][a-z0-9-]{0,60}$", name):
|
||||
raise Refused("style name %r: use lower-case letters, digits and hyphens" % name)
|
||||
return name
|
||||
|
||||
|
||||
def cmd_styles(args):
|
||||
d = styles_dir(args.root)
|
||||
found = {}
|
||||
for p in sorted(d.glob("*")) if d.is_dir() else []:
|
||||
if p.suffix.lower() in (".docx", ".odt", ".css"):
|
||||
found.setdefault(p.stem, []).append(p.suffix[1:].lower())
|
||||
if not found:
|
||||
print("no styles in %s" % STYLES_DIR.as_posix())
|
||||
return 0
|
||||
for name, kinds in found.items():
|
||||
flag = "" if "docx" in kinds else " (no .docx: docx and pdf use pandoc's default)"
|
||||
print("%-20s %s%s" % (name, ", ".join(kinds), flag))
|
||||
return 0
|
||||
|
||||
|
||||
def cmd_doctor(args):
|
||||
v = pandoc_version()
|
||||
lo = soffice()
|
||||
engines = [e for e in PDF_ENGINES if shutil.which(e)]
|
||||
print("pandoc: %s" % (".".join(map(str, v)) if v else "MISSING (required)"))
|
||||
print("libreoffice: %s" % (lo or "missing (PDF and ODT will not follow the Word style)"))
|
||||
if lo:
|
||||
print("pdf: via LibreOffice from the styled .docx")
|
||||
elif engines:
|
||||
print("pdf: via pandoc --pdf-engine=%s (Word style not applied)" % engines[0])
|
||||
else:
|
||||
print("pdf: unavailable (install LibreOffice)")
|
||||
print("styles: %s" % (", ".join(sorted(p.stem for p in styles_dir(args.root).glob("*.docx")))
|
||||
if styles_dir(args.root).is_dir() else "none") or "none")
|
||||
return 0 if v else 3
|
||||
|
||||
|
||||
def cmd_new_style(args):
|
||||
name = valid_name(args.name)
|
||||
d = styles_dir(args.root)
|
||||
dest = d / (name + ".docx")
|
||||
if dest.exists() and not args.force:
|
||||
raise Refused("%s exists; use edit-style to change it, or --force to replace it"
|
||||
% dest.relative_to(args.root).as_posix())
|
||||
d.mkdir(parents=True, exist_ok=True)
|
||||
if args.from_file:
|
||||
src = Path(args.from_file)
|
||||
if not src.is_file():
|
||||
raise Refused("no such file: %s" % src)
|
||||
ext = src.suffix.lower()
|
||||
if ext in (".docm", ".dotm"):
|
||||
raise Refused("%s holds macros; save it as .docx or .dotx (no macros) first" % src.name)
|
||||
if ext not in (".docx", ".dotx"):
|
||||
raise Refused("a style is made from a .docx or .dotx file, not %s" % ext)
|
||||
shutil.copyfile(src, dest)
|
||||
if ext == ".dotx":
|
||||
rewrite_zip(dest, {"[Content_Types].xml": lambda x: x.replace(DOTX_CT, DOCX_CT)})
|
||||
else:
|
||||
need_pandoc()
|
||||
with open(dest, "wb") as f:
|
||||
p = subprocess.run(["pandoc", "--print-default-data-file", "reference.docx"],
|
||||
stdout=f, stderr=subprocess.PIPE, timeout=60)
|
||||
if p.returncode != 0:
|
||||
dest.unlink()
|
||||
raise Missing("pandoc could not print its reference.docx: %s"
|
||||
% p.stderr.decode("utf-8", "replace").strip())
|
||||
notes = apply_settings(dest, args) if style_settings_given(args) else []
|
||||
print("written: %s" % dest.relative_to(args.root).as_posix())
|
||||
for n in notes:
|
||||
print("note: " + n)
|
||||
if args.from_file:
|
||||
report_missing(dest)
|
||||
return 0
|
||||
|
||||
|
||||
def cmd_edit_style(args):
|
||||
name = valid_name(args.name)
|
||||
dest = styles_dir(args.root) / (name + ".docx")
|
||||
if not dest.exists():
|
||||
raise Refused("no style %s; create it with new-style" % name)
|
||||
if not style_settings_given(args):
|
||||
raise Refused("nothing to change: give --body-font, --heading-font, --size, "
|
||||
"--heading-color, --paper or --margin-cm")
|
||||
notes = apply_settings(dest, args)
|
||||
print("updated: %s" % dest.relative_to(args.root).as_posix())
|
||||
for n in notes:
|
||||
print("note: " + n)
|
||||
return 0
|
||||
|
||||
|
||||
def report_missing(path):
|
||||
have = style_names(path)
|
||||
missing = [s for s in PANDOC_STYLES if s.lower() not in have]
|
||||
key = [s for s in missing if s in KEY_STYLES]
|
||||
if not missing:
|
||||
print("check: every style pandoc uses is defined")
|
||||
else:
|
||||
print("check: %d of %d styles pandoc uses are not defined; pandoc adds its own for them:"
|
||||
% (len(missing), len(PANDOC_STYLES)))
|
||||
print(" " + ", ".join(missing))
|
||||
if key:
|
||||
print(" important: " + ", ".join(key))
|
||||
return missing
|
||||
|
||||
|
||||
def cmd_check_style(args):
|
||||
path = styles_dir(args.root) / (valid_name(args.name) + ".docx")
|
||||
if not path.exists():
|
||||
raise Refused("no style %s" % args.name)
|
||||
report_missing(path)
|
||||
return 0
|
||||
|
||||
|
||||
def default_output(root, src, fmt, out_dir):
|
||||
root = Path(root).resolve()
|
||||
src = Path(src).resolve()
|
||||
if out_dir:
|
||||
d = Path(out_dir)
|
||||
d = d if d.is_absolute() else root / d
|
||||
else:
|
||||
try:
|
||||
rel = src.relative_to(root)
|
||||
d = src.parent if rel.parts[:1] == ("outputs",) else root / DEFAULT_OUT_DIR
|
||||
except ValueError:
|
||||
d = root / DEFAULT_OUT_DIR
|
||||
return d / (src.stem + "." + fmt)
|
||||
|
||||
|
||||
def cmd_convert(args):
|
||||
version = need_pandoc()
|
||||
root = Path(args.root).resolve()
|
||||
src = Path(args.file)
|
||||
if not src.is_absolute():
|
||||
src = (Path.cwd() / src).resolve()
|
||||
if not src.is_file():
|
||||
raise Refused("no such file: %s" % args.file)
|
||||
fmt = args.to
|
||||
out = Path(args.out) if args.out else default_output(root, src, fmt, args.out_dir)
|
||||
if not out.is_absolute():
|
||||
out = root / out
|
||||
if out.suffix.lower() != "." + fmt:
|
||||
raise Refused("--out %s does not end in .%s" % (out.name, fmt))
|
||||
if out.exists() and not args.force:
|
||||
raise Refused("exists: %s (--force replaces it, --out writes elsewhere)" % rel(out, root))
|
||||
name = valid_name(args.style)
|
||||
sdir = styles_dir(root)
|
||||
ref_docx = sdir / (name + ".docx")
|
||||
notes = []
|
||||
if not ref_docx.exists():
|
||||
if args.style_required:
|
||||
raise Refused("no style %s in %s" % (name, STYLES_DIR.as_posix()))
|
||||
notes.append("no style %s: used pandoc's default look" % name)
|
||||
ref_docx = None
|
||||
|
||||
meta, body = prepare(src.read_text(encoding="utf-8-sig"), args.keep_links)
|
||||
lo = soffice()
|
||||
with tempfile.TemporaryDirectory(prefix="ckb-convert-") as tmp:
|
||||
tmpd = Path(tmp)
|
||||
md = tmpd / (src.stem + ".md")
|
||||
md.write_text(body, encoding="utf-8")
|
||||
metaf = tmpd / "meta.json"
|
||||
metaf.write_text(json.dumps(meta, ensure_ascii=False), encoding="utf-8")
|
||||
base = ["pandoc", str(md), "-f", "markdown-yaml_metadata_block+autolink_bare_uris",
|
||||
"--metadata-file", str(metaf),
|
||||
"--resource-path", "%s%s%s" % (src.parent, ";" if sys.platform == "win32" else ":", root)]
|
||||
if "title" not in meta:
|
||||
base += ["--metadata", "pagetitle=" + src.stem]
|
||||
if args.toc:
|
||||
base.append("--toc")
|
||||
if args.number_sections:
|
||||
base.append("--number-sections")
|
||||
|
||||
def docx_to(path):
|
||||
cmd = base + ["-t", "docx", "-o", str(path)]
|
||||
if ref_docx:
|
||||
cmd += ["--reference-doc", str(ref_docx)]
|
||||
return run(cmd)
|
||||
|
||||
via = "pandoc"
|
||||
produced = tmpd / ("out." + fmt)
|
||||
if fmt == "docx":
|
||||
p = docx_to(produced)
|
||||
elif fmt == "html":
|
||||
css = sdir / (name + ".css")
|
||||
cmd = base + ["-t", "html5", "--standalone", "-o", str(produced),
|
||||
"--embed-resources" if version >= (2, 19) else "--self-contained"]
|
||||
if css.exists():
|
||||
cmd += ["--css", str(css)]
|
||||
else:
|
||||
notes.append("no %s.css: html uses pandoc's default look" % name)
|
||||
p = run(cmd)
|
||||
elif fmt == "odt":
|
||||
ref_odt = sdir / (name + ".odt")
|
||||
if ref_odt.exists():
|
||||
p = run(base + ["-t", "odt", "-o", str(produced), "--reference-doc", str(ref_odt)])
|
||||
elif lo and ref_docx:
|
||||
p = docx_to(tmpd / (src.stem + ".docx"))
|
||||
produced = soffice_convert(lo, tmpd / (src.stem + ".docx"), "odt", tmpd)
|
||||
via = "pandoc + LibreOffice"
|
||||
else:
|
||||
p = run(base + ["-t", "odt", "-o", str(produced)])
|
||||
notes.append("odt uses pandoc's default look (no %s.odt%s)"
|
||||
% (name, "" if lo else ", no LibreOffice"))
|
||||
else: # pdf
|
||||
if lo:
|
||||
p = docx_to(tmpd / (src.stem + ".docx"))
|
||||
produced = soffice_convert(lo, tmpd / (src.stem + ".docx"), "pdf", tmpd)
|
||||
via = "pandoc + LibreOffice"
|
||||
else:
|
||||
engine = next((e for e in PDF_ENGINES if shutil.which(e)), None)
|
||||
if not engine:
|
||||
raise Missing("PDF needs LibreOffice (keeps the Word style) or a pandoc PDF "
|
||||
"engine (%s); none found" % ", ".join(PDF_ENGINES))
|
||||
p = run(base + ["-o", str(produced), "--pdf-engine=" + engine])
|
||||
via = "pandoc --pdf-engine=" + engine
|
||||
notes.append("no LibreOffice: the PDF does not follow the Word style")
|
||||
out.parent.mkdir(parents=True, exist_ok=True)
|
||||
shutil.copyfile(produced, out)
|
||||
for line in (p.stderr or "").splitlines():
|
||||
if line.strip():
|
||||
notes.append("pandoc: " + line.strip())
|
||||
print("written: %s" % rel(out, root))
|
||||
print("format: %s via %s, style: %s" % (fmt, via, name if ref_docx else "pandoc default"))
|
||||
if meta.get("title"):
|
||||
print("title: %s" % meta["title"])
|
||||
for n in notes:
|
||||
print("note: " + n)
|
||||
return 0
|
||||
|
||||
|
||||
def rel(path, root):
|
||||
try:
|
||||
return Path(path).resolve().relative_to(Path(root).resolve()).as_posix()
|
||||
except ValueError:
|
||||
return str(path)
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------- CLI
|
||||
|
||||
def hex_color(v):
|
||||
v = v.lstrip("#").upper()
|
||||
if not re.match(r"^[0-9A-F]{6}$", v):
|
||||
raise argparse.ArgumentTypeError("colour must be six hex digits, e.g. 1F3864")
|
||||
return v
|
||||
|
||||
|
||||
def style_options(p):
|
||||
p.add_argument("--body-font")
|
||||
p.add_argument("--heading-font")
|
||||
p.add_argument("--size", type=float, help="body text size in points")
|
||||
p.add_argument("--heading-color", type=hex_color, help="RRGGBB")
|
||||
p.add_argument("--paper", choices=sorted(PAPER))
|
||||
p.add_argument("--margin-cm", type=float)
|
||||
|
||||
|
||||
def main(argv=None):
|
||||
for stream in (sys.stdout, sys.stderr):
|
||||
if hasattr(stream, "reconfigure"):
|
||||
stream.reconfigure(encoding="utf-8", errors="replace")
|
||||
ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
|
||||
ap.add_argument("--root", default=".")
|
||||
sub = ap.add_subparsers(dest="cmd")
|
||||
sub.required = True
|
||||
|
||||
c = sub.add_parser("convert")
|
||||
c.add_argument("file")
|
||||
c.add_argument("--to", choices=FORMATS, default="docx")
|
||||
c.add_argument("--style", default="house")
|
||||
c.add_argument("--style-required", action="store_true",
|
||||
help="refuse instead of falling back to pandoc's default when the style is missing")
|
||||
c.add_argument("--out")
|
||||
c.add_argument("--out-dir")
|
||||
c.add_argument("--toc", action="store_true")
|
||||
c.add_argument("--number-sections", action="store_true")
|
||||
c.add_argument("--keep-links", action="store_true")
|
||||
c.add_argument("--force", action="store_true")
|
||||
c.set_defaults(fn=cmd_convert)
|
||||
|
||||
n = sub.add_parser("new-style")
|
||||
n.add_argument("name")
|
||||
n.add_argument("--from", dest="from_file")
|
||||
n.add_argument("--force", action="store_true")
|
||||
style_options(n)
|
||||
n.set_defaults(fn=cmd_new_style)
|
||||
|
||||
e = sub.add_parser("edit-style")
|
||||
e.add_argument("name")
|
||||
style_options(e)
|
||||
e.set_defaults(fn=cmd_edit_style)
|
||||
|
||||
k = sub.add_parser("check-style")
|
||||
k.add_argument("name")
|
||||
k.set_defaults(fn=cmd_check_style)
|
||||
|
||||
sub.add_parser("styles").set_defaults(fn=cmd_styles)
|
||||
sub.add_parser("doctor").set_defaults(fn=cmd_doctor)
|
||||
|
||||
args = ap.parse_args(argv)
|
||||
args.root = str(Path(args.root).resolve())
|
||||
try:
|
||||
return args.fn(args)
|
||||
except Refused as e:
|
||||
print("refused: %s" % e, file=sys.stderr)
|
||||
return 1
|
||||
except Missing as e:
|
||||
print("error: %s" % e, file=sys.stderr)
|
||||
return 3
|
||||
except zipfile.BadZipFile as e:
|
||||
print("refused: not a valid Office file (%s)" % e, file=sys.stderr)
|
||||
return 1
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
|
|
@ -1,69 +0,0 @@
|
|||
# `voice` module
|
||||
|
||||
*Read this in: **English** | [Polski](README.pl.md)*
|
||||
|
||||
Opt-in. Install with "install the voice module"; remove with "uninstall the
|
||||
voice module". Nothing in here is active until installed.
|
||||
|
||||
## What it does
|
||||
|
||||
Answers, documents and reports the KB writes for people outside it tend to
|
||||
read like a model wrote them. This module rewrites them in **your voice**
|
||||
before they're saved. The voice is a wiki page, `wiki/voice/<name>.md`, so
|
||||
the team can read it, review it and correct it like any other knowledge.
|
||||
|
||||
| Skill | Does |
|
||||
|---|---|
|
||||
| `ckb-voice` | Rewrites outgoing text in a voice profile, builds a profile from sample documents, records "we never say X" as it comes up, and changes the settings. |
|
||||
|
||||
Once installed, nothing changes until the first profile exists. Say
|
||||
"calibrate our writing style" and give it a few documents that sound right.
|
||||
From then on, every new file in `outputs/answers/`, `outputs/documents/`,
|
||||
`outputs/reports/` and the project overview is written in that voice.
|
||||
|
||||
## What changes and what doesn't
|
||||
|
||||
The voice changes **wording**: banned AI vocabulary, formulaic structure,
|
||||
hedging, flat rhythm, and the tone, formality and phrases your profile sets.
|
||||
|
||||
It never changes **content**. Frontmatter, `## Sources`, `## Crux` and every
|
||||
quote, `## Notes`, contradiction markers, code, paths, links, numbers and
|
||||
names come out exactly as they went in. A rewrite that would alter one of
|
||||
them is rejected. A vague claim isn't cut, it's flagged for you. Wiki pages
|
||||
are never rewritten; the wiki stays plain.
|
||||
|
||||
## Settings
|
||||
|
||||
In `ckb.yaml`, under the module's entry. Change them by asking ("set the
|
||||
voice mode to ask", "make board the default voice"):
|
||||
|
||||
```yaml
|
||||
config:
|
||||
mode: auto # auto | ask (once per file) | off
|
||||
profile: house # the default voice, wiki/voice/house.md
|
||||
writer: ckb-voice # or another rewriting skill you have, e.g. ghost-writer
|
||||
apply_to: [outputs/answers/, outputs/documents/, outputs/reports/, PROJECT-OVERVIEW]
|
||||
skip: [outputs/okf/, outputs/starlight/]
|
||||
chat: false # true = chat answers too
|
||||
```
|
||||
|
||||
Which voice is used: one named in the request ("in the board voice"), else
|
||||
the `voice:` set in your own `workload/profiles/` page ("use my own voice by
|
||||
default"), else `profile`.
|
||||
|
||||
## Using your own rewriting skill
|
||||
|
||||
If you already have a rewriting skill you like, such as a personal
|
||||
`ghost-writer` in `~/.claude/skills/`, set `writer: ghost-writer`. The
|
||||
module still picks the profile from the wiki and still guards the frozen
|
||||
parts; your skill does the rewriting. If the skill isn't installed on a
|
||||
teammate's machine, their sessions fall back to `ckb-voice`.
|
||||
|
||||
## Safety
|
||||
|
||||
- **Profiles are committed.** Everyone who clones the KB sees them. Keep
|
||||
samples to text you'd share with the team.
|
||||
- **Third-party voices** ("write like Feynman") are built from published
|
||||
text and keep only a few lines as a sample.
|
||||
- **Uninstalling keeps the profiles.** `wiki/voice/` stays as knowledge;
|
||||
only the automatic rewrite stops.
|
||||
|
|
@ -1,73 +0,0 @@
|
|||
# Moduł `voice`
|
||||
|
||||
*Przeczytaj w: [English](README.md) | **Polski***
|
||||
|
||||
Opcjonalny. Instalacja: „install the voice module”, usunięcie: „uninstall
|
||||
the voice module”. Dopóki nie jest zainstalowany, nic z tego folderu nie
|
||||
działa.
|
||||
|
||||
## Co robi
|
||||
|
||||
Odpowiedzi, dokumenty i raporty, które baza pisze dla ludzi spoza niej,
|
||||
często brzmią jak tekst z modelu. Ten moduł przepisuje je **Waszym głosem**,
|
||||
zanim zostaną zapisane. Głos to strona wiki, `wiki/voice/<nazwa>.md`, więc
|
||||
zespół może go przeczytać, przejrzeć i poprawić jak każdą inną wiedzę.
|
||||
|
||||
| Skill | Co robi |
|
||||
|---|---|
|
||||
| `ckb-voice` | Przepisuje wychodzący tekst według profilu głosu, buduje profil z przykładowych dokumentów, zapisuje uwagi w rodzaju „nigdy nie piszemy X”, gdy padną, i zmienia ustawienia. |
|
||||
|
||||
Po instalacji nic się nie zmienia, dopóki nie powstanie pierwszy profil.
|
||||
Powiedz „calibrate our writing style” i podaj kilka dokumentów, które brzmią
|
||||
dobrze. Od tej chwili każdy nowy plik w `outputs/answers/`,
|
||||
`outputs/documents/`, `outputs/reports/` i przegląd projektu powstaje tym
|
||||
głosem.
|
||||
|
||||
## Co się zmienia, a co nie
|
||||
|
||||
Głos zmienia **sformułowania**: typowe dla AI słownictwo, schematyczną
|
||||
budowę, asekuranckie zwroty, płaski rytm, a także ton, formalność i
|
||||
zwroty, które ustala profil.
|
||||
|
||||
Nigdy nie zmienia **treści**. Frontmatter, `## Sources`, `## Crux` i każdy
|
||||
cytat, `## Notes`, znaczniki sprzeczności, kod, ścieżki, linki, liczby i
|
||||
nazwy wychodzą dokładnie takie, jakie weszły. Przepisanie, które zmieniłoby
|
||||
którekolwiek z nich, jest odrzucane. Ogólnikowe twierdzenie nie jest
|
||||
wycinane, tylko zgłaszane Tobie. Strony wiki nigdy nie są przepisywane;
|
||||
wiki zostaje zwykła.
|
||||
|
||||
## Ustawienia
|
||||
|
||||
W `ckb.yaml`, we wpisie modułu. Zmieniasz je prośbą („set the voice mode to
|
||||
ask”, „make board the default voice”):
|
||||
|
||||
```yaml
|
||||
config:
|
||||
mode: auto # auto | ask (raz na plik) | off
|
||||
profile: house # domyślny głos, wiki/voice/house.md
|
||||
writer: ckb-voice # albo inny Twój skill do przepisywania, np. ghost-writer
|
||||
apply_to: [outputs/answers/, outputs/documents/, outputs/reports/, PROJECT-OVERVIEW]
|
||||
skip: [outputs/okf/, outputs/starlight/]
|
||||
chat: false # true = także odpowiedzi w czacie
|
||||
```
|
||||
|
||||
Który głos: nazwany w prośbie („in the board voice”), inaczej `voice:` z
|
||||
Twojej strony w `workload/profiles/` („use my own voice by default”),
|
||||
inaczej `profile`.
|
||||
|
||||
## Własny skill do przepisywania
|
||||
|
||||
Jeśli masz już skill, który lubisz, np. osobisty `ghost-writer` w
|
||||
`~/.claude/skills/`, ustaw `writer: ghost-writer`. Moduł nadal bierze profil
|
||||
z wiki i nadal pilnuje zamrożonych części; przepisuje Twój skill. Jeśli na
|
||||
komputerze kogoś z zespołu tego skilla nie ma, jego sesje wracają do
|
||||
`ckb-voice`.
|
||||
|
||||
## Bezpieczeństwo
|
||||
|
||||
- **Profile są commitowane.** Widzi je każdy, kto sklonuje bazę. Jako
|
||||
próbki dawaj tylko tekst, którym podzielił(a)byś się z zespołem.
|
||||
- **Głosy osób trzecich** („pisz jak Feynman”) powstają z opublikowanych
|
||||
tekstów, a jako próbka zostaje najwyżej kilka linijek.
|
||||
- **Odinstalowanie zostawia profile.** `wiki/voice/` zostaje jako wiedza;
|
||||
ustaje tylko automatyczne przepisywanie.
|
||||
|
|
@ -1,20 +0,0 @@
|
|||
## MODULE: voice
|
||||
|
||||
Text this KB sends out is written in a voice whose profile is a wiki page,
|
||||
`wiki/voice/<name>.md` (`type: voice-profile`). Settings are under the
|
||||
`voice` entry of `kb_modules:` in `ckb.yaml`.
|
||||
|
||||
- **Before writing a prose file** to a path under `apply_to` and not under
|
||||
`skip`, pass the draft through `ckb-voice`, whatever skill produced it.
|
||||
`mode: ask` asks once per file; `mode: off`, or no profile page yet, writes
|
||||
the draft unchanged. `chat: true` does the same for answers in the chat.
|
||||
- **The voice changes wording, never content.** Frontmatter, `## Sources`,
|
||||
`## Crux` and every quote, `## Notes`, `> CONTRADICTION:` markers, code,
|
||||
paths, links, numbers, names and a template's headings stay byte-for-byte.
|
||||
- Which profile: one named in the request, else the `voice:` field of the
|
||||
person's `workload/profiles/` page, else `profile` in `ckb.yaml`.
|
||||
- `wiki/` pages are never rewritten into a voice; the wiki stays plain.
|
||||
|
||||
| User intent | Skill |
|
||||
|---|---|
|
||||
| Rewrite text in a voice, create or update a voice profile, change the voice settings | `ckb-voice` |
|
||||
|
|
@ -1 +0,0 @@
|
|||
# voice module: nothing extra to ignore (profiles are tracked in wiki/voice/).
|
||||
|
|
@ -1,45 +0,0 @@
|
|||
# Cascade KB module manifest — read by `ckb-module` on install/uninstall.
|
||||
# See docs/decisions/0020-voice-module.md.
|
||||
name: voice
|
||||
title: Voice for outgoing text
|
||||
version: 1.0.0
|
||||
requires_kb_schema: "1.7"
|
||||
summary: >
|
||||
Rewrites every text the KB sends out (kept answers, documents, reports, the
|
||||
project overview) in a writing voice whose profile is a page in
|
||||
wiki/voice/, so it reads like the team and not like a model. Facts, quotes,
|
||||
sources and code are never touched.
|
||||
|
||||
skills:
|
||||
- ckb-voice
|
||||
|
||||
# No scaffold: wiki/voice/ is created, and logged, by ckb-voice when the first
|
||||
# profile is written. A module install never writes wiki pages.
|
||||
|
||||
agents_fragment: fragments/agents-routing.md
|
||||
gitignore_fragment: fragments/gitignore.snippet
|
||||
|
||||
# Default settings, written under this module's `config:` in ckb.yaml on
|
||||
# install. ckb-voice owns them afterwards ("set the voice mode to ask").
|
||||
default_config:
|
||||
mode: auto # auto | ask | off
|
||||
profile: house # wiki/voice/<profile>.md used when nothing else names one
|
||||
writer: ckb-voice # or the name of another rewriting skill, e.g. ghost-writer
|
||||
apply_to: # path prefixes whose prose files go through the voice
|
||||
- outputs/answers/
|
||||
- outputs/documents/
|
||||
- outputs/reports/
|
||||
- PROJECT-OVERVIEW
|
||||
skip: # never rewritten, even under an apply_to prefix
|
||||
- outputs/okf/
|
||||
- outputs/starlight/
|
||||
chat: false # true = also rewrite answers given in the chat
|
||||
|
||||
schema_additions:
|
||||
types:
|
||||
- voice-profile # wiki/voice/<name>.md: a writing voice, maintained by ckb-voice
|
||||
fields:
|
||||
- voice # on an output file: the profile it was written in
|
||||
# on a person's workload/profiles/ page: their default voice
|
||||
|
||||
depends_on: []
|
||||
|
|
@ -1,238 +0,0 @@
|
|||
---
|
||||
name: ckb-voice
|
||||
description: Rewrite text the KB sends out (kept answers, documents, reports, the project overview) in a writing voice whose profile lives in wiki/voice/, and maintain those profiles and the voice settings. Runs before any prose file is written under the configured outputs paths, whichever skill drafted it. Use for "rewrite this in our voice", "use the <name> voice", "make this sound less AI", "humanize this", "calibrate our writing style", "create a voice profile", "update the house voice", "list voices", "set the voice mode to ask", "turn the voice off", "use my own voice by default".
|
||||
---
|
||||
|
||||
# Voice skill
|
||||
|
||||
## Purpose
|
||||
|
||||
Everything this KB hands to people outside it should read like the team
|
||||
wrote it, not like a model did. The rules for *how* to write are generic and
|
||||
ship here; the voice itself (tone, formality, words to keep and avoid,
|
||||
samples) is knowledge the team owns, so it is a wiki page anyone can review
|
||||
and correct: `wiki/voice/<name>.md`.
|
||||
|
||||
Two jobs:
|
||||
|
||||
1. **Apply** a voice to a draft before it leaves the KB (Steps 1–5).
|
||||
2. **Maintain** profiles and settings (the sections after Step 5).
|
||||
|
||||
## Settings
|
||||
|
||||
Under the `voice` entry of `kb_modules:` in `ckb.yaml`, written by
|
||||
`ckb-module` on install from the manifest's `default_config`:
|
||||
|
||||
```yaml
|
||||
kb_modules:
|
||||
- name: voice
|
||||
version: 1.0.0
|
||||
installed_on: YYYY-MM-DD
|
||||
config:
|
||||
mode: auto # auto | ask | off
|
||||
profile: house # default profile, wiki/voice/house.md
|
||||
writer: ckb-voice # or another installed rewriting skill
|
||||
apply_to: [outputs/answers/, outputs/documents/, outputs/reports/, PROJECT-OVERVIEW]
|
||||
skip: [outputs/okf/, outputs/starlight/]
|
||||
chat: false
|
||||
```
|
||||
|
||||
A path is in scope when it starts with an `apply_to` prefix and with no
|
||||
`skip` prefix. Only prose files are rewritten: Markdown and plain text.
|
||||
Generated data (`.json`, `.ics`, `.yaml`, `.csv`) never is, even in scope.
|
||||
`workload/`, `raw/`, `templates/` and `wiki/` are never in scope, whatever
|
||||
the settings say.
|
||||
|
||||
## Step 1 — Decide whether to run
|
||||
|
||||
Run when either is true:
|
||||
|
||||
- another skill is about to write a file whose path is in scope (the
|
||||
`AGENTS.md` module block sends it here), or the chat answer is about to
|
||||
go out and `chat: true`;
|
||||
- the user asks directly ("rewrite this in our voice", "use the Feynman
|
||||
voice", "make this less AI") — then scope and `mode` don't matter.
|
||||
|
||||
Then by `mode`:
|
||||
|
||||
- `off` → write the draft unchanged. Say nothing.
|
||||
- `ask` → ask once per file: "Write `<path>` in the `<profile>` voice?" A no
|
||||
writes the draft unchanged.
|
||||
- `auto` → continue.
|
||||
|
||||
## Step 2 — Resolve the profile
|
||||
|
||||
First match wins:
|
||||
|
||||
1. a profile named in the request ("in the Feynman voice", "use the board
|
||||
voice");
|
||||
2. `voice:` in the frontmatter of the session person's
|
||||
`workload/profiles/<author-slug>.md`;
|
||||
3. `profile` in the settings.
|
||||
|
||||
Read `wiki/voice/<name>.md`. If it doesn't exist:
|
||||
|
||||
- On an automatic run, write the draft unchanged and say once per session:
|
||||
"(No `<name>` voice profile yet, so `<path>` went out as drafted. Say
|
||||
'calibrate the <name> voice' to create one.)"
|
||||
- On a direct request, list `wiki/voice/index.md` and ask which to use, or
|
||||
offer to calibrate one.
|
||||
|
||||
A profile with `review: needs_update` is still used; mention it once.
|
||||
A profile marked `superseded_by` is replaced by its successor.
|
||||
|
||||
Say which voice you used in one line, e.g. "(Written in the `house` voice.)"
|
||||
Never mix two profiles in one text.
|
||||
|
||||
## Step 3 — Freeze what must not change
|
||||
|
||||
Before touching anything, mark these spans as frozen. They come out
|
||||
byte-for-byte as they went in:
|
||||
|
||||
- frontmatter, then add or update only `voice: <name>` in it;
|
||||
- `## Sources`, `## Crux` and every blockquote, and each attribution line
|
||||
(`— \`path\`, under "X"`), em-dash included;
|
||||
- `## Notes` and `## Rules`;
|
||||
- `> CONTRADICTION:` markers and `<private>` spans;
|
||||
- code blocks, inline code, file paths, URLs, links and `[[wikilinks]]`;
|
||||
- numbers, dates, amounts, names of people, products and organisations;
|
||||
- tables of data (cell wording may be tidied, values never);
|
||||
- in a `ckb-document` output, the template's headings and their order.
|
||||
|
||||
If the voice would need a frozen span changed (a quote that breaks the
|
||||
rhythm, a heading in the wrong register), leave it and move on.
|
||||
|
||||
## Step 4 — Rewrite the rest
|
||||
|
||||
If `writer` names another skill (for example a personal `ghost-writer`
|
||||
installed in the user's home directory), load it and let it do the
|
||||
rewrite. Pass it the profile page as its style profile and the frozen spans
|
||||
from Step 3 as text it must not change. Then check its output against
|
||||
Step 5. If it isn't available, say so once and fall back to `ckb-voice`.
|
||||
|
||||
Otherwise apply [`references/rules.md`](references/rules.md), with the
|
||||
profile overriding its defaults:
|
||||
|
||||
- **Tone**, **Formality** and **Sentence style** replace the rules' defaults
|
||||
(an em-dash rate set there overrides the rules' dash advice).
|
||||
- **Keep** words survive even if the rules ban them; **Avoid** words are added
|
||||
to the ban list.
|
||||
- **Sample** paragraphs are the voice reference: match their rhythm, not
|
||||
their content.
|
||||
- **Audience** and **Opinions** set how much to explain and how hard to land
|
||||
a point.
|
||||
|
||||
A rewrite changes wording, order inside a paragraph and paragraph breaks.
|
||||
It never adds a claim, a number or an example that wasn't in the draft, and
|
||||
never drops one. A vague claim the rules would cut is kept and listed in the
|
||||
change note instead. In a KB its source may say more, and that is the
|
||||
author's call, not the voice's.
|
||||
|
||||
For a long text (about 1,500 words or more), also read
|
||||
[`references/ai-signs.md`](references/ai-signs.md) and
|
||||
[`references/good-writing.md`](references/good-writing.md).
|
||||
|
||||
## Step 5 — Check, then write
|
||||
|
||||
Compare the rewrite with the draft before writing it:
|
||||
|
||||
- every frozen span is identical (diff them, don't eyeball them);
|
||||
- every number, name, path and link in the draft is still there;
|
||||
- the headings are the same (a `ckb-document` output) or no fewer
|
||||
(anything else).
|
||||
|
||||
A failed check means the rewrite is wrong: fix it, or write the draft
|
||||
unchanged and say why. Then write the file and add one line to the reply:
|
||||
"Voice: `<name>`. Main change: <the dominant pattern fixed>." On a direct
|
||||
request with no file, return the text and the same line.
|
||||
|
||||
The written file is the calling skill's output. Its log and workload entries
|
||||
are that skill's, and this skill adds none.
|
||||
|
||||
## Maintaining profiles
|
||||
|
||||
### A profile page
|
||||
|
||||
`wiki/voice/<name>.md`, one per voice. The name is a lower-case slug
|
||||
(`house`, `board`, `michal-kopec`, `feynman`). Write it from
|
||||
[`references/profile-template.md`](references/profile-template.md):
|
||||
|
||||
```yaml
|
||||
---
|
||||
type: voice-profile
|
||||
tldr: <who this voice is for and what it sounds like, one sentence>
|
||||
voice_of: team | person | third-party # whose voice it is
|
||||
last_updated: YYYY-MM-DD
|
||||
retention: high
|
||||
review: draft
|
||||
---
|
||||
```
|
||||
|
||||
The body has the sections in the template: Tone, Formality, Sentence style,
|
||||
Keep, Avoid, Audience, Opinions, Sample, then the reserved `## Sources`
|
||||
(documents the voice was calibrated from, fingerprinted as `AGENTS.md` §2
|
||||
says) and `## Notes` (protected).
|
||||
|
||||
`wiki/voice/index.md` lists every profile with its `tldr`, and
|
||||
`wiki/index.md` routes to it. Create both with the first profile. Every
|
||||
create or change under `wiki/voice/` is logged in `wiki/log.md` (Rule B)
|
||||
before going further.
|
||||
|
||||
A profile is knowledge about how to write. It is not evidence for any other
|
||||
claim, and `ckb-retrieve` should not ground a factual answer on it.
|
||||
|
||||
### Calibrate ("calibrate our writing style", "create a voice profile for X")
|
||||
|
||||
Run [`references/calibration.md`](references/calibration.md). It asks for
|
||||
sample documents first and then at most four short questions, one at a time,
|
||||
and writes the page with `review: draft`. Sample documents the user points
|
||||
to inside the KB (`raw/archive/`, `outputs/`) are cited in `## Sources`.
|
||||
Files from elsewhere go to `raw/inbox/` first, and only on a yes, so they
|
||||
can be fingerprinted. A third-party voice (a writer, a public figure) is
|
||||
built from published text and marked `voice_of: third-party`; its Sample
|
||||
holds a few lines at most, never whole passages.
|
||||
|
||||
### Update one thing ("we never say 'leverage'", "the board voice is more formal")
|
||||
|
||||
A standing preference, said during any work, goes to the profile in use:
|
||||
change only the field it touches, set `last_updated`, set `review:
|
||||
needs_update` on a `reviewed` page, log it, and confirm in one line. "Make
|
||||
*this one* more formal" is a one-off. Apply it and don't save it. If it's
|
||||
unclear which, ask: "Keep that for future texts, or just this one?"
|
||||
|
||||
Never write a preference learned for one profile into another.
|
||||
|
||||
### Personal default ("use my own voice by default")
|
||||
|
||||
Write `voice: <name>` into the frontmatter of the person's
|
||||
`workload/profiles/<author-slug>.md`, creating the profile through
|
||||
`ckb-profile` if it doesn't exist. It changes their sessions only.
|
||||
|
||||
### List ("list voices", "what voices do we have")
|
||||
|
||||
Show `wiki/voice/index.md`: name, `voice_of`, `tldr`, review state, and mark
|
||||
the default and the current person's choice.
|
||||
|
||||
### Retire
|
||||
|
||||
Never delete a profile on a request to change it. A replaced voice gets
|
||||
`superseded_by`, and its successor gets `supersedes`. Delete only on an
|
||||
explicit "delete the X voice", logged.
|
||||
|
||||
## Changing the settings
|
||||
|
||||
"Set the voice mode to ask", "turn the voice off", "make board the default
|
||||
voice", "also apply the voice to outputs/teaching/", "rewrite chat answers
|
||||
too". Edit only the `config:` of the `voice` entry in `ckb.yaml`, keeping
|
||||
everything else in the file intact, and confirm the new value in one line.
|
||||
Refuse an `apply_to` under `wiki/`, `raw/`, `workload/` or `templates/` and
|
||||
say why: the wiki stays plain, raw material and workload notes are records,
|
||||
and templates are the user's.
|
||||
|
||||
## What this skill does not do
|
||||
|
||||
- It does not check facts or add knowledge. Content goes out as the
|
||||
calling skill drafted it.
|
||||
- It does not rewrite wiki pages, quotes or code.
|
||||
- It does not change the language (English/Polish, British/American) unless
|
||||
the profile or the request says so.
|
||||
|
|
@ -1,139 +0,0 @@
|
|||
# AI Writing Signs — Detection Checklist
|
||||
|
||||
Reference for the `ckb-voice` skill (adapted from a personal ghost-writer skill). Scan input text against these patterns before rewriting.
|
||||
|
||||
---
|
||||
|
||||
## Category A: Surface-Level Tells (Easy to Spot)
|
||||
|
||||
### 1. Em Dash Overuse
|
||||
**Signal:** More than 3 em dashes per 500 words
|
||||
**Fix:** Replace with period, comma, or restructure the sentence
|
||||
|
||||
### 2. Banned Vocabulary
|
||||
**Signal:** Any cluster of these words: *delve, showcase, underscores, noteworthy, pivotal, realm, tapestry, beacon, multifaceted, commendable, meticulous, intricate, vibrant, bolstered, fostering, highlighting, crucial, emphasizing, enhance, align with*
|
||||
**Fix:** Replace with plain, direct language. "Shows" not "showcases." "Important" not "pivotal."
|
||||
|
||||
### 3. Perfect Grammar, Zero Personality
|
||||
**Signal:** No fragments, no deliberate rule-bending, no contractions, no personality
|
||||
**Fix:** Add a fragment. Use a contraction. Let a short sentence stand alone. Like this.
|
||||
|
||||
### 4. Formulaic Paragraph Structure
|
||||
**Signal:** Every paragraph follows: topic sentence → evidence → summary
|
||||
**Fix:** Vary openings. Start a paragraph with a question, an example, or a one-sentence punch.
|
||||
|
||||
### 5. Excessive Hedging
|
||||
**Signal:** High density of: *arguably, potentially, it's worth noting, it could be said, in many ways, some might argue, one could suggest*
|
||||
**Fix:** If the author means it, say it. Cut the hedge or restructure to a genuine conditional.
|
||||
|
||||
### 6. Meta-Commentary and Structural Narration
|
||||
**Signal:** "In this article, we will explore…" / "As we can see…" / "In conclusion, we have discussed…"
|
||||
**Fix:** Delete sentences that describe the document instead of saying the thing.
|
||||
|
||||
### 7. Identical Sentence Length
|
||||
**Signal:** Every sentence runs 15–20 words with no variation
|
||||
**Fix:** Vary aggressively. Mix a 4-word sentence with a 30-word one.
|
||||
|
||||
### 8. Transition Word Saturation
|
||||
**Signal:** High frequency of: *furthermore, moreover, additionally, consequently, thus, hence, in addition, it is important to note*
|
||||
**Fix:** Remove or replace with direct connectives ("but," "so," "and") or restructure without them.
|
||||
|
||||
### 9. The Rule of Three — Always
|
||||
**Signal:** Every list has exactly three items; every comparison hits three points
|
||||
**Fix:** Use two sometimes. Use four sometimes. Break the pattern intentionally.
|
||||
|
||||
### 10. Overuse of "-ing" Openers
|
||||
**Signal:** Multiple sentences per paragraph starting with an -ing phrase ("Offering a wide range…", "Giving users the ability…")
|
||||
**Fix:** Restructure to lead with the subject.
|
||||
|
||||
---
|
||||
|
||||
## Category B: Deep Patterns (Harder to Spot, More Damaging)
|
||||
|
||||
### 11. The Abstraction Trap ⚠️ HIGH PRIORITY
|
||||
**Signal:** Vague language where concrete details belong. "The experience was positive" instead of "Cut setup time from 3 days to 4 hours."
|
||||
**Fix:** For every abstract claim, add one specific detail, number, or named example.
|
||||
|
||||
### 12. The Treadmill Effect
|
||||
**Signal:** Text circles the same idea across multiple paragraphs without advancing the information
|
||||
**Fix:** Cut restatements ruthlessly. If the same idea appears twice, keep the best version, delete the rest.
|
||||
|
||||
### 13. Latinate Bias ⚠️ HIGH PRIORITY
|
||||
**Signal:** Preference for long, formal Latinate words over short Anglo-Saxon ones:
|
||||
- "utilize" → "use"
|
||||
- "facilitate" → "help"
|
||||
- "commence" → "start"
|
||||
- "demonstrate" → "show"
|
||||
- "approximately" → "about"
|
||||
- "endeavor" → "try"
|
||||
- "in order to" → "to"
|
||||
- "due to the fact that" → "because"
|
||||
**Fix:** Audit every 3+ syllable word. Is there a shorter one? Use it.
|
||||
|
||||
### 14. Sensing Without Sensing
|
||||
**Signal:** Sensory descriptions that feel generic ("the warm, inviting atmosphere" / "a rich blend of flavors")
|
||||
**Fix:** Replace with specific, idiosyncratic detail that only someone who was there would know.
|
||||
|
||||
### 15. The Both-Sides Seesaw
|
||||
**Signal:** AI presents "both sides" of claims the author clearly believes in, or softens assertions with unnecessary counterpoints
|
||||
**Fix:** If the author has a position, let it land. Remove false balance.
|
||||
|
||||
### 16. Model-Specific First-Word Fingerprints
|
||||
**Signal:**
|
||||
- ChatGPT: sentences starting with "Certainly!", "As an AI…", "Sure!", "Here's…"
|
||||
- Claude: "I'd be happy to", "Based on", "I understand"
|
||||
- Generic: "Absolutely!", "Great question!"
|
||||
**Fix:** Delete or fully restructure these openers.
|
||||
|
||||
### 17. Passive Voice Overuse
|
||||
**Signal:** Actions where the agent is hidden: "Mistakes were made." / "The analysis was conducted."
|
||||
**Fix:** Say who did it. "The team made mistakes." "We ran the analysis."
|
||||
|
||||
### 18. Uniform Paragraph Length
|
||||
**Signal:** All paragraphs roughly the same length (3-5 sentences each)
|
||||
**Fix:** Vary paragraph length. Use a 1-sentence paragraph for impact.
|
||||
|
||||
### 19. Overclaiming Comprehensiveness
|
||||
**Signal:** "This comprehensive guide covers everything you need to know about…" / "A complete overview of…"
|
||||
**Fix:** Say what it actually covers. "This covers the three most common setup errors."
|
||||
|
||||
### 20. Fake Urgency / Motivational Padding
|
||||
**Signal:** Closing with generic positivity: "Now that you have the tools, you're ready to succeed!" / "The possibilities are endless!"
|
||||
**Fix:** End with a specific, useful next step or a genuine observation.
|
||||
|
||||
---
|
||||
|
||||
## Category C: Structural Red Flags
|
||||
|
||||
### 21. Symmetrical Bullet Lists
|
||||
**Signal:** Every bullet item is the same length; every list has the same count
|
||||
**Fix:** Vary. Let some bullets be 1 sentence, others 3. Cut a list to 2 items or expand to 6.
|
||||
|
||||
### 22. Overuse of Bold Headers in Short Text
|
||||
**Signal:** H2/H3 headers every 2-3 paragraphs in a short document
|
||||
**Fix:** Reserve headers for genuine section breaks in longer content.
|
||||
|
||||
### 23. Redundant Section Summaries
|
||||
**Signal:** A paragraph that restates the preceding section at the end of each section
|
||||
**Fix:** Cut. The section speaks for itself.
|
||||
|
||||
### 24. The "Despite / However" Pivot Formula
|
||||
**Signal:** "Despite its many advantages, [X] faces challenges…" appears formulaically
|
||||
**Fix:** Restructure the critique directly without the softening setup.
|
||||
|
||||
---
|
||||
|
||||
## Quick Scan Protocol
|
||||
|
||||
When scanning a new text, check in this order:
|
||||
|
||||
1. Ctrl+F for banned vocabulary (see #2 above)
|
||||
2. Read first sentence of every paragraph — are they all the same structure?
|
||||
3. Count em dashes — more than 3 per page is a flag
|
||||
4. Find one factual claim — is it specific or vague? (abstraction trap)
|
||||
5. Find one transition word — does it appear more than twice per page?
|
||||
6. Read aloud for 30 seconds — does it have rhythm, or is it a metronome?
|
||||
|
||||
---
|
||||
|
||||
*Sources: vrid.ai/blog/signs-of-ai-writing (Feb 2026), Wikipedia:Signs_of_AI_writing, academic research from CMU, theaugmentededucator.com, bethz.com pattern analysis*
|
||||
|
|
@ -1,86 +0,0 @@
|
|||
# Calibrating a voice profile
|
||||
|
||||
Run this for "calibrate our writing style", "create a voice profile for X",
|
||||
"learn how we write", "rebuild the house voice". For a single preference
|
||||
mentioned in passing, use "Update one thing" in SKILL.md instead and don't
|
||||
run these questions.
|
||||
|
||||
Adapted from a personal ghost-writer skill's calibration flow. The result
|
||||
is a wiki page, `wiki/voice/<name>.md`, not a file in a skill folder.
|
||||
|
||||
---
|
||||
|
||||
## Which profile
|
||||
|
||||
Take the name from the request (`house` when they say "our style", "the
|
||||
team voice", "house style"; the person's author slug for "my style"). If
|
||||
`wiki/voice/<name>.md` exists, ask once: "There's already a `<name>` voice.
|
||||
Update it, or replace it from scratch?" Updating keeps every field the new
|
||||
answers don't touch, and keeps `## Notes` byte-for-byte.
|
||||
|
||||
Set `voice_of`: `team` for a shared voice, `person` for one person's own,
|
||||
`third-party` for a writer or public figure.
|
||||
|
||||
## Question 1 — samples (the most useful input)
|
||||
|
||||
Ask: "Do you have documents written in this voice? Give me paths in the KB,
|
||||
files elsewhere, or paste text."
|
||||
|
||||
- **In the KB** (`raw/archive/`, `outputs/`, a `templates/` example): read
|
||||
them and cite them in `## Sources` with fingerprints.
|
||||
- **Elsewhere**: offer to copy them into `raw/inbox/` first, so they can be
|
||||
fingerprinted and re-read later. Read them either way. Without the copy,
|
||||
say "Calibrated from files outside the KB" in the page's opening
|
||||
paragraph, and leave them out of `## Sources`.
|
||||
- **Pasted text**: use it, and say a single paragraph is a weak signal.
|
||||
- **`.docx`**: `python3 -c "from docx import Document; d=Document('PATH'); print('\n'.join(p.text for p in d.paragraphs if p.text.strip()))"`.
|
||||
Without python-docx, ask for a PDF or pasted text. Never install it
|
||||
without asking.
|
||||
- For a file over 1,000 lines, read the first 200 and the last 100.
|
||||
|
||||
Extract, with examples quoted from the samples:
|
||||
|
||||
1. average sentence length and how often short ones land;
|
||||
2. contractions or not;
|
||||
3. deliberate fragments;
|
||||
4. how sentences usually open;
|
||||
5. recurring phrases (these go to **Keep**);
|
||||
6. vocabulary register and domain terms;
|
||||
7. paragraph length;
|
||||
8. how directly opinions are stated;
|
||||
9. overall tone in two or three words;
|
||||
10. habits that appear inconsistently and look like slips (candidates for
|
||||
**Avoid**).
|
||||
|
||||
With several documents, separate what holds across all of them from what
|
||||
one document does. If the samples come from different eras or authors,
|
||||
ask which ones are the target voice and use the rest for facts only.
|
||||
|
||||
## Questions 2–4 — only what the samples didn't settle
|
||||
|
||||
Ask one at a time, and skip any the samples already answer:
|
||||
|
||||
2. "What do you mostly write in this voice: notes, blog posts, business
|
||||
documents, client deliverables, or formal writing?" (maps to 1–5)
|
||||
3. "Short and punchy, long and flowing, or mixed?"
|
||||
4. "Any words or habits you want stripped, even if they aren't AI tells?
|
||||
And when there's a point of view, state it or stay neutral?"
|
||||
|
||||
## Confirm, then write
|
||||
|
||||
Summarise in two sentences: "This voice is [formality], [sentence style],
|
||||
[opinions]. I'll keep [phrases] and strip [avoid list]." Ask: "Does that
|
||||
sound right?" Apply corrections.
|
||||
|
||||
Then write the page from `profile-template.md` with `review: draft` and
|
||||
today's `last_updated`. Paste the best one or two sample paragraphs into
|
||||
`## Sample`; for a third-party voice, a few lines at most.
|
||||
|
||||
Create `wiki/voice/index.md` if it's missing (a table: name, `voice_of`,
|
||||
`tldr`), add the row, and add a `wiki/voice/` row to `wiki/index.md`. Log
|
||||
every create and change in `wiki/log.md` (Rule B) as you go.
|
||||
|
||||
Finish with one line: "Saved the `<name>` voice to `wiki/voice/<name>.md`.
|
||||
It applies to new outputs from now on. Edit the page or say 'update the
|
||||
<name> voice' to change it." If it isn't the default and the user may want
|
||||
it to be, offer that once.
|
||||
|
|
@ -1,158 +0,0 @@
|
|||
# Good Writing Principles
|
||||
|
||||
Reference for the `ckb-voice` skill. Apply these when rewriting. These are grounded in enduring style principles (Orwell, Strunk & White, Hemingway) and current research on what distinguishes human from AI prose.
|
||||
|
||||
---
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Clarity First
|
||||
The reader should understand every sentence on first read. No re-reading required.
|
||||
|
||||
- Use precise words over impressive ones
|
||||
- One idea per sentence when the idea is complex
|
||||
- Active voice: say who did what
|
||||
- Short sentences carry weight. Use them for your most important points.
|
||||
|
||||
> Orwell's rule: "If it is possible to cut a word out, always cut it out."
|
||||
|
||||
---
|
||||
|
||||
### 2. Economy of Words
|
||||
Every word must earn its place.
|
||||
|
||||
| Cut this | Write this |
|
||||
|----------|-----------|
|
||||
| in order to | to |
|
||||
| due to the fact that | because |
|
||||
| at this point in time | now |
|
||||
| in the event that | if |
|
||||
| it is important to note that | (just say it) |
|
||||
| basic fundamentals | fundamentals |
|
||||
| end result | result |
|
||||
| close proximity | near |
|
||||
|
||||
Eliminating redundancy doesn't flatten writing — it sharpens it. The meaning comes through faster and hits harder.
|
||||
|
||||
---
|
||||
|
||||
### 3. Voice and Authenticity
|
||||
Voice is the personality of the writer coming through the text. It can't be faked — it emerges from honest, confident writing.
|
||||
|
||||
**What creates voice:**
|
||||
- Word choices the author gravitates toward
|
||||
- Sentence rhythms that feel natural to them
|
||||
- Opinions delivered without apology
|
||||
- Specific details only this person would notice
|
||||
|
||||
**What kills voice:**
|
||||
- Hedging every assertion
|
||||
- Replacing personality with formality
|
||||
- Writing "correctly" instead of writing truly
|
||||
|
||||
When editing, ask: *does this still sound like the author, or does it sound like a textbook?*
|
||||
|
||||
---
|
||||
|
||||
### 4. Rhythm and Sentence Variation
|
||||
Writing without rhythm feels robotic. The goal is a cadence that pulls the reader forward.
|
||||
|
||||
**Rhythm tactics:**
|
||||
- Mix sentence lengths. A short sentence after a long one lands hard.
|
||||
- Vary sentence structure. Not every sentence needs subject → verb → object.
|
||||
- Use a one-sentence paragraph for a point that deserves to stand alone.
|
||||
- Parallel structures (two or more sentences with the same grammatical shape) create momentum — but only when used intentionally, not by default.
|
||||
|
||||
**The metronome test:** Read the text aloud. If every sentence takes about the same amount of time to speak, the rhythm is broken.
|
||||
|
||||
---
|
||||
|
||||
### 5. Specificity Over Generality
|
||||
Concrete details create trust. Vague language signals inexperience or distance from the subject.
|
||||
|
||||
| Vague (AI) | Specific (Human) |
|
||||
|-----------|-----------------|
|
||||
| "significant improvement" | "reduced errors by 40%" |
|
||||
| "the experience was positive" | "we spent 3 fewer hours per sprint in review" |
|
||||
| "it smelled wonderful" | "burnt espresso and old books" |
|
||||
| "many users prefer this" | "7 of the 10 engineers we interviewed chose it immediately" |
|
||||
| "recently" | "last Tuesday" / "in Q3" |
|
||||
| "a well-known study found" | "the 2024 CMU study of 12,000 texts found" |
|
||||
|
||||
When specifics aren't available, name the gap: "we haven't measured this yet" is more trustworthy than a vague positive claim.
|
||||
|
||||
---
|
||||
|
||||
### 6. Active Voice
|
||||
Passive voice hides agents and weakens impact. Use it only when the agent is genuinely unknown or irrelevant.
|
||||
|
||||
| Passive | Active |
|
||||
|---------|--------|
|
||||
| "Mistakes were made." | "The team made mistakes." |
|
||||
| "The report was written by Sarah." | "Sarah wrote the report." |
|
||||
| "It was decided that..." | "The board decided..." |
|
||||
| "Questions should be sent to..." | "Send questions to..." |
|
||||
|
||||
---
|
||||
|
||||
### 7. Directness
|
||||
A direct writer doesn't hide behind jargon or hedged language. They trust that clear, honest prose persuades better than embellishment.
|
||||
|
||||
**Signs of indirect writing:**
|
||||
- Using formal language to create distance ("leverage synergies")
|
||||
- Qualifying assertions that the author clearly believes ("it could be argued that this approach is effective")
|
||||
- Softening criticism to the point of meaninglessness ("while this has some limitations, it also shows promise")
|
||||
|
||||
**Directness in practice:**
|
||||
- Say the bad thing directly: "This approach failed in three ways."
|
||||
- Commit to your position: "This is wrong." not "One might argue this is suboptimal."
|
||||
- Trust the reader to handle direct information.
|
||||
|
||||
---
|
||||
|
||||
### 8. Unpretentious Language
|
||||
Strunk and White: use words and phrases that come readily to hand. Plain language bridges writer and reader.
|
||||
|
||||
The goal is to *express*, not to *impress*. Pretentious writing signals the writer is showing off rather than communicating. Readers sense this and disengage.
|
||||
|
||||
**Practical test:** If you'd feel awkward saying it out loud to a colleague, rewrite it.
|
||||
|
||||
---
|
||||
|
||||
### 9. Structure Serves the Reader
|
||||
Good structure is invisible — the reader moves through the document without noticing the architecture.
|
||||
|
||||
**Structure principles:**
|
||||
- Lead with the most important information (especially in professional writing)
|
||||
- Topic sentences that actually commit to a point, not just name a topic
|
||||
- Transitions that reflect logic, not just sequence ("but" / "because" / "so" rather than "furthermore" / "additionally")
|
||||
- Endings that land — not a summary of what was just said, but a forward-looking observation or call to action
|
||||
|
||||
---
|
||||
|
||||
### 10. Emotional Honesty
|
||||
Human writing carries the writer's actual perspective. It can be measured, professional, and still emotionally present.
|
||||
|
||||
AI avoids emotional stakes. It describes things at a distance. Human writers who care about their subject write differently than those who don't — and readers feel it.
|
||||
|
||||
**Ways emotional honesty shows up:**
|
||||
- An opinion delivered without apology
|
||||
- A specific anecdote from real experience
|
||||
- Admitting uncertainty without hiding behind vague language
|
||||
- Enthusiasm (or frustration, or caution) that's proportionate to the subject
|
||||
|
||||
---
|
||||
|
||||
## The Writer's Test
|
||||
|
||||
Before finalizing any rewrite, ask:
|
||||
|
||||
1. Can I read every sentence aloud without stumbling?
|
||||
2. Does every paragraph move forward — does it add something the previous didn't?
|
||||
3. Is there at least one concrete, specific detail in every major claim?
|
||||
4. Would I be comfortable sending this with my name on it?
|
||||
5. Does it sound like a person, or does it sound like a template?
|
||||
|
||||
---
|
||||
|
||||
*Grounded in: Strunk & White "The Elements of Style," Orwell "Politics and the English Language," Hemingway's iceberg principle, journalism.university writing principles, naturalwrite.com elements of good writing (2025)*
|
||||
|
|
@ -1,49 +0,0 @@
|
|||
---
|
||||
type: voice-profile
|
||||
tldr: <Whose voice this is, for what kind of text, and what it sounds like, in one sentence>
|
||||
voice_of: team # team | person | third-party
|
||||
last_updated: YYYY-MM-DD
|
||||
retention: high
|
||||
review: draft
|
||||
---
|
||||
|
||||
# <Name> voice
|
||||
|
||||
<!-- One or two sentences: when to use this voice and when not to. -->
|
||||
|
||||
## Tone
|
||||
<!-- How the text should come across, in a few words with an example:
|
||||
"calm practitioners talking to peers", "blunt", "warm but exact". -->
|
||||
|
||||
## Formality
|
||||
<!-- 1-5, plus a word on contractions:
|
||||
1 chat, 2 blog, 3 business, 4 client deliverable, 5 legal/academic. -->
|
||||
|
||||
## Sentence style
|
||||
<!-- Short and punchy / mixed / long and flowing. Paragraph length.
|
||||
Punctuation habits, such as how often an em dash is fine. -->
|
||||
|
||||
## Keep
|
||||
<!-- Words and phrases this voice uses on purpose. Kept even when the
|
||||
generic rules would ban them. -->
|
||||
|
||||
## Avoid
|
||||
<!-- Words, phrases and habits to strip, on top of the generic ban list. -->
|
||||
|
||||
## Audience
|
||||
<!-- Who reads it, and what they already know. -->
|
||||
|
||||
## Opinions
|
||||
<!-- State positions directly, stay neutral, or hedge only on uncertain facts. -->
|
||||
|
||||
## Sample
|
||||
<!-- One or two short paragraphs that sound exactly right. The rewrite
|
||||
matches their rhythm, not their content. For a third-party voice,
|
||||
a few lines at most. -->
|
||||
|
||||
## Sources
|
||||
<!-- Documents this voice was calibrated from, one bullet each with a
|
||||
fingerprint, as AGENTS.md §2 says. Leave empty if built from answers only. -->
|
||||
|
||||
## Notes
|
||||
<!-- Human-authored and protected: no skill rewrites this section. -->
|
||||
|
|
@ -1,188 +0,0 @@
|
|||
# Rewriting rules
|
||||
|
||||
Reference for the `ckb-voice` skill, adapted from a personal ghost-writer
|
||||
skill. The active voice profile overrides these defaults wherever it says
|
||||
something (see SKILL.md Step 4). Frozen spans (SKILL.md Step 3) are never
|
||||
touched, whatever a rule below says.
|
||||
|
||||
---
|
||||
|
||||
## Scan and triage
|
||||
|
||||
Run the quick scan protocol in this order:
|
||||
|
||||
1. Ctrl+F for banned vocabulary (section A below) - flag every hit
|
||||
2. Read the first sentence of every paragraph - are they all the same grammatical shape?
|
||||
3. Count em dashes - more than 3 per page is a flag
|
||||
4. Find one factual claim - is it specific or vague? (abstraction trap, section E)
|
||||
5. Find one transition word - does it appear more than twice per page?
|
||||
6. Read 30 seconds aloud - does it have rhythm, or is it a metronome?
|
||||
|
||||
Classify findings:
|
||||
|
||||
- **High priority** (most detectable, most trust-damaging): abstraction trap, banned vocabulary, hedging, formulaic structure, "serves as" substitutions
|
||||
- **Medium priority**: sentence rhythm, transition word overuse, Latinate bias, passive voice
|
||||
- **Low priority**: em dash count, rule-of-three overuse, -ing openers
|
||||
|
||||
**Exit path:** If the scan finds only one or two low-priority issues, fix those and stop. Don't force a full rewrite on a clean text.
|
||||
|
||||
If the user asks for a **quick pass**, fix high-priority items only and note what was skipped. For a long text or a **deep rewrite**, work through all categories and read `ai-signs.md` and `good-writing.md` for the extended checklist.
|
||||
|
||||
---
|
||||
|
||||
## Rules
|
||||
|
||||
Work through all categories relevant to what triage found. Preserve intentional stylistic choices - if the author consistently uses a construction across the whole text, treat it as a voice marker, not a tell.
|
||||
|
||||
---
|
||||
|
||||
### A. Banned vocabulary - replace or cut
|
||||
|
||||
Every instance must be replaced with a plain word or the sentence rewritten.
|
||||
|
||||
**Remove or replace:**
|
||||
testament, pivotal, underscore, watershed, profound, solidifies, stands as, serves as, crucial, vibrant, enduring, intricate, seamless, comprehensive, robust, dynamic, breathtaking, stunning, nestled, groundbreaking, renowned, boasts, bolstered, garner, foster, enhance, delve, tapestry, rich (as in "rich cultural heritage"), landscape (metaphorical), ecosystem (metaphorical), interplay, meticulous/meticulously, align with, highlighting, showcasing, emphasizing, realm, beacon, multifaceted, commendable
|
||||
|
||||
**Replace "is/are" substitutes with the plain verb:**
|
||||
- "serves as" → "is"
|
||||
- "stands as" → "is"
|
||||
- "marks" (as synonym for "is") → "is"
|
||||
- "represents" → "is" or "shows"
|
||||
- "features" (meaning "has") → "has"
|
||||
- "maintains" (meaning "has") → "has"
|
||||
- "offers" (meaning "has") → "has"
|
||||
|
||||
**Remove vague authority phrases entirely:**
|
||||
- "industry observers note", "experts argue", "some critics argue"
|
||||
- "researchers suggest" (unless a specific researcher is named)
|
||||
- "it has been suggested", "it is worth noting", "it is important to note"
|
||||
- "scholarship describes", "studies show" (without citation)
|
||||
|
||||
If the draft names the source anywhere (its `## Sources`, a citation), name it here. If not, state the claim plainly without the false authority and list it in the change note. Never cut the claim itself: in a KB that is the author's call, not the voice's.
|
||||
|
||||
---
|
||||
|
||||
### B. Banned sentence patterns
|
||||
|
||||
**"Not X but Y" / "Not only X but also Y"**
|
||||
Artificial contrasts that sound insightful but restate the obvious. State the point directly.
|
||||
|
||||
Before: "Not just a technical tool, it is also a communication platform."
|
||||
After: "It is both a technical tool and a communication platform."
|
||||
|
||||
**Trailing -ing phrases that restate the clause**
|
||||
Delete any trailing participial phrase that repeats what the main clause already said.
|
||||
|
||||
Before: "The system improved reliability, reducing errors across deployments."
|
||||
After: "The system improved reliability."
|
||||
|
||||
**The rule of three (triplet adjectives or vague phrases)**
|
||||
Three-part lists of vague adjectives are an LLM fingerprint. Use one specific detail or none.
|
||||
|
||||
Before: "a dynamic, innovative, and forward-thinking organisation"
|
||||
After: "an organisation that ships in two-week cycles"
|
||||
|
||||
**The "Despite / However" pivot formula**
|
||||
Before: "Despite its many advantages, the system faces challenges, but continues to improve."
|
||||
After: State the specific challenge as a concrete fact, or cut the paragraph.
|
||||
|
||||
**Transition word saturation**
|
||||
Remove or replace: furthermore, moreover, additionally, consequently, thus, hence, in addition, it is worth noting, in contrast.
|
||||
Replace with direct connectives ("but," "so," "and") or restructure without them.
|
||||
|
||||
---
|
||||
|
||||
### C. Structural patterns to remove
|
||||
|
||||
**"In conclusion" / "As we have seen" / "In summary" openers**
|
||||
Delete. Start the final paragraph with its actual content.
|
||||
|
||||
**"In today's world" / "In today's [adjective] landscape" openers**
|
||||
Delete the opener. Start with the substantive claim.
|
||||
|
||||
**"As X continues to evolve" / "With the rise of X" openers**
|
||||
Delete. Start with what actually happened.
|
||||
|
||||
**Separate "Challenges and Future Prospects" or "Looking Ahead" sections**
|
||||
Integrate challenges as concrete statements into the relevant sections. Cut speculation.
|
||||
|
||||
**Meta-commentary and structural narration**
|
||||
Delete sentences that describe the document rather than saying the thing:
|
||||
- "In this article, we will explore…"
|
||||
- "As we can see from the above…"
|
||||
- "This section covers…" (as a standalone sentence)
|
||||
|
||||
---
|
||||
|
||||
### D. Formatting tells to remove
|
||||
|
||||
**Bullet points with bolded lead phrases**
|
||||
The pattern "**Term:** explanation" throughout a document is an LLM fingerprint. Convert to prose where the calling skill's format allows it. If a list is genuinely needed, use plain bullets without bolded labels.
|
||||
|
||||
**Excessive bold mid-sentence**
|
||||
Bold is for terms being defined or genuine emphasis only. Remove bold from any word bolded simply because the LLM deemed it important.
|
||||
|
||||
**Excessive headers**
|
||||
One header per short paragraph is a structural tell. Consolidate sections. A paragraph does not need a heading unless it begins a genuinely new section. A template's headings (a `ckb-document` output) are frozen and stay.
|
||||
|
||||
**Em dashes used for decoration or aside**
|
||||
Replace em dashes (—) in prose with a comma, a full stop, a hyphen-minus surrounded by spaces ( - ), or restructure the sentence. A profile may set its own dash rate. Crux attribution lines start with an em-dash and are frozen.
|
||||
|
||||
**Symmetrical bullet lists**
|
||||
Every bullet the same length, every list the same count, is a tell. Vary: let some bullets be one sentence, others three. Cut a list to two items or expand to six.
|
||||
|
||||
---
|
||||
|
||||
### E. The abstraction trap (highest priority)
|
||||
|
||||
Every generic claim should carry a concrete fact, number, name, or example, taken from the draft itself or from the sources it cites. Never invent one. If the draft has nothing specific to offer, keep the claim and list it in the change note as vague, so the author can fill it or cut it.
|
||||
|
||||
Before: "The platform has helped many organisations improve their processes."
|
||||
After: "The platform cut invoice processing time by 40% at the client in the case study." (only if the draft or its source says so)
|
||||
Or: keep it and flag it.
|
||||
|
||||
Apply to every sentence containing:
|
||||
- quantities without numbers ("many," "several," "numerous," "various")
|
||||
- superlatives without evidence ("the most," "the best," "leading")
|
||||
- outcomes without measurement ("improved," "enhanced," "transformed")
|
||||
- time without specifics ("recently," "in recent years," "over time")
|
||||
|
||||
---
|
||||
|
||||
### F. Voice, clarity and authenticity
|
||||
|
||||
**Latinate bias**
|
||||
Replace long formal words with short plain ones:
|
||||
- "utilize" → "use", "facilitate" → "help", "commence" → "start"
|
||||
- "demonstrate" → "show", "approximately" → "about", "endeavor" → "try"
|
||||
- "in order to" → "to", "due to the fact that" → "because"
|
||||
|
||||
**Passive voice**
|
||||
Say who did what. "Mistakes were made" → "The team made mistakes."
|
||||
|
||||
**Hedging**
|
||||
If the author means it, say it. Cut: arguably, potentially, it could be said, in many ways, one could suggest, somewhat.
|
||||
|
||||
**Treadmill effect**
|
||||
Cut restatements. If the same idea appears twice, keep the best version, delete the rest.
|
||||
|
||||
**Perfect grammar, zero personality**
|
||||
Add a fragment. Use a contraction. Let a short sentence stand alone. Like this.
|
||||
|
||||
**Preserve the author's voice**
|
||||
Do not over-sanitize. Retain domain vocabulary the author uses deliberately. Where the original has opinions, let them land - do not hedge what the author clearly meant to assert. One opinion should land in the final version without softening.
|
||||
|
||||
---
|
||||
|
||||
### G. Sentence rhythm
|
||||
|
||||
LLMs produce sentences of similar length and structure. After all other fixes, check rhythm:
|
||||
|
||||
- Are consecutive sentences the same length? Break one up or combine two.
|
||||
- Do multiple sentences start with subject + verb? Vary the opening.
|
||||
- Does every paragraph have at least one short sentence (under 10 words)?
|
||||
- Are all paragraphs roughly the same length? Use a one-sentence paragraph for a point that deserves to stand alone.
|
||||
- Read aloud: if every sentence takes about the same time to speak, the rhythm is broken.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -10,9 +10,6 @@ description: Record a numbered, append-only decision record in wiki/decisions/,
|
|||
A decision is never rewritten to reflect a later change of mind: a new one
|
||||
supersedes it and both stay on the record. Recording wires supersession in
|
||||
both directions; look-up is scoped to `wiki/decisions/`, not the whole wiki.
|
||||
It also keeps what the decision was expected to change and, at review,
|
||||
what actually happened, so a later reader can tell a decision that worked
|
||||
from one that merely stayed in force.
|
||||
Writes only `wiki/decisions/`, its `index.md` and `log.md`,
|
||||
`wiki/graph/edges.json`, and a pointer line in `wiki/log.md`.
|
||||
|
||||
|
|
@ -31,7 +28,6 @@ decided_on: 2026-09-01
|
|||
decided_by: Alice Smith, Bob Jones
|
||||
affects: /wiki/entities/billing-service.md, /wiki/projects/index.md
|
||||
review_on: 2027-03-01
|
||||
expected_outcome: Monthly reporting queries run in the billing store, with no second analytics database.
|
||||
supersedes: /wiki/decisions/0003-use-mysql.md
|
||||
confidence: 0.9
|
||||
quality: 0.8
|
||||
|
|
@ -70,18 +66,6 @@ What else was on the table and why each was not chosen. A decision record
|
|||
without this is much less useful on re-reading: it's the part that stops
|
||||
the same option being re-proposed every six months.
|
||||
|
||||
## Tried
|
||||
|
||||
What was actually built, run or tested on the way here and dropped, with
|
||||
what was observed. Not the same as *Alternatives considered*: those were
|
||||
weighed, these were tried. A pilot that read MySQL replicas into a
|
||||
reporting cache ran for two weeks (2026-08) and missed its nightly window
|
||||
three times.
|
||||
|
||||
## Outcome
|
||||
|
||||
*(Appended at review, never before. See "Reviewing an outcome".)*
|
||||
|
||||
## Supersession
|
||||
|
||||
Supersedes [[D-0003]] / [D-0003](/wiki/decisions/0003-use-mysql.md) — MySQL
|
||||
|
|
@ -127,10 +111,7 @@ the append-only rule exists to prevent.
|
|||
| `decided_on` | yes for `accepted`/`rejected`/`reversed` | `YYYY-MM-DD`, the date the call was made. Distinct from `last_updated`, which is when the *page* last changed. A `proposed` decision may have no `decided_on` yet. |
|
||||
| `decided_by` | yes when known | comma-separated names, kept flat and plain so tooling can read it. The body's **Deciders** line carries the dual-links to entity pages. If genuinely unknown, write `unknown` rather than omitting the field — "we don't know who decided this" is itself worth recording. |
|
||||
| `affects` | no | comma-separated project-root-absolute wiki paths this decision constrains. Cheap way to answer "what decisions touch X" without walking the graph. |
|
||||
| `review_on` | no | `YYYY-MM-DD` to revisit. `ckb-lint` reports these once the date passes, until an `outcome_checked` on or after it records the review. |
|
||||
| `expected_outcome` | no, preferred with `review_on` | One line: what this decision should change, stated so a later reader can check it ("p95 checkout latency under 300 ms"; not "better performance"). Written **when the decision is recorded**, before anyone knows the result. One added later gets `(added YYYY-MM-DD)` at its end, so nobody mistakes hindsight for a prediction. |
|
||||
| `outcome` | set at review | `met` / `partly` / `missed` / `unclear`: how what happened compares with `expected_outcome`. |
|
||||
| `outcome_checked` | set at review | `YYYY-MM-DD` of the latest outcome review. |
|
||||
| `review_on` | no | `YYYY-MM-DD` to revisit. `ckb-lint` reports these once the date passes. |
|
||||
| `supersedes` / `superseded_by` | when relevant | project-root-absolute path to the other decision. **Always set both sides** (see below). |
|
||||
| `confidence`, `quality`, `last_updated`, `freshness_window_days`, `retention` | as usual | standard page schema. Decisions default to `freshness_window_days: 365` and `retention: high` — a decision record doesn't rot the way a status page does, and it should survive a retention sweep. |
|
||||
|
||||
|
|
@ -146,13 +127,6 @@ Then check what's missing against this list, in priority order:
|
|||
3. **When** — a date. "Today" is fine; "last Tuesday's architecture review" is fine, resolve it to a date.
|
||||
4. **Why** — the rationale, and the alternatives that lost.
|
||||
5. **Whether it changes an existing decision** — see Step 2.
|
||||
6. **What it should change** — the `expected_outcome`, and a `review_on`
|
||||
date by which that should be visible. Offer one from the rationale if
|
||||
the user gave none ("So by March, reporting runs without a second store?
|
||||
Shall I put that down to check?"). Never invent it: no answer means no
|
||||
field.
|
||||
7. **Anything already tried** — a pilot, a spike, a reverted change. That
|
||||
goes under `## Tried` with what was observed.
|
||||
|
||||
Ask for the missing ones in a **single** `AskUserQuestion` round rather than
|
||||
an interview — this is a recording task, not a discovery interview. If the
|
||||
|
|
@ -184,14 +158,6 @@ same subject. If one exists and is still `accepted`:
|
|||
Both directions must be set. A one-sided supersession link is a lint finding,
|
||||
and it breaks the "what changed this?" lookup in the other direction.
|
||||
|
||||
**A direction already tried or rejected.** When the new decision picks
|
||||
something listed under an earlier decision's `## Tried` or `## Alternatives
|
||||
considered`, or reverses a `rejected` decision, say so and ask what is new
|
||||
since then: a changed constraint, new evidence, a different model or
|
||||
setting. Put that answer in the new decision's `## Context`. Coming back to a
|
||||
direction is fine; coming back without knowing it was tried before is the
|
||||
mistake this check prevents.
|
||||
|
||||
### Step 3 — Allocate the number and write the page
|
||||
|
||||
The next number is the highest existing `NNNN` in `wiki/decisions/` plus one,
|
||||
|
|
@ -235,33 +201,6 @@ updated), which deciders had no entity page, and the standard reminder that
|
|||
this is on disk but not committed — "say 'sync changes' when you want it
|
||||
pushed."
|
||||
|
||||
## How to run this skill — reviewing an outcome
|
||||
|
||||
Triggered by "review D-0007", "did D-0007 work", or a lint finding that a
|
||||
`review_on` with an `expected_outcome` has passed.
|
||||
|
||||
1. Read the page: `expected_outcome`, `## Rationale`, `## Tried`.
|
||||
2. Ask the user what actually happened, or check it against the wiki where
|
||||
the evidence is recorded there. Cite where the answer came from.
|
||||
3. Append a dated entry to `## Outcome` (create the section above
|
||||
`## Supersession` / `## Sources` if missing). Never edit an earlier one:
|
||||
|
||||
```markdown
|
||||
### 2027-03-04 — partly
|
||||
- **Expected:** Monthly reporting queries run in the billing store, with no second analytics database.
|
||||
- **Observed:** Monthly reports run in Postgres; the yearly audit export still needs the old warehouse.
|
||||
- **Evidence:** /wiki/projects/billing.md, ops review 2027-03-02
|
||||
- **Checked by:** Ana Reyes
|
||||
```
|
||||
|
||||
4. Set `outcome`, `outcome_checked` and `last_updated`. If another check is
|
||||
worth making, set a new `review_on` after `outcome_checked`. Otherwise
|
||||
leave `review_on` as it is: the outcome check closes it.
|
||||
5. When the outcome says the decision should change, that is a new decision
|
||||
that supersedes this one (recording, Step 2), and this outcome entry is
|
||||
its context. Offer it; do not record it unasked.
|
||||
6. Log it in `wiki/decisions/log.md` (action `UPDATE (outcome review)`).
|
||||
|
||||
## How to run this skill — looking up
|
||||
|
||||
### Step 1 — Start at the decisions index
|
||||
|
|
@ -283,9 +222,7 @@ ones.
|
|||
and before that MySQL, changed in September because of reporting" is the
|
||||
useful answer; "we use Postgres" is the impoverished one. Follow
|
||||
`supersedes`/`superseded_by` chains in both directions and present the
|
||||
history in order. Include `outcome` where one is recorded: "in force, and
|
||||
reviewed in March as having partly met its aim" is a different answer from
|
||||
"in force".
|
||||
history in order.
|
||||
|
||||
### Step 3 — Verify against the source before answering
|
||||
|
||||
|
|
@ -318,14 +255,10 @@ a `wiki/query-gaps.md` entry (`ckb-retrieve` owns that file).
|
|||
## Rule: decisions are append-only
|
||||
|
||||
The only edits this skill makes to an *existing* decision page are:
|
||||
`status`, `superseded_by`, `last_updated`, the outcome fields
|
||||
(`outcome`, `outcome_checked`, a later `review_on`), a new dated entry
|
||||
appended to `## Outcome`, and — when the user is explicitly
|
||||
`status`, `superseded_by`, `last_updated`, and — when the user is explicitly
|
||||
correcting a recording error rather than changing their mind — the factual
|
||||
metadata fields. Context, Decision, Rationale, Consequences, Alternatives, Tried,
|
||||
`expected_outcome`, and earlier Outcome entries are never rewritten to match
|
||||
a later view. A wrong prediction is the most useful thing on the page; the
|
||||
reason to write it down first is so that it can turn out wrong.
|
||||
metadata fields. Context, Decision, Rationale, Consequences, and Alternatives
|
||||
are never rewritten to match a later view.
|
||||
|
||||
When the user says "actually we changed our mind about D-0003", that is a new
|
||||
decision superseding D-0003, not an edit to D-0003. Say so and record it that
|
||||
|
|
|
|||
|
|
@ -71,13 +71,9 @@ The canonical repo keeps four branches, and they are not interchangeable:
|
|||
|---|---|---|
|
||||
| `main` | **Stable.** The released template. | Always, unless the user says otherwise. **This is the default.** |
|
||||
| `test` | **Release candidate.** Changes validated before they reach `main`. | The user is helping validate a release, or needs a fix that has landed but not shipped. |
|
||||
| `experimental` | **Preview.** Work merged from `dev` early; may be broken, may be reverted. | The user is developing the template itself, or explicitly wants the newest ideas and accepts the risk. |
|
||||
| `experimental` | **Development.** Active work; may be broken, may be reverted. | The user is developing the template itself, or explicitly wants the newest ideas and accepts the risk. |
|
||||
| `1.x` | **Maintenance.** The 1.x line after 2.0: fixes only; the last line with PowerShell support. | The user needs PowerShell, or asks for 1.x by name. |
|
||||
|
||||
`dev` is the template's integration branch and never carries a version change
|
||||
(D-0022), so it is not a channel: a KB built from it would never see an
|
||||
upgrade. Asked for `dev` ("set up a dev KB"), use `experimental` and say why.
|
||||
|
||||
Default to `main`. Take a different branch only when the user asks for one,
|
||||
in whatever words: "initialize from the test branch", "use experimental",
|
||||
"set up a dev KB", "bootstrap from `<url>` branch `<name>`", "I want the
|
||||
|
|
@ -315,9 +311,8 @@ generic structure:
|
|||
generic - directory tree, cascade priority, frontmatter summary, no
|
||||
project content). Set `last_updated` to today.
|
||||
- **`wiki/log.md`** - header and explanation only, no entries.
|
||||
- **`wiki/error-book.md`** - copy verbatim (already generic: the entry
|
||||
format in a comment + a placeholder note, no problems). Set
|
||||
`last_updated` to today.
|
||||
- **`wiki/error-book.md`** - copy verbatim (already generic: empty table
|
||||
+ placeholder note). Set `last_updated` to today.
|
||||
- **`wiki/entities/index.md`** - header + placeholder note, no entries.
|
||||
- **`wiki/graph/index.md`** - header + pointer to `edges.json`, the edge
|
||||
vocabulary table and its conventions **verbatim** (`ckb-ingest`,
|
||||
|
|
@ -343,37 +338,6 @@ If the template source's `wiki/` holds scaffold files beyond this list,
|
|||
carry them over the same way - empty, structure only. The list above is
|
||||
what the schema requires, not a cap.
|
||||
|
||||
#### Step 8b - Offer to carry experience from this KB (only when run inside one)
|
||||
|
||||
A new KB starts with no lessons and an empty error book, so it can repeat
|
||||
mistakes this KB has already learned from. When this skill runs inside a
|
||||
populated KB whose `wiki/lessons.md` or `wiki/error-book.md` has entries, ask
|
||||
once:
|
||||
|
||||
> "This KB has N lessons and M error-book problems. Carry any into the new
|
||||
> KB? (all / pick / none)"
|
||||
|
||||
Default to none, and never carry anything unasked. On *pick*, list each
|
||||
lesson's heading and **Context** and each error-book entry's heading and
|
||||
status, and take the user's choice. For each one carried:
|
||||
|
||||
- **Lesson** → the new KB's `wiki/lessons.md` (create it as `ckb-profile`
|
||||
does), unchanged except for an added
|
||||
`- **Carried from:** <source KB name>, recorded there YYYY-MM-DD` line.
|
||||
Skip struck-through lessons.
|
||||
- **Error-book problem** → the new KB's `wiki/error-book.md` with all its
|
||||
attempt rows, the heading kept, and a `- **Carried from:** <source KB
|
||||
name>, YYYY-MM-DD` line under **Opened**. Its status becomes `watching`
|
||||
whatever it was: nothing has been checked in the new setting yet.
|
||||
- Set `review: needs_update` on both files so someone in the new KB checks
|
||||
what was carried, and add one entry to the new `wiki/log.md` naming the
|
||||
source KB and the count.
|
||||
|
||||
Profiles (`workload/profiles/`) and personal lessons are never carried: they
|
||||
belong to people, not to a KB. A lesson whose **Applies when** names this
|
||||
KB's own projects or sources rarely makes sense elsewhere. Point that out
|
||||
when the user picks one.
|
||||
|
||||
Do not carry over any entity pages, graph edges, log entries, or overview
|
||||
content specific to this project - the whole point is an empty KB with the
|
||||
same shape.
|
||||
|
|
@ -475,7 +439,6 @@ Tell the user:
|
|||
- The `VERSION` the new KB starts on, and what was decided for `LICENSE`'s
|
||||
copyright line.
|
||||
- Whether a git repo was initialized in the target, or why not.
|
||||
- What experience was carried (Step 8b): counts, or "none".
|
||||
- Next step: "Drop material into `raw/inbox/` and say 'Ingest' to populate the wiki for the first time."
|
||||
|
||||
## Edge cases
|
||||
|
|
|
|||
|
|
@ -67,8 +67,8 @@ page that needs a decision, not the decision itself.
|
|||
**Without Python (degraded path).** Say so once and point to
|
||||
"Prerequisites" in `docs/MANUAL.md`. Then:
|
||||
|
||||
1. Run the native fallback for the cheap counts — `bash scripts/lint_quick.sh`
|
||||
(Git Bash on Windows). It covers checks 1, 2,
|
||||
1. Run the native fallback for the cheap counts — `scripts/lint_quick.sh`
|
||||
(bash) or `scripts/lint_quick.ps1` (PowerShell). It covers checks 1, 2,
|
||||
12 and a reduced check 15 only, and prints the same one-line summary as
|
||||
`--quick`.
|
||||
2. For a full lint, work the checklist in
|
||||
|
|
@ -117,15 +117,11 @@ from the vocabulary, a `decided_on` date where the status implies one, a
|
|||
`decided_by` (`unknown` counts — an omitted field doesn't), `affects` targets
|
||||
and supersession links that resolve, supersession set on **both** sides,
|
||||
`status: superseded`/`reversed` matched by a `superseded_by`, unique
|
||||
four-digit decision numbers, an `outcome` from `met`/`partly`/`missed`/`unclear`
|
||||
with a dated `outcome_checked`, and any `review_on` date that has passed
|
||||
with no `outcome_checked` on or after it. Fix the structural ones
|
||||
directly — they're mechanical. A `review_on` that has come due is not a
|
||||
defect, though: report it so the user can decide whether to revisit. When
|
||||
the page has an `expected_outcome`, the finding says so: that review is
|
||||
"did it do what we expected?", answered through `ckb-decide`'s outcome
|
||||
review. Never change a decision's substance yourself (`ckb-decide` →
|
||||
decisions are append-only).
|
||||
four-digit decision numbers, and any `review_on` date that has passed. Fix
|
||||
those directly — they're mechanical. A `review_on` that has come due is not a
|
||||
defect, though: report it so the user can decide whether to revisit, and never
|
||||
change a decision's substance yourself (`ckb-decide` → decisions are
|
||||
append-only).
|
||||
|
||||
The *semantic* half stays yours: when two pages appear to cover the same
|
||||
entity or the same choice, check for contradictions. If one is clearly
|
||||
|
|
@ -163,40 +159,9 @@ duplicate log entries directly — these are the safest auto-fixes on the list.
|
|||
|
||||
Record any systemic issue found above (a repeated broken pattern, a
|
||||
recurring format mismatch, the same kind of orphan appearing again) in
|
||||
`wiki/error-book.md`. A one-off, isolated issue doesn't need an entry —
|
||||
this is for patterns, not incidents. The file's comment block holds the
|
||||
format; the rules:
|
||||
|
||||
1. **Problem first, then attempt.** An entry (`## E<n> — <root cause>`) is
|
||||
a hypothesis about *why*, and holds every attempt made against it. Read
|
||||
the open entries before writing. When one already explains the finding,
|
||||
append an attempt row to it. Open a new entry only when none does.
|
||||
2. **Write the expectation before the result.** Each attempt states what
|
||||
it should stop, in terms the next lint run can confirm ("no more
|
||||
orphans under `wiki/projects/`"), with `Observed: pending`.
|
||||
3. **Close the loop on later runs.** On every lint run, check each
|
||||
`pending` attempt against this run's findings and fill in `held`,
|
||||
`recurred` or `partly`, with the date. When the problem recurs, the old
|
||||
row stays as written and a new attempt is added. A tested fix that did
|
||||
not hold is evidence, not clutter. Try the same fix again only when
|
||||
something has changed, and say what changed in the new row.
|
||||
4. **Context on every attempt**: the agent/model and the template
|
||||
`VERSION` it ran under. When the model or template has changed since an
|
||||
attempt, treat its result as something to recheck, not a settled fact.
|
||||
5. **Status**: `open` while it recurs; `watching` once an attempt held but
|
||||
fewer than two later runs have confirmed it; `resolved` after that. Add a
|
||||
`Constraint:` line once one is known, and propose it for `AGENTS.md` if
|
||||
it should bind every session (never edit `AGENTS.md` from here).
|
||||
6. **Merging**: two entries with the same root cause are merged into the
|
||||
older one. Move the attempt rows across, marked `(from E4)`, and leave
|
||||
the newer heading as an alias, `## E4 → E2 — merged YYYY-MM-DD`, so
|
||||
links and log entries that name E4 still resolve.
|
||||
|
||||
An error book from before schema 1.8 (a single table) stays as it is under
|
||||
an `## Earlier entries` heading. New entries use the format above; old rows
|
||||
are moved into an entry only when a new attempt joins them.
|
||||
|
||||
Every change to the file is a `wiki/` change, logged under Rule B.
|
||||
`wiki/error-book.md` with its root cause, the fix applied, and the derived
|
||||
constraint that should prevent recurrence. A one-off, isolated issue
|
||||
doesn't need an Error Book entry — this is for patterns, not incidents.
|
||||
|
||||
### 10 — External source config check
|
||||
|
||||
|
|
|
|||
|
|
@ -10,17 +10,17 @@ say what was skipped — by hand, this costs tokens.
|
|||
|
||||
| # | Check | How to detect by hand |
|
||||
|---|---|---|
|
||||
| 1 | Conformance | `rg -L --files-without-match '^---$' wiki -g '*.md' -g '!index.md' -g '!log.md'` lists pages with no frontmatter. For the rest, open the frontmatter: must be flat `key: value` lines, closed by `---`, with a non-empty `type`. `lint_quick.sh` counts these. |
|
||||
| 2 | Freshness | `rg -n '^(last_updated|freshness_window_days):' wiki` and compare: today − `last_updated` > `freshness_window_days` ⇒ stale. `lint_quick.sh` counts these. |
|
||||
| 1 | Conformance | `rg -L --files-without-match '^---$' wiki -g '*.md' -g '!index.md' -g '!log.md'` lists pages with no frontmatter. For the rest, open the frontmatter: must be flat `key: value` lines, closed by `---`, with a non-empty `type`. `lint_quick.sh`/`.ps1` counts these. |
|
||||
| 2 | Freshness | `rg -n '^(last_updated|freshness_window_days):' wiki` and compare: today − `last_updated` > `freshness_window_days` ⇒ stale. `lint_quick.sh`/`.ps1` counts these. |
|
||||
| 3 | Confidence | `rg -n '^confidence:' wiki` — flag values outside 0.0–1.0 or non-numeric; then apply the decay rule from check 3 to pages older than their window. |
|
||||
| 4 | Retention | `rg -n '^retention: low' wiki` and check each page's age against check 4's archive threshold. |
|
||||
| 5 | Decisions | For each `wiki/decisions/NNNN-*.md`: `status` ∈ proposed/accepted/rejected/superseded/reversed; `decided_on` and `decided_by` present; every `supersedes` has a matching `superseded_by` on the target (`rg -n '^(supersedes|superseded_by):' wiki/decisions`). |
|
||||
| 6 | Orphans | For each page, `rg -l '<page-slug>' wiki` — a page nothing links to (outside its own directory index) is an orphan. Do this only for pages touched since the last lint unless asked for a full pass. |
|
||||
| 7 | Graph | `rg -o '"(from|to)": *"[^"]+"' wiki/graph/edges.json` — every endpoint must exist as a file. Verbs must be in the edge vocabulary listed in `docs/CHANGELOG.md`. |
|
||||
| 8 | Index / log | Every page appears in its directory `index.md`; every file in `git log --since=<last lint> --name-only -- wiki` has a matching `wiki/log.md` (or `wiki/decisions/log.md` + POINTER) entry. |
|
||||
| 12 | Source fingerprints | For each `## Sources` bullet with `sha256:<prefix>`: `sha256sum <file>` must start with the prefix. `lint_quick.sh` counts these. |
|
||||
| 12 | Source fingerprints | For each `## Sources` bullet with `sha256:<prefix>`: `sha256sum <file>` (or `Get-FileHash`) must start with the prefix. `lint_quick.sh`/`.ps1` counts these. |
|
||||
| 13 | Crux verbatimness | For each `## Crux` quote, `rg -F '<first ~40 chars>' <cited source>` — a miss means the evidence moved. Only practical for a few pages; list candidates and ask which to verify. |
|
||||
| 15 | Secrets and private spans | `rg -n 'BEGIN [A-Z ]*PRIVATE KEY|AKIA[0-9A-Z]{16}|gh[pousr]_[A-Za-z0-9]{36}|xox[abprs]-|sk-[A-Za-z0-9_-]{20}|AIza[0-9A-Za-z_-]{35}|://[^/ :@]+:[^/ @]+@' wiki outputs workload raw` and `rg -n -i '<private>' wiki`. `lint_quick.sh` counts the reduced set. |
|
||||
| 15 | Secrets and private spans | `rg -n 'BEGIN [A-Z ]*PRIVATE KEY|AKIA[0-9A-Z]{16}|gh[pousr]_[A-Za-z0-9]{36}|xox[abprs]-|sk-[A-Za-z0-9_-]{20}|AIza[0-9A-Za-z_-]{35}|://[^/ :@]+:[^/ @]+@' wiki outputs workload raw` and `rg -n -i '<private>' wiki`. `lint_quick.sh`/`.ps1` counts the reduced set. |
|
||||
| 16 | Kept answers | For each `outputs/answers/*.md`, check its `## Sources` fingerprints as in check 12. |
|
||||
| 17 | Review status | `rg -n '^review:' wiki` — values must be draft/reviewed/needs_update; for each `reviewed` page compare `last_updated` with `reviewed_on`. `rg -l '^review: (draft|needs_update)' wiki` is the review queue. |
|
||||
| 18 | Contradictions | `rg -n '^> *CONTRADICTION:' wiki` — every hit is open until resolved. |
|
||||
|
|
|
|||
182
.agents/skills/ckb-lint/scripts/lint_quick.ps1
Normal file
182
.agents/skills/ckb-lint/scripts/lint_quick.ps1
Normal file
|
|
@ -0,0 +1,182 @@
|
|||
# Copyright 2026 Michał Kopeć
|
||||
#
|
||||
# Licensed under the Apache License, Version 2.0 (the "License");
|
||||
# you may not use this file except in compliance with the License.
|
||||
# You may obtain a copy of the License at
|
||||
#
|
||||
# http://www.apache.org/licenses/LICENSE-2.0
|
||||
#
|
||||
# Unless required by applicable law or agreed to in writing, software
|
||||
# distributed under the License is distributed on an "AS IS" BASIS,
|
||||
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
# See the License for the specific language governing permissions and
|
||||
# limitations under the License.
|
||||
#
|
||||
# No-Python fallback for `lint_report.py --quick` (Rule E session-start check).
|
||||
#
|
||||
# powershell -ExecutionPolicy Bypass -File lint_quick.ps1 [-Today YYYY-MM-DD]
|
||||
#
|
||||
# Run from the repository root. Read-only. Prints the same one-line summary
|
||||
# shape as the Python script for four of its six quick checks:
|
||||
# - malformed pages with no/unclosed frontmatter or no `type`
|
||||
# - past freshness `last_updated` + `freshness_window_days` < today
|
||||
# - source drift `## Sources` bullets whose sha256 no longer matches
|
||||
# - possible secrets a reduced set of credential shapes, and `<private>` in wiki/
|
||||
# Diverged crux quotes and the context budget need the full checker and are
|
||||
# skipped; the summary says so. Exit 0 when clean, 1 when anything was flagged.
|
||||
#
|
||||
# Works on Windows PowerShell 5.1 and PowerShell 7+. Prefer the Python script
|
||||
# whenever an interpreter is available — it is the reference implementation.
|
||||
[CmdletBinding()]
|
||||
param([string]$Today = "")
|
||||
|
||||
$ErrorActionPreference = "Stop"
|
||||
if (-not (Test-Path -LiteralPath "wiki" -PathType Container)) {
|
||||
[Console]::Error.WriteLine("error: no wiki/ directory here — run from the repository root"); exit 2
|
||||
}
|
||||
function Parse-Date([string]$s) {
|
||||
$s = $s.Trim()
|
||||
if ($s -notmatch '^\d{4}-\d{2}-\d{2}$') { return $null }
|
||||
try { return [datetime]::ParseExact($s, 'yyyy-MM-dd', [Globalization.CultureInfo]::InvariantCulture) } catch { return $null }
|
||||
}
|
||||
if ($Today -eq "") { $todayDate = (Get-Date).Date } else {
|
||||
$todayDate = Parse-Date $Today
|
||||
if ($null -eq $todayDate) { [Console]::Error.WriteLine("error: -Today is not a YYYY-MM-DD date: $Today"); exit 2 }
|
||||
}
|
||||
function Unquote([string]$v) {
|
||||
$v = $v.Trim()
|
||||
if ($v.Length -ge 2 -and $v[0] -eq $v[-1] -and ($v[0] -eq '"' -or $v[0] -eq "'")) { return $v.Substring(1, $v.Length - 2) }
|
||||
return $v
|
||||
}
|
||||
|
||||
$malformed = 0; $stale = 0; $drift = 0
|
||||
$root = (Get-Location).Path
|
||||
|
||||
# Trees: wiki/ plus every connector-backed lib (has source.yaml).
|
||||
$trees = @("wiki")
|
||||
if (Test-Path -LiteralPath "libs" -PathType Container) {
|
||||
Get-ChildItem -LiteralPath "libs" -Directory | ForEach-Object {
|
||||
if (Test-Path -LiteralPath (Join-Path $_.FullName "source.yaml")) { $trees += "libs/$($_.Name)" }
|
||||
}
|
||||
}
|
||||
|
||||
foreach ($tree in $trees) {
|
||||
$files = Get-ChildItem -LiteralPath $tree -Recurse -File -Filter *.md | Sort-Object FullName
|
||||
foreach ($file in $files) {
|
||||
if ($file.Name -eq "index.md" -or $file.Name -eq "log.md") { continue }
|
||||
$rel = $file.FullName.Substring($root.Length).TrimStart('\', '/')
|
||||
if (($rel -split '[\\/]') | Where-Object { $_.StartsWith('.') }) { continue }
|
||||
|
||||
$text = [IO.File]::ReadAllText($file.FullName) -replace "`r`n", "`n"
|
||||
$lines = $text -split "`n"
|
||||
|
||||
# ---- frontmatter --------------------------------------------------
|
||||
if ($lines.Count -eq 0 -or $lines[0] -ne '---') { $malformed++; continue }
|
||||
$end = -1
|
||||
for ($i = 1; $i -lt $lines.Count; $i++) { if ($lines[$i] -eq '---') { $end = $i; break } }
|
||||
if ($end -lt 0) { $malformed++; continue }
|
||||
$fm = @{}; $bad = $false
|
||||
for ($i = 1; $i -lt $end; $i++) {
|
||||
$line = $lines[$i]; $stripped = $line.Trim()
|
||||
if ($stripped -eq '' -or $stripped.StartsWith('#')) { continue }
|
||||
if ($line -match '^\s') { $bad = $true; break }
|
||||
if ($stripped -notmatch ':') { $bad = $true; break }
|
||||
$idx = $stripped.IndexOf(':')
|
||||
$fm[$stripped.Substring(0, $idx).Trim()] = Unquote $stripped.Substring($idx + 1)
|
||||
}
|
||||
if ($bad) { $malformed++; continue }
|
||||
if (-not $fm.ContainsKey('type') -or [string]::IsNullOrWhiteSpace($fm['type'])) { $malformed++; continue }
|
||||
$body = ($lines | Select-Object -Skip ($end + 1)) -join "`n"
|
||||
|
||||
# ---- freshness ----------------------------------------------------
|
||||
$win = $null
|
||||
if ($fm.ContainsKey('freshness_window_days') -and $fm['freshness_window_days'] -match '^\s*\d+\s*$') { $win = [int]$fm['freshness_window_days'] }
|
||||
$updRaw = if ($fm.ContainsKey('last_updated')) { $fm['last_updated'] } else { '' }
|
||||
$upd = if ($updRaw -ne '') { Parse-Date $updRaw } else { $null }
|
||||
if ($updRaw -ne '' -and $null -eq $upd) { $stale++ }
|
||||
elseif ($null -ne $win -and $null -ne $upd) {
|
||||
if (($todayDate - $upd).Days -gt $win) { $stale++ }
|
||||
}
|
||||
|
||||
# ---- source fingerprints -----------------------------------------
|
||||
$secStart = -1; $bodyLines = $body -split "`n"
|
||||
for ($i = 0; $i -lt $bodyLines.Count; $i++) { if ($bodyLines[$i] -match '^## Sources\s*$') { $secStart = $i; break } }
|
||||
if ($secStart -lt 0) { continue }
|
||||
$section = @()
|
||||
for ($i = $secStart + 1; $i -lt $bodyLines.Count; $i++) { if ($bodyLines[$i] -match '^## ') { break }; $section += $bodyLines[$i] }
|
||||
$bullets = $section | Where-Object { $_ -match '^\s*[-*]\s+`([^`]+)`(.*)$' }
|
||||
if (-not $bullets) { $drift++; continue }
|
||||
foreach ($b in $bullets) {
|
||||
if ($b -notmatch '^\s*[-*]\s+`([^`]+)`(.*)$') { continue }
|
||||
$cited = $Matches[1].Trim(); $rest = $Matches[2]
|
||||
if ($cited -match '^[a-z][a-z0-9+.-]*://') { continue }
|
||||
$target = Join-Path $root $cited.TrimStart('/')
|
||||
if (-not (Test-Path -LiteralPath $target)) { $target = Join-Path (Join-Path $root $tree) $cited.TrimStart('/') }
|
||||
# A cited subtree is legal but has no single digest to recompute.
|
||||
if (Test-Path -LiteralPath $target -PathType Container) { continue }
|
||||
if (-not (Test-Path -LiteralPath $target -PathType Leaf)) { $drift++; continue }
|
||||
if ($rest -notmatch '\b(sha256|etag|mtime):([^\s,)]+)') { $drift++; continue }
|
||||
if ($Matches[1] -ne 'sha256') { continue }
|
||||
$recorded = $Matches[2].ToLowerInvariant()
|
||||
# Under 6 hex characters a prefix proves nothing; lint_report.py says so too.
|
||||
if ($recorded.Length -lt 6) { $drift++; continue }
|
||||
try { $bytes = [IO.File]::ReadAllBytes((Resolve-Path -LiteralPath $target).Path) } catch { $drift++; continue }
|
||||
# Git may convert line endings on checkout (core.autocrlf): match the
|
||||
# file as stored, with LF or with CRLF endings. Latin-1 maps bytes 1:1.
|
||||
$latin = [Text.Encoding]::GetEncoding(28591)
|
||||
$asIs = $latin.GetString($bytes); $lf = $asIs.Replace("`r`n", "`n"); $crlf = $lf.Replace("`n", "`r`n")
|
||||
$hasher = [Security.Cryptography.SHA256]::Create(); $ok = $false
|
||||
foreach ($v in @($asIs, $lf, $crlf)) {
|
||||
$hex = -join ($hasher.ComputeHash($latin.GetBytes($v)) | ForEach-Object { $_.ToString('x2') })
|
||||
if ($hex.StartsWith($recorded)) { $ok = $true; break }
|
||||
}
|
||||
if (-not $ok) { $drift++ }
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
# ---- secrets: a reduced pattern set (lint_report.py knows more shapes) ----
|
||||
$secretRe = '-----BEGIN ([A-Z0-9]+ )*PRIVATE KEY-----|(AKIA|ASIA)[0-9A-Z]{16}|gh[pousr]_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{50,}|xox[abprs]-[A-Za-z0-9-]{10,}|sk-(ant-|proj-)?[A-Za-z0-9_-]{20,}|AIza[0-9A-Za-z_-]{35}'
|
||||
$secretExt = @('.md','.txt','.eml','.csv','.json','.jsonl','.yaml','.yml','.html','.log','.env','.ini','.toml','.sh','.py','.js','.ts','.xml')
|
||||
$allow = @{}
|
||||
$allowMatch = @() # `<glob> match:<hash>`: one matched string, every matching file
|
||||
if (Test-Path -LiteralPath ".secrets-allow" -PathType Leaf) {
|
||||
foreach ($a in (Get-Content -LiteralPath ".secrets-allow")) {
|
||||
$parts = (($a -split '#', 2)[0]).Trim() -split '\s+'
|
||||
if ($parts.Count -ne 2) { continue }
|
||||
if ($parts[1] -like 'match:*') { $allowMatch += ,@($parts[0].TrimStart('/'), $parts[1].Substring(6).ToLowerInvariant()); continue }
|
||||
$allow["$($parts[0].TrimStart('/')) $($parts[1].ToLowerInvariant())"] = $true
|
||||
}
|
||||
}
|
||||
$sha = [Security.Cryptography.SHA256]::Create()
|
||||
$secrets = 0
|
||||
foreach ($top in @("wiki", "outputs", "workload", "raw")) {
|
||||
if (-not (Test-Path -LiteralPath $top -PathType Container)) { continue }
|
||||
foreach ($file in (Get-ChildItem -LiteralPath $top -Recurse -File | Sort-Object FullName)) {
|
||||
if ($secretExt -notcontains $file.Extension.ToLowerInvariant()) { continue }
|
||||
$rel = $file.FullName.Substring($root.Length).TrimStart('\', '/') -replace '\\', '/'
|
||||
if ($rel -match '^outputs/(starlight|okf|teaching)/') { continue }
|
||||
if (($rel -split '/') | Where-Object { $_.StartsWith('.') }) { continue }
|
||||
foreach ($line in ([IO.File]::ReadAllText($file.FullName) -split "`n")) {
|
||||
if ($top -eq "wiki" -and $line -match '(?i)<private>') { $secrets++ }
|
||||
if ($line -cnotmatch $secretRe) { continue }
|
||||
$bytes = [Text.Encoding]::UTF8.GetBytes($line.Trim())
|
||||
$h = (-join ($sha.ComputeHash($bytes) | ForEach-Object { $_.ToString("x2") })).Substring(0, 8)
|
||||
if ($allow.ContainsKey("$rel $h")) { continue }
|
||||
$m = [regex]::Match($line, $secretRe).Value
|
||||
$mh = (-join ($sha.ComputeHash([Text.Encoding]::UTF8.GetBytes($m)) | ForEach-Object { $_.ToString("x2") })).Substring(0, 8)
|
||||
if ($allowMatch | Where-Object { $_[1] -eq $mh -and $rel -like $_[0] }) { continue }
|
||||
$secrets++
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
$flagged = @()
|
||||
if ($malformed) { $flagged += "$malformed malformed" }
|
||||
if ($stale) { $flagged += "$stale past freshness window" }
|
||||
if ($drift) { $flagged += "$drift source drift" }
|
||||
if ($secrets) { $flagged += "$secrets possible secrets" }
|
||||
$note = " (fallback: crux quotes and context budget not checked — install Python for the full check)"
|
||||
if ($flagged.Count -eq 0) { Write-Output "ckb check: clean$note"; exit 0 }
|
||||
Write-Output ("ckb check: " + ($flagged -join ", ") + " — run `"lint`" for detail" + $note)
|
||||
exit 1
|
||||
|
|
@ -51,7 +51,6 @@ LIBS = REPO_ROOT / "libs"
|
|||
RESERVED = {"index.md", "log.md"}
|
||||
DEFAULT_REFRESH_DAYS = 30
|
||||
DECISION_STATUSES = {"proposed", "accepted", "rejected", "superseded", "reversed"}
|
||||
DECISION_OUTCOMES = {"met", "partly", "missed", "unclear"}
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
|
|
@ -320,32 +319,15 @@ def check_decisions(docs, root, today):
|
|||
if not doc.fm.get("decided_by", "").strip():
|
||||
findings.append(f"{rel}: no `decided_by` — record `unknown` rather than omitting it")
|
||||
|
||||
# Expected vs observed outcome (schema 1.8): a review is done once
|
||||
# `outcome_checked` is on or after `review_on`.
|
||||
outcome = doc.fm.get("outcome", "").strip().lower()
|
||||
if outcome and outcome not in DECISION_OUTCOMES:
|
||||
findings.append(
|
||||
f"{rel}: `outcome: {outcome}` is not one of {', '.join(sorted(DECISION_OUTCOMES))}"
|
||||
)
|
||||
checked_raw = doc.fm.get("outcome_checked")
|
||||
checked = as_date(checked_raw) if checked_raw else None
|
||||
if checked_raw and checked is None:
|
||||
findings.append(f"{rel}: `outcome_checked` is not a YYYY-MM-DD date: {checked_raw!r}")
|
||||
if checked and not outcome:
|
||||
findings.append(f"{rel}: `outcome_checked` set but no `outcome`")
|
||||
expected = doc.fm.get("expected_outcome", "").strip()
|
||||
|
||||
review = doc.fm.get("review_on")
|
||||
if review:
|
||||
review_date = as_date(review)
|
||||
if review_date is None:
|
||||
findings.append(f"{rel}: `review_on` is not a YYYY-MM-DD date: {review!r}")
|
||||
elif review_date <= today and not (checked and checked >= review_date):
|
||||
elif review_date <= today:
|
||||
findings.append(
|
||||
f"{rel}: due for review — `review_on: {review_date.isoformat()}` "
|
||||
f"passed {(today - review_date).days}d ago"
|
||||
+ ("; check `expected_outcome` against what happened and record `outcome`"
|
||||
if expected else "")
|
||||
)
|
||||
|
||||
# Supersession links must resolve and must be reciprocal.
|
||||
|
|
|
|||
|
|
@ -18,7 +18,6 @@ What it prints, one line each (plus the tail of the latest workload note):
|
|||
threads: N open ... unticked `- [ ]` under "Open threads" in workload/ notes; only when any
|
||||
profile: workload/profiles/<slug>.md the session identity's own profile, printed; only when it exists
|
||||
lessons: N new in wiki/lessons.md KB lessons dated after your previous workload note; only when any
|
||||
upstream lessons: N in linked/<name>/... the same for each linked KB's lessons, read-only, ranked below local ones
|
||||
workload: <file> (last block follows) latest workload/ note by filename date
|
||||
|
||||
Exit 0 unless the repo root is not a KB. Python 3.8+, standard library only.
|
||||
|
|
@ -270,46 +269,23 @@ def profile_lines(root, slug):
|
|||
"project rules leave room"] + [" " + l if l else "" for l in body]
|
||||
|
||||
|
||||
def read_lessons(path):
|
||||
"""(date, rule) for each lesson heading, skipping struck-through ones
|
||||
(`~~rule~~ — dropped/merged …`): those stay on the record but are not
|
||||
advice any more."""
|
||||
if not path.is_file():
|
||||
return []
|
||||
found = LESSON_RE.findall(path.read_text(encoding="utf-8-sig", errors="replace"))
|
||||
return [(d, t) for d, t in found if not t.startswith("~~")]
|
||||
|
||||
|
||||
def previous_note(root, slug, today):
|
||||
"""Date of this person's latest workload note before today, or None."""
|
||||
if not slug or not (root / "workload").is_dir():
|
||||
return None
|
||||
dates = [f.name[:10] for f in (root / "workload").glob(f"*_{slug}_summary.md") if f.name[:10] < today.isoformat()]
|
||||
return max(dates) if dates else None
|
||||
|
||||
|
||||
def lessons_lines(root, slug, today):
|
||||
"""KB lessons dated after this person's previous workload note (all of them
|
||||
on a first session), so a lesson someone else recorded is not missed; then
|
||||
the same for each linked KB's lessons, marked upstream (prior experience
|
||||
from another setting, ranked below every local lesson)."""
|
||||
prev = previous_note(root, slug, today)
|
||||
on a first session), so a lesson someone else recorded is not missed."""
|
||||
path = root / "wiki" / "lessons.md"
|
||||
if not path.is_file():
|
||||
return []
|
||||
lessons = LESSON_RE.findall(path.read_text(encoding="utf-8-sig", errors="replace"))
|
||||
prev = None
|
||||
if slug and (root / "workload").is_dir():
|
||||
dates = [f.name[:10] for f in (root / "workload").glob(f"*_{slug}_summary.md") if f.name[:10] < today.isoformat()]
|
||||
prev = max(dates) if dates else None
|
||||
new = [(d, t) for d, t in lessons if prev is None or d > prev]
|
||||
if not new:
|
||||
return []
|
||||
since = f"since your note of {prev}" if prev else "— first session here"
|
||||
out = []
|
||||
new = [(d, t) for d, t in read_lessons(root / "wiki" / "lessons.md") if prev is None or d > prev]
|
||||
if new:
|
||||
out.append(f"lessons: {len(new)} in wiki/lessons.md {since} -> read the ones that bear on this session")
|
||||
out += [f" - {d} — {t}" for d, t in new[-THREADS_SHOWN:]]
|
||||
linked = root / "linked"
|
||||
if linked.is_dir():
|
||||
for kb in sorted(p for p in linked.iterdir() if p.is_dir()):
|
||||
up = [(d, t) for d, t in read_lessons(kb / "wiki" / "lessons.md") if prev is None or d > prev]
|
||||
if not up:
|
||||
continue
|
||||
rel = f"linked/{kb.name}/wiki/lessons.md"
|
||||
out.append(f"upstream lessons: {len(up)} in {rel} {since} -> another KB's experience; "
|
||||
"local lessons win; check its Context before relying on one")
|
||||
out += [f" - {d} — {t}" for d, t in up[-THREADS_SHOWN:]]
|
||||
out = [f"lessons: {len(new)} in wiki/lessons.md {since} -> read the ones that bear on this session"]
|
||||
out += [f" - {d} — {t}" for d, t in new[-THREADS_SHOWN:]]
|
||||
return out
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -56,7 +56,7 @@ Find `.agents/modules/<name>/module.yaml`. If the name doesn't match, list what'
|
|||
actually in `.agents/modules/` rather than guessing at a near-miss.
|
||||
|
||||
Read the manifest: `skills`, `scaffold`, `agents_fragment`, `gitignore_fragment`,
|
||||
`schema_additions`, `depends_on`, `requires_kb_schema`, `default_config`.
|
||||
`schema_additions`, `depends_on`, `requires_kb_schema`.
|
||||
|
||||
### Step 2 — Check preconditions, and report them before writing anything
|
||||
|
||||
|
|
@ -110,10 +110,7 @@ Both patches are wrapped in markers so uninstall is exact:
|
|||
|
||||
### Step 5 — Record, log, report
|
||||
|
||||
- Add the module to `ckb.yaml` with its version and today's date. If the
|
||||
manifest has `default_config`, write it as the entry's `config:`. On a
|
||||
reinstall, keep the existing `config:` and add only keys it lacks: the
|
||||
user may have changed the values since.
|
||||
- Add the module to `ckb.yaml` with its version and today's date.
|
||||
- Log to `wiki/log.md` per Rule B **only** for the `wiki/index.md` change — the
|
||||
rest is template layer, not wiki content.
|
||||
- Append to `workload/YYYY-MM-DD_<author>_summary.md` per Rule D.
|
||||
|
|
|
|||
|
|
@ -73,17 +73,9 @@ most, offer once: "Want me to keep that as a lesson?"
|
|||
- **Why:** <what went wrong or what the person said>
|
||||
- **Applies when:** <the situations it covers>
|
||||
- **Scope:** person | KB
|
||||
- **Context:** <agent/model>, template <VERSION>[, <the setting: project, kind of source, task>]
|
||||
- **Recorded by:** Name
|
||||
```
|
||||
|
||||
**Context** records the situation the lesson was learned in: the agent and
|
||||
model the session ran under (`unknown` if you cannot tell), the template
|
||||
`VERSION`, and, when it matters, the project or kind of material. A lesson
|
||||
learned while one model kept skipping a step may not hold for the next
|
||||
model. Without this line there is no way to tell which lessons to
|
||||
recheck after a change.
|
||||
|
||||
Ask which scope when it is not obvious:
|
||||
|
||||
- **Person** — how this person likes to work. Append to `## Lessons` in
|
||||
|
|
@ -101,34 +93,6 @@ Suggest that once; do not edit `AGENTS.md` from here.
|
|||
The session-start brief lists KB lessons dated after the person's previous
|
||||
workload note. Read the ones that bear on the task.
|
||||
|
||||
**How to apply a lesson.** A lesson is prior experience, not a rule of the
|
||||
same rank as `AGENTS.md`:
|
||||
|
||||
- Check its **Context** against the current session. The same model,
|
||||
template major version and kind of task means it applies as written. A
|
||||
different one means it is a strong hint: follow it unless the current
|
||||
evidence says otherwise, and if it turns out not to hold, say so and offer
|
||||
to strike it through or narrow its **Applies when**.
|
||||
- A lesson with no **Context** line (recorded before schema 1.8) is read
|
||||
as context unknown.
|
||||
- When two lessons conflict, the one whose context is closer to the
|
||||
current session wins. Mention the conflict once and offer to merge or
|
||||
narrow them.
|
||||
|
||||
**Upstream lessons.** The brief also lists lessons from `linked/<name>/wiki/lessons.md`,
|
||||
marked `upstream`. They are read-only (Rule A) and rank below every local
|
||||
lesson. They describe another KB's setting, so apply them as above with the
|
||||
context treated as different. To make one local, on request ("adopt that
|
||||
lesson"), copy it into `wiki/lessons.md` with today's date and one extra
|
||||
line, `- **Carried from:** linked/<name>, recorded there YYYY-MM-DD`, then
|
||||
set `review: needs_update` and log it like any KB lesson. `ckb-init`
|
||||
carries lessons into a new KB the same way.
|
||||
|
||||
**Merging**: when two lessons say the same thing, keep the older one, add
|
||||
`- **Also recorded:** YYYY-MM-DD (merged)` to it, and strike through the
|
||||
newer one with `~~rule~~ — merged into "<older rule>" YYYY-MM-DD`. Both
|
||||
stay, so a link or log entry naming either still finds it.
|
||||
|
||||
**Forgetting**: a lesson is never deleted silently. Strike it through
|
||||
(`~~rule~~ — dropped YYYY-MM-DD: why`) so the record survives. A KB lesson
|
||||
change is logged under Rule B.
|
||||
|
|
|
|||
|
|
@ -53,7 +53,7 @@ each match) and ask the user to remove the secret, allowlist a harmless
|
|||
match (`ckb-lint` check 15), or commit anyway. Commit anyway only on an
|
||||
explicit "commit anyway" for these findings — a secret that reaches `origin`
|
||||
has to be rotated, not just deleted. Without Python, run
|
||||
`bash .agents/skills/ckb-lint/scripts/lint_quick.sh` (Git Bash on Windows) and
|
||||
`bash .agents/skills/ckb-lint/scripts/lint_quick.sh` (or the `.ps1`) and
|
||||
treat a `possible secrets` count the same way.
|
||||
|
||||
### Step 1b — Nested source repos (`software` module only)
|
||||
|
|
|
|||
|
|
@ -75,17 +75,12 @@ convention was effectively tracking.
|
|||
|---|---|---|
|
||||
| `main` | **Stable.** The released template. | Everyone, by default. |
|
||||
| `test` | **Release candidate.** Validated before merging to `main`. | Anyone helping validate a release, or needing a landed-but-unshipped fix. |
|
||||
| `experimental` | **Preview.** Work merged from `dev` early; may be broken or reverted. | People developing the template itself. |
|
||||
| `experimental` | **Development.** Active work; may be broken or reverted. | People developing the template itself. |
|
||||
| `1.x` | **Maintenance.** The 1.x line after 2.0: fixes only; the last line with PowerShell support. | KBs that need PowerShell, or can't move to 2.0 yet. |
|
||||
|
||||
`dev` is the template's integration branch, not a channel: `VERSION` changes
|
||||
only when `dev` is merged into another branch (D-0022), so a comparison
|
||||
against `dev` never finds anything newer. If a user asks for `dev`, say so and
|
||||
offer `experimental`, the earliest channel that carries a version.
|
||||
|
||||
A user switches channel by saying so: "upgrade from the test branch", "check
|
||||
experimental for updates", "switch this KB to the stable channel", "I want
|
||||
the bleeding edge". A branch named in the request **overrides** `ckb.yaml` for
|
||||
the dev version". A branch named in the request **overrides** `ckb.yaml` for
|
||||
this run, and — once the upgrade is actually applied — is written back to
|
||||
`ckb.yaml` so the next run stays on the channel the user chose. Do not write
|
||||
it back on a run the user cancelled: they asked to *look*, not to move.
|
||||
|
|
@ -122,6 +117,13 @@ local_v=$(cat VERSION 2>/dev/null || echo 0.0.0); remote_v=$(cat tmp/ckb-upgrade
|
|||
[[ "$local_v" != "$remote_v" && "$(printf '%s\n' "$local_v" "$remote_v" | sort -V | tail -n1)" == "$remote_v" ]] && echo newer || echo same-or-older
|
||||
```
|
||||
|
||||
```powershell
|
||||
# PowerShell — [version] compares component-wise
|
||||
$l = [version](Get-Content VERSION -ErrorAction SilentlyContinue | Select-Object -First 1); if (-not $l) { $l = [version]"0.0.0" }
|
||||
$r = [version](Get-Content tmp/ckb-upgrade-src/VERSION | Select-Object -First 1)
|
||||
if ($r -gt $l) { "newer" } else { "same-or-older" }
|
||||
```
|
||||
|
||||
No Python needed for this step; with only two numbers to compare, doing it
|
||||
by eye is acceptable too.
|
||||
|
||||
|
|
@ -429,22 +431,6 @@ template's scaffold if it is missing, and add its routing row to
|
|||
`wiki/index.md`. Topic pages themselves are never generated by a migration;
|
||||
`ckb-consolidate` proposes and builds them on request.
|
||||
|
||||
**b5. Schema 1.7 → 1.8: outcomes, attempts, lesson context.** Every 1.8
|
||||
addition is optional (D-0023), so a 1.7 page is already a valid 1.8 page.
|
||||
- **`wiki/error-book.md`** — if it holds the old single table with rows,
|
||||
put the table, unchanged, under an `## Earlier entries` heading. Then add
|
||||
the 1.8 entry-format comment above it from the template's scaffold, and
|
||||
update the `tldr`. Never convert old rows into problem entries: an
|
||||
attempt's expected result was never written down, and making one up now
|
||||
would be hindsight presented as a prediction. An empty table is replaced
|
||||
by the scaffold.
|
||||
- **Decisions** — do not backfill `expected_outcome`. Offer once: "N
|
||||
decisions have a `review_on` and no expected outcome. Want to add one to
|
||||
each? It will be marked `(added <today>)`." Apply only on a yes, one
|
||||
decision at a time with the user's wording.
|
||||
- **Lessons** — do not backfill **Context**; a lesson without one is read
|
||||
as context unknown (`ckb-profile`).
|
||||
|
||||
**c. Bump `wiki/index.md`'s `kb_schema_version`** to the template's
|
||||
current value, once every page has been checked.
|
||||
|
||||
|
|
|
|||
|
|
@ -20,8 +20,8 @@ run hits an unusual situation the main steps don't cover.
|
|||
separately-confirmed operation.
|
||||
- **Template repo is this very repo** (the template project upgrading
|
||||
itself) — the comparison is between branches of one repo rather than
|
||||
between two repos. That's valid, and the usual flow is `dev` → `experimental`
|
||||
→ `test` → `main` (or `dev` → `test` → `main`, or `dev` → `main`; D-0022); but say plainly that this is a self-upgrade, since the
|
||||
between two repos. That's valid, and the usual flow is `experimental` →
|
||||
`test` → `main`; but say plainly that this is a self-upgrade, since the
|
||||
"local vs upstream" framing in the report reads oddly otherwise.
|
||||
|
||||
- **No `VERSION` file locally** — treat local version as `0.0.0`; any real
|
||||
|
|
|
|||
22
AGENTS.md
22
AGENTS.md
|
|
@ -187,14 +187,12 @@ evidence: follow it to its members before grounding an answer.
|
|||
|
||||
Pages with `type: decision` live in `wiki/decisions/` as `NNNN-slug.md` and
|
||||
add `status` (`proposed`/`accepted`/`rejected`/`superseded`/`reversed`),
|
||||
`decided_on`, `decided_by`, and optionally `affects`, `review_on` and
|
||||
`expected_outcome` (what the decision should change, written when it is made,
|
||||
checked at review into `outcome`/`outcome_checked`). They are
|
||||
`decided_on`, `decided_by`, and optionally `affects` and `review_on`. They are
|
||||
append-only: never rewrite a decision's substance to match a later change of
|
||||
mind — record a new decision that supersedes it, and set both
|
||||
`supersedes` and `superseded_by`. `ckb-decide` owns the format.
|
||||
|
||||
`wiki/index.md` alone also carries `kb_schema_version`, currently `"1.8"`
|
||||
`wiki/index.md` alone also carries `kb_schema_version`, currently `"1.7"`
|
||||
for the base contract. An installed module may raise it additively by
|
||||
declaring `requires_kb_schema` and contributing optional types and fields;
|
||||
`ckb-module` applies that bump at install time. Detailed schema migration
|
||||
|
|
@ -254,10 +252,8 @@ Disambiguation, only where the table alone is ambiguous:
|
|||
and stays with `ckb-upgrade`.
|
||||
- `ckb-upgrade` also takes a request naming a release channel. The template repo
|
||||
keeps `main` (stable), `test` (release candidate), `experimental`
|
||||
(preview) and `1.x` (maintenance of the 1.x line); which branch this
|
||||
(development) and `1.x` (maintenance of the 1.x line); which branch this
|
||||
KB tracks lives in `ckb.yaml`'s `template:` block and defaults to `main`.
|
||||
`dev` is where template work lands; it never moves `VERSION`, so it is not
|
||||
a channel a KB can track (D-0022).
|
||||
- `ckb-reset` deletes accumulated knowledge, so it always shows an inventory and
|
||||
takes a typed confirmation first, and never touches the template layer or `src/`.
|
||||
|
||||
|
|
@ -271,14 +267,13 @@ Windows normally has `python` or `py`, never `python3`.
|
|||
|
||||
If none is found, say so **once**, point to the "Prerequisites" section of
|
||||
`docs/MANUAL.md` (per-OS install steps), and use the degraded path the
|
||||
skill documents — `ckb-lint` has a bash fallback for the quick
|
||||
check (Git Bash on Windows) and a manual checklist, `ckb-retrieve` falls back to index-first
|
||||
skill documents — `ckb-lint` has a bash/PowerShell fallback for the quick
|
||||
check and a manual checklist, `ckb-retrieve` falls back to index-first
|
||||
navigation plus `grep`, `ckb-ingest` compares `sha256sum` digests by hand,
|
||||
`ckb-add-conversation` copies the transcript with `cp` and skips the
|
||||
Markdown rendering. The two exporters have no fallback and stop.
|
||||
Never retry a failed interpreter on every call, and never install
|
||||
anything without asking. Every script the template and its modules ship is
|
||||
Python; a module may need other tools, never another script language.
|
||||
anything without asking.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -391,8 +386,9 @@ Act only on lines that ask for it, and stay quiet about anything clean:
|
|||
names is run by hand, mark that routine too. `ckb-routine` owns the details.
|
||||
|
||||
Without Python, say so once and do the same by hand: `git status --short
|
||||
--branch`, `bash .agents/skills/ckb-lint/scripts/lint_quick.sh` (Git Bash
|
||||
on Windows; four of the six quick checks, crux quotes and budget skipped), the last
|
||||
--branch`, `bash .agents/skills/ckb-lint/scripts/lint_quick.sh` (or
|
||||
`powershell -ExecutionPolicy Bypass -File .agents/skills/ckb-lint/scripts/lint_quick.ps1`
|
||||
on Windows — four of the six quick checks, crux quotes and budget skipped), the last
|
||||
block of the latest `workload/` note by filename date, and skip the routine
|
||||
check.
|
||||
|
||||
|
|
|
|||
46
README.md
46
README.md
|
|
@ -32,12 +32,7 @@ PDFs and video transcripts into `raw/inbox/`, the optional `capture` module
|
|||
saves each as a dated, untrusted-marked snapshot. To send a document to
|
||||
another KB, the optional `share` module uses a shared git repo with one
|
||||
mailbox per KB; the receiver takes it into `raw/inbox/` and ingests it as
|
||||
usual. To write everything the KB sends out in your team's voice, the
|
||||
optional `voice` module rewrites kept answers, documents and reports from a
|
||||
voice profile kept as a wiki page, without touching facts, quotes or
|
||||
sources. To hand a document over as a Word file or a PDF, the optional
|
||||
`convert` module runs pandoc with a house style kept in `templates/styles/`,
|
||||
built from a few settings or from your company's Word template. Every module has its
|
||||
usual. Every module has its
|
||||
own README in both languages under `.agents/modules/<name>/`.
|
||||
|
||||
For the page schema in full, and for how both version numbers got where they
|
||||
|
|
@ -47,22 +42,14 @@ Why the template is shaped the way it is - its own design decisions - is in
|
|||
|
||||
### Release channels
|
||||
|
||||
The template repo keeps four release branches, plus `dev`, where work lands. They are not interchangeable:
|
||||
The template repo keeps four branches. They are not interchangeable:
|
||||
|
||||
| Branch | What it is | Who should track it |
|
||||
|---|---|---|
|
||||
| `main` | **Stable** - the released template | Everyone, by default |
|
||||
| `test` | **Release candidate** - validated before merging to `main` | Anyone helping validate a release, or needing a landed-but-unshipped fix |
|
||||
| `experimental` | **Preview** - work merged from `dev` early, may be broken or reverted | People developing the template itself |
|
||||
| `experimental` | **Development** - active work, may be broken or reverted | People developing the template itself |
|
||||
| `1.x` | **Maintenance** - the 1.x line after 2.0: fixes only; the last line with PowerShell support | KBs that need PowerShell, or can't move to 2.0 yet |
|
||||
| `dev` | **Integration** - where every change lands first; `VERSION` never changes here | Nobody: not a channel (an upgrade from it finds nothing newer) |
|
||||
|
||||
The version changes only when `dev` is merged into another branch, never on
|
||||
`dev` itself. Changes travel `dev` → `experimental` → `test` → `main`,
|
||||
`dev` → `test` → `main`, or `dev` → `main`; a version keeps its number as it
|
||||
moves along. What each number position means is unchanged: major for
|
||||
breaking changes, minor for features, patch for fixes. See
|
||||
[D-0022](docs/decisions/0022-dev-branch-and-merge-versioning.md).
|
||||
|
||||
Both `ckb-init` and `ckb-upgrade` default to `main`. To use another channel,
|
||||
say which: *"initialize from the test branch"*, *"check experimental for
|
||||
|
|
@ -262,12 +249,7 @@ with them), printed into their own session-start brief and nobody else's.
|
|||
"Remember this" or "lesson: …" records a lesson: a personal one in the
|
||||
profile, a KB-wide one in `wiki/lessons.md`, which waits for a second
|
||||
person's review. Precedence is `AGENTS.md`, then a project's `## Rules`, then
|
||||
the profile. Each lesson records the context it was learned in (agent/model,
|
||||
template version), so after a model or template change the agent rechecks
|
||||
it instead of treating it as settled. Lessons from KBs under `linked/`
|
||||
appear in the brief as upstream, ranked below local ones, and a new KB can
|
||||
start with lessons carried from the one that created it. Skill:
|
||||
`.agents/skills/ckb-profile/SKILL.md`.
|
||||
the profile. Skill: `.agents/skills/ckb-profile/SKILL.md`.
|
||||
|
||||
### Kept Answers
|
||||
An answer that took real work can be kept on request in
|
||||
|
|
@ -292,10 +274,6 @@ what was decided, `decided_by` whom, `decided_on` what date, why, the
|
|||
alternatives that lost, and what it `affects`. A `status` field
|
||||
(`proposed`/`accepted`/`rejected`/`superseded`/`reversed`) says whether it is
|
||||
actually in force, and an optional `review_on` date marks it for revisiting.
|
||||
An optional `expected_outcome`, written when the decision is made, says what
|
||||
it should change; at review the agent records what actually happened
|
||||
(`outcome: met/partly/missed/unclear`) in an appended `## Outcome`, and a
|
||||
`## Tried` section keeps what was built or tested and dropped on the way.
|
||||
|
||||
Decision pages are **append-only**. When the choice changes, a *new* decision
|
||||
supersedes the old one - `supersedes`/`superseded_by` are set on both sides,
|
||||
|
|
@ -307,7 +285,7 @@ Postgres, and before that MySQL, changed in September because of reporting".
|
|||
"what decisions touch Y" are direct lookups. The `ckb-decide` skill records
|
||||
decisions and answers questions about them; `ckb-lint` checks their structure
|
||||
(status vocabulary, required dates, two-sided supersession, unique numbers,
|
||||
overdue reviews, unrecorded outcomes).
|
||||
overdue reviews).
|
||||
|
||||
### Query Gaps
|
||||
If the cascade cannot answer a question, the agent records or proposes a
|
||||
|
|
@ -374,7 +352,7 @@ source or it doesn't. `## Notes` is the inverse guarantee - on pages the agent
|
|||
regenerates (connector indexes, code maps), it is the one place an annotation
|
||||
survives the next rebuild.
|
||||
|
||||
`wiki/index.md` alone also carries `kb_schema_version` (currently `"1.8"`), declaring
|
||||
`wiki/index.md` alone also carries `kb_schema_version` (currently `"1.7"`), declaring
|
||||
which revision of this schema the wiki was authored against - bump minor for
|
||||
additive optional fields, major for breaking changes.
|
||||
|
||||
|
|
@ -500,12 +478,8 @@ source citations, and consistency with the rest of the wiki. Pages below
|
|||
|
||||
### Error Book
|
||||
Systematic errors (orphan links, formatting issues, cross-page contradictions)
|
||||
are recorded in `wiki/error-book.md`, one entry per recurring problem. Each
|
||||
entry names the suspected root cause and keeps every fix tried against it:
|
||||
what changed, what it was expected to stop (written before the result was
|
||||
known), what later lint runs actually saw, and the model and template
|
||||
version it ran under. Fixes that did not hold stay on the record, so the
|
||||
same fix is not tried again blind. Two-layer repair:
|
||||
are recorded in `wiki/error-book.md` with root cause, applied fix, and a
|
||||
reusable constraint to prevent recurrence. Two-layer repair:
|
||||
- **Layer 1** - deterministic auto-fix for structural issues
|
||||
- **Layer 2** - agent reasoning pass for semantic/cross-page issues
|
||||
|
||||
|
|
@ -696,8 +670,8 @@ goes into `wiki/query-gaps.md` only on your yes. See
|
|||
## Quick Start
|
||||
|
||||
0. **Optional: install Python 3.8+.** Eight skills run a stdlib-only Python
|
||||
script; without it the session-start check falls back to a bash
|
||||
script (Git Bash on Windows), lint and retrieval run in a slower manual mode, and the exporters
|
||||
script; without it the session-start check falls back to a bash/PowerShell
|
||||
script, lint and retrieval run in a slower manual mode, and the exporters
|
||||
are unavailable. Per-OS steps: [docs/MANUAL.md → Prerequisites](docs/MANUAL.md#prerequisites).
|
||||
|
||||
1. **Mount upstream KBs:**
|
||||
|
|
|
|||
45
README.pl.md
45
README.pl.md
|
|
@ -35,13 +35,6 @@ w `raw/inbox/`, opcjonalny moduł `capture` zapisuje każdą jako datowany zrzut
|
|||
oznaczony jako niezaufany. Aby wysłać dokument do innej bazy, opcjonalny moduł
|
||||
`share` korzysta ze wspólnego repozytorium git z jedną skrzynką na bazę;
|
||||
odbiorca bierze dokument do `raw/inbox/` i przetwarza go zwykłym ingestem.
|
||||
Aby wszystko, co baza wysyła na zewnątrz, brzmiało głosem zespołu, opcjonalny
|
||||
moduł `voice` przepisuje zachowane odpowiedzi, dokumenty i raporty według
|
||||
profilu głosu trzymanego jako strona wiki, nie ruszając faktów, cytatów ani
|
||||
źródeł. Aby oddać dokument jako plik Worda lub PDF, opcjonalny moduł
|
||||
`convert` uruchamia pandoca ze stylem firmowym trzymanym w
|
||||
`templates/styles/`, zbudowanym z kilku ustawień albo z firmowego szablonu
|
||||
Worda.
|
||||
Każdy moduł ma własne README w obu językach w
|
||||
`.agents/modules/<nazwa>/`.
|
||||
|
||||
|
|
@ -52,22 +45,14 @@ opisuje [docs/decisions/](docs/decisions/README.md).
|
|||
|
||||
### Kanały wydawnicze
|
||||
|
||||
Repozytorium szablonu utrzymuje cztery gałęzie wydań oraz `dev`, na którą trafia praca. Nie są wymienne:
|
||||
Repozytorium szablonu utrzymuje cztery gałęzie. Nie są wymienne:
|
||||
|
||||
| Gałąź | Czym jest | Kto powinien ją śledzić |
|
||||
|---|---|---|
|
||||
| `main` | **Stabilna** — wydany szablon | Wszyscy, domyślnie |
|
||||
| `test` | **Kandydat do wydania** — walidowany przed scaleniem do `main` | Każdy, kto pomaga walidować wydanie albo potrzebuje poprawki, która weszła, ale jeszcze nie została wydana |
|
||||
| `experimental` | **Podglądowa** — zmiany scalone z `dev` wcześnie, mogą być zepsute albo wycofane | Osoby rozwijające sam szablon |
|
||||
| `experimental` | **Rozwojowa** — bieżąca praca, może być zepsuta albo wycofana | Osoby rozwijające sam szablon |
|
||||
| `1.x` | **Utrzymaniowa** — linia 1.x po wydaniu 2.0: tylko poprawki; ostatnia z obsługą PowerShella | KB, które potrzebują PowerShella albo nie mogą jeszcze przejść na 2.0 |
|
||||
| `dev` | **Integracyjna** — tu najpierw trafia każda zmiana; `VERSION` nigdy się tu nie zmienia | Nikt: to nie jest kanał (upgrade z niej nie znajdzie nic nowszego) |
|
||||
|
||||
Wersja zmienia się tylko przy scaleniu `dev` do innej gałęzi, nigdy na samej
|
||||
`dev`. Zmiany idą `dev` → `experimental` → `test` → `main`,
|
||||
`dev` → `test` → `main` albo `dev` → `main`; wersja zachowuje swój numer po
|
||||
drodze. Znaczenie pozycji numeru się nie zmienia: główna dla zmian
|
||||
łamiących, poboczna dla funkcji, poprawkowa dla poprawek. Zobacz
|
||||
[D-0022](docs/decisions/0022-dev-branch-and-merge-versioning.md).
|
||||
|
||||
Zarówno `ckb-init`, jak i `ckb-upgrade` domyślnie używają `main`. Żeby użyć
|
||||
innego kanału, powiedz którego: *„zainicjuj z gałęzi test"*,
|
||||
|
|
@ -274,12 +259,8 @@ Każda osoba może mieć profil w `workload/profiles/` (rola, jak z nią
|
|||
pracować), wypisywany w podsumowaniu startu jej własnej sesji i niczyjej
|
||||
innej. „Remember this” albo „lesson: …” zapisuje lekcję: osobistą w profilu,
|
||||
dla całej KB w `wiki/lessons.md`, gdzie czeka na przegląd drugiej osoby.
|
||||
Pierwszeństwo: `AGENTS.md`, potem `## Rules` projektu, potem profil. Każda
|
||||
lekcja zapisuje kontekst, w którym powstała (agent/model, wersja szablonu),
|
||||
więc po zmianie modelu lub szablonu agent ją sprawdza, zamiast uznawać za
|
||||
pewnik. Lekcje z baz w `linked/` pojawiają się w podsumowaniu jako
|
||||
zewnętrzne, poniżej lokalnych, a nowa KB może zacząć od lekcji przeniesionych
|
||||
z bazy, która ją utworzyła. Skill: `.agents/skills/ckb-profile/SKILL.md`.
|
||||
Pierwszeństwo: `AGENTS.md`, potem `## Rules` projektu, potem profil. Skill:
|
||||
`.agents/skills/ckb-profile/SKILL.md`.
|
||||
|
||||
### Zachowane odpowiedzi
|
||||
Odpowiedź, która wymagała prawdziwej pracy, można na prośbę zachować w
|
||||
|
|
@ -307,10 +288,6 @@ ekspert to słabsze twierdzenie niż zapisany.
|
|||
(`affects`). Pole `status`
|
||||
(`proposed`/`accepted`/`rejected`/`superseded`/`reversed`) mówi, czy decyzja
|
||||
faktycznie obowiązuje, a opcjonalna data `review_on` oznacza ją do przeglądu.
|
||||
Opcjonalne `expected_outcome`, zapisane w chwili podjęcia decyzji, mówi, co
|
||||
ma ona zmienić; przy przeglądzie agent zapisuje, co faktycznie się stało
|
||||
(`outcome: met/partly/missed/unclear`) w dopisywanej sekcji `## Outcome`, a
|
||||
sekcja `## Tried` zachowuje to, co zbudowano lub przetestowano i porzucono.
|
||||
|
||||
Strony decyzji są **tylko do dopisywania**. Gdy wybór się zmienia, *nowa*
|
||||
decyzja zastępuje starą — `supersedes`/`superseded_by` ustawiane są po obu
|
||||
|
|
@ -399,7 +376,7 @@ zgadza, albo nie. `## Notes` daje odwrotną gwarancję — na stronach
|
|||
regenerowanych przez agenta (indeksy konektorów, mapy kodu) to jedyne miejsce,
|
||||
w którym adnotacja przetrwa kolejną przebudowę.
|
||||
|
||||
Sam `wiki/index.md` dodatkowo zawiera `kb_schema_version` (obecnie `"1.8"`),
|
||||
Sam `wiki/index.md` dodatkowo zawiera `kb_schema_version` (obecnie `"1.7"`),
|
||||
deklarujący, według której wersji tego schematu wiki została napisana —
|
||||
zwiększaj wersję pomniejszą dla dodatkowych opcjonalnych pól, główną dla
|
||||
zmian łamiących kompatybilność.
|
||||
|
|
@ -550,13 +527,9 @@ są oznaczane do przeglądu lub przepisywane podczas kolejnego lintowania.
|
|||
|
||||
### Księga błędów (Error Book)
|
||||
Systematyczne błędy (uszkodzone linki, problemy z formatowaniem,
|
||||
sprzeczności między stronami) są zapisywane w `wiki/error-book.md`, jeden
|
||||
wpis na powracający problem. Wpis nazywa podejrzewaną przyczynę i zachowuje
|
||||
każdą wypróbowaną naprawę: co zmieniono, czemu miało to zapobiec (zapisane,
|
||||
zanim znany był wynik), co faktycznie pokazały kolejne przebiegi lintu oraz
|
||||
model i wersję szablonu, przy których to działało. Naprawy, które nie
|
||||
zadziałały, zostają w zapisie, więc ta sama naprawa nie jest próbowana
|
||||
ponownie na ślepo. Naprawa dwuwarstwowa:
|
||||
sprzeczności między stronami) są zapisywane w `wiki/error-book.md` wraz z
|
||||
przyczyną, zastosowaną naprawą i ograniczeniem wielokrotnego użytku
|
||||
zapobiegającym powtórce. Naprawa dwuwarstwowa:
|
||||
- **Warstwa 1** — deterministyczna automatyczna naprawa problemów
|
||||
strukturalnych
|
||||
- **Warstwa 2** — przebieg rozumowania agenta dla problemów
|
||||
|
|
@ -762,7 +735,7 @@ tylko po twojej zgodzie. Zobacz `.agents/skills/ckb-feynman/SKILL.md`.
|
|||
|
||||
0. **Opcjonalnie: zainstaluj Pythona 3.8+.** Osiem skilli uruchamia skrypt
|
||||
w Pythonie (tylko biblioteka standardowa); bez niego kontrola na starcie
|
||||
sesji przechodzi na zapasowy skrypt bash (na Windows: Git Bash), lint i wyszukiwanie
|
||||
sesji przechodzi na zapasowy skrypt bash/PowerShell, lint i wyszukiwanie
|
||||
działają w wolniejszym trybie ręcznym, a eksporty są niedostępne. Kroki
|
||||
dla poszczególnych systemów: [docs/MANUAL.pl.md → Wymagania wstępne](docs/MANUAL.pl.md#wymagania-wstępne).
|
||||
|
||||
|
|
|
|||
2
VERSION
2
VERSION
|
|
@ -1 +1 @@
|
|||
2.4.0
|
||||
1.28.10
|
||||
|
|
|
|||
|
|
@ -24,24 +24,18 @@ required field, or changing an existing reserved filename convention. There
|
|||
has never been a major bump; every schema version to date has been additive,
|
||||
so any page written since 2026-07-13 is still valid today.
|
||||
|
||||
The template version follows the same rule for the tooling: **major** when
|
||||
something a KB may rely on is removed. Its first major, 2.0.0, removed
|
||||
PowerShell support. The previous major keeps getting fixes on a maintenance
|
||||
branch named after it (`1.x`), and `ckb-upgrade` never crosses a major
|
||||
without asking.
|
||||
|
||||
---
|
||||
|
||||
## Contents
|
||||
|
||||
1. [Current page schema (1.8)](#current-page-schema-kb_schema_version-18)
|
||||
1. [Current page schema (1.7)](#current-page-schema-kb_schema_version-17)
|
||||
2. [KB schema version history](#kb-schema-version-history)
|
||||
3. [Template version history](#template-version-history)
|
||||
4. [Migrating between versions](#migrating-between-versions)
|
||||
|
||||
---
|
||||
|
||||
## Current page schema (`kb_schema_version: "1.8"`)
|
||||
## Current page schema (`kb_schema_version: "1.7"`)
|
||||
|
||||
### Frontmatter — every non-reserved page
|
||||
|
||||
|
|
@ -83,10 +77,7 @@ add:
|
|||
| `decided_on` | for `accepted`/`rejected`/`reversed` | `YYYY-MM-DD`, the date the call was made. |
|
||||
| `decided_by` | when known | Comma-separated names. Where genuinely unknown, write `unknown` rather than omitting the field - "we don't know who decided this" is itself worth recording. |
|
||||
| `affects` | no | Comma-separated wiki paths this decision constrains. |
|
||||
| `review_on` | no | `YYYY-MM-DD` to revisit. Lint reports these once the date passes, until an `outcome_checked` on or after it. |
|
||||
| `expected_outcome` | no | *(1.8)* One line: what the decision should change, written when it is recorded. One added later ends with `(added YYYY-MM-DD)`. |
|
||||
| `outcome` | at review | *(1.8)* `met` / `partly` / `missed` / `unclear`, against `expected_outcome`. Validated by lint. |
|
||||
| `outcome_checked` | at review | *(1.8)* `YYYY-MM-DD` of the latest outcome review; the dated entry itself is appended to the body's `## Outcome`. |
|
||||
| `review_on` | no | `YYYY-MM-DD` to revisit. Lint reports these once the date passes. |
|
||||
|
||||
Decision records are **append-only**. A decision is never rewritten to match
|
||||
a later change of mind: record a new one that supersedes it, and both stay on
|
||||
|
|
@ -211,7 +202,7 @@ improving it (in-degree is used as a ranking signal).
|
|||
| `wiki/index.md` | 1.1 | Routing table; the only page carrying `kb_schema_version` |
|
||||
| `wiki/overview.md` | 1.1 | High-level map of the KB |
|
||||
| `wiki/log.md` | 1.1 | Reverse-chronological change log for `wiki/` |
|
||||
| `wiki/error-book.md` | 1.1 | Recurring problems (since 1.8: one entry per root cause, with every attempt, its expected and observed result and context) |
|
||||
| `wiki/error-book.md` | 1.1 | Systemic issues with root cause and fix |
|
||||
| `wiki/entities/` | 1.1 | Typed entity pages |
|
||||
| `wiki/graph/` | 1.1 | `edges.json` plus the vocabulary in `index.md` |
|
||||
| `wiki/query-gaps.md` | 1.2 | Questions the wiki could not answer, driving demand-driven ingest |
|
||||
|
|
@ -228,21 +219,6 @@ navigation stays lazy.
|
|||
|
||||
## KB schema version history
|
||||
|
||||
### 1.8 — 2026-11-18 · improvement memory
|
||||
|
||||
[D-0023](decisions/0023-improvement-memory.md), after Google's
|
||||
Self-Improvement Memory (arXiv 2611.18856). Additive:
|
||||
- **Error book by problem**: `## E<n> — <root cause>` entries with status
|
||||
and an attempts table (date, change, Expected, Observed, Context); merged
|
||||
entries stay as `## E4 → E2` aliases.
|
||||
- **Decisions**: optional `expected_outcome`, `outcome`, `outcome_checked`;
|
||||
optional body sections `## Tried` and an append-only `## Outcome`.
|
||||
- **Lessons**: a `Context:` line (agent/model, template version), optional
|
||||
`Carried from:` and `Also recorded:` lines.
|
||||
|
||||
**Migration** (`ckb-upgrade` Step 7 b5): an old error-book table is kept
|
||||
under `## Earlier entries`; nothing is backfilled.
|
||||
|
||||
### 1.7 — 2026-11-02 · topic summaries
|
||||
|
||||
[D-0016](decisions/0016-topic-summaries-and-consolidation.md). A new optional
|
||||
|
|
@ -364,20 +340,15 @@ docs. Independent of the content schema above.
|
|||
|
||||
| Version | Date | What landed | Schema |
|
||||
|---|---|---|---|
|
||||
| **2.4.0** | 2026-11-18 | Improvement memory (D-0023, schema 1.8), after Google's Self-Improvement Memory paper. **Error book** (`ckb-lint` check 9): one entry per recurring problem with every attempt, what it was expected to stop (written first), what later runs observed (`pending` → `held`/`recurred`/`partly`) and the model/template it ran under; lint fills in pending observations each run, retries a failed fix only with something new, merges entries into aliases; new scaffold. **Decisions** (`ckb-decide`): `expected_outcome` asked for when recording, a new "reviewing an outcome" procedure appending to `## Outcome` and setting `outcome`/`outcome_checked`, a `## Tried` section, and a check when a new decision picks a direction already tried or rejected. `lint_report.py` validates the outcome vocabulary, closes a due review once `outcome_checked` ≥ `review_on`, and asks for the outcome when an `expected_outcome` is set. **Lessons** (`ckb-profile`): a `Context:` line and rules for applying a lesson from another context, adopting upstream lessons, merging. `session_start.py` lists new lessons from `linked/<name>/wiki/lessons.md` as `upstream lessons:` and skips struck-through lessons. **`ckb-init`** Step 8b offers to carry lessons and error-book problems into a new KB. **`ckb-upgrade`** b5 migration. Template ADRs may carry the same fields. Deferred: a self-improvement loop over the template (needs evals). Rejected: loading the whole record into context. Tests: `tests/unit/test_sim_memory.py` | 1.8 |
|
||||
| 2.3.0 | 2026-11-12 | Branch and version flow (D-0022): a new `dev` integration branch where all work lands; `VERSION` and the changelog change only when `dev` is merged into `experimental`, `test` or `main` (paths `dev` → `experimental` → `test` → `main`, `dev` → `test` → `main`, `dev` → `main`), and a version keeps its number when promoted; `main` is merged back into `dev`, `test` and `experimental` after a release; `1.x` keeps its own fixes. `experimental` becomes the *preview* channel; `dev` is not a channel, and `ckb-init`/`ckb-upgrade` offer `experimental` when asked for it. Also **profile skills** in `user-skills/`, installed once per person rather than per KB: `ckb-create` builds a KB with the fetched template's `ckb-init`, commits on `main` and pushes to an empty remote; `ckb-join` clones a KB by URL and checks git identity, symlinks, `linked/` mounts and Python without committing. Neither is copied into a KB. Both manuals gain a section on them | 1.7 |
|
||||
| 2.2.0 | 2026-11-11 | New opt-in `convert` module (D-0021): skill `ckb-convert` and `convert.py` (stdlib; needs pandoc, LibreOffice optional). `convert` turns any KB Markdown file into `.docx`, `.odt`, PDF or HTML in a named house style, `templates/styles/<name>.docx` (pandoc's reference document; optional `<name>.odt`/`<name>.css`). PDF and ODT are made by LibreOffice from the styled `.docx` (private profile), so every format looks the same; without it PDF falls back to a pandoc PDF engine and says the style wasn't applied. The copy is cleaned for outside readers: frontmatter → title/author (no e-mail)/date/lang, a leading `# H1` → title, template comments dropped, `[[wikilinks]]` and KB-path links → text (`--keep-links`), code blocks untouched. An existing output is refused without `--force`. **Styles without fonts by hand:** `new-style` copies pandoc's default reference and sets body/heading font, size, heading colour, paper (A4/Letter) and margins in `styles.xml`, the theme and the body `sectPr` in schema order; `--from` takes a company `.docx`/`.dotx` (content type rewritten, macros refused); `edit-style`, `check-style` (styles pandoc uses that a template lacks), `styles`, `doctor`. Scaffold `templates/styles/README.md`; settings `style`, `format`, `out_dir`, `toc`, `number_sections`, `keep_links` via `default_config`; routed by the module's `AGENTS.md` block, after `ckb-voice`. Tests: `tests/unit/test_convert.py`, eval `ckb-module/install-convert`. No schema change | 1.7 |
|
||||
| 2.1.0 | 2026-11-11 | New opt-in `voice` module (D-0020): skill `ckb-voice`, no script. Every prose file written under the configured `apply_to` paths (default `outputs/answers/`, `outputs/documents/`, `outputs/reports/`, `PROJECT-OVERVIEW*`; `outputs/okf/` and `outputs/starlight/` skipped) is rewritten in a voice before it is saved, whichever skill drafted it; the hook is the module's `AGENTS.md` block, so no core skill changed for it. **Profiles are wiki pages**, `wiki/voice/<name>.md` (`type: voice-profile`, `voice_of: team/person/third-party`, Tone, Formality, Sentence style, Keep, Avoid, Audience, Opinions, Sample, `## Sources`, protected `## Notes`), created and logged by calibration from sample documents; standing preferences said in passing update one field. **Settings** in `ckb.yaml` (`mode: auto/ask/off`, `profile`, `writer`, `apply_to`, `skip`, `chat`); profile precedence: named in the request, then `voice:` on the person's `workload/profiles/` page, then the default. **Frozen spans** (frontmatter except a new `voice:` field, Sources, Crux and quotes with attributions, Notes/Rules, contradiction markers, `<private>`, code, paths, links, numbers, names, a template's headings) are diffed before writing; a vague claim is flagged, never cut. `writer:` hands the rewrite to another installed skill such as a personal `ghost-writer`, with fallback. Rules adapted from that skill. `ckb-module` reads a manifest's `default_config` into the entry's `config:` and keeps edited values on reinstall. New type `voice-profile` and field `voice`, additive, no schema bump | 1.7 |
|
||||
| 2.0.9 | 2026-11-11 | Tests only. Golden outputs for both exporters on the clean fixture: the exact file list (`tests/expected/okf-files.txt`, 15 files; `starlight-files.txt`, 17) and the summary each prints (`okf-report.txt`, `starlight-report.txt`, including the OKF conformance verdict). Content is not compared, because OKF stamps the export date. This closes the last item of the 2.0.0 script review | 1.7 |
|
||||
| 2.0.8 | 2026-11-11 | Tests only. `tests/unit/test_mcp_server.py` covers the mcp server with the MCP SDK installed (2.3.0): a confirmation code confirms exactly one write and is bound to its payload and lifetime, a wrong `kb` is refused first, `_redact` masks secrets, the allowed-hosts default and override, a foreign `Host` header gets 421 over real HTTP while the public host gets 200, and OAuth tokens signed with a real RSA key — an unverified email no longer passes an `@domain` allow list, a verified one does, `CKB_MCP_OAUTH_TRUST_EMAIL=1` opts out, wrong audience and expired tokens fail. Without the SDK the tests skip; `CKB_MCP_PYTHON=<venv>/bin/python bash tests/smoke.sh` runs them. These confirm the 2.0.4 server changes, which until now were only compiled | 1.7 |
|
||||
| 2.0.7 | 2026-11-11 | Skill evals for the destructive and stateful skills, and the fix one of them found; no new features. **`ckb-reset`:** in a KB with no git repository, Step 0 asked for "a much more explicit confirmation" without saying what, so two runs asked for two different phrases; the phrase is now named, **`reset the wiki with no restore point`**, and the plain `reset the wiki` does not count there. **Nine new eval cases**, each run once by an agent on 2026-11-11 and passing: `ckb-reset/no-confirm` (inventory, nothing deleted), `ckb-reset/confirmed` (the plain phrase refused, the strict one accepted; tier 1 gone, scaffold back, `kb_schema_version` kept, raw/template untouched), `ckb-module/install` and `ckb-module/round-trip` (`AGENTS.md`, `.gitignore`, `ckb.yaml` byte-identical after uninstall), `ckb-upgrade/major-guard` (1.28.7 → 2.x stops and asks) and `ckb-upgrade/take-major` (VERSION 2.x, `lint_quick.ps1` deleted, wiki untouched), `ckb-decide/supersede` (both links set, D-0001's text untouched), `ckb-ingest/check-in-waits` and `ckb-ingest/reviewed-page` (`needs_update`, `## Notes` byte-for-byte). **Runner:** `replies` for the operator's answers when a skill stops and waits; setup steps `template` (template files, optionally from an older git ref) and `upstream` (a local bare repo for `ckb-upgrade`); `record` saves a passing run as `reference/` with a `.deleted` list and `replay` rebuilds and checks it; the smoke test replays every reference (five today). The runner's frontmatter reader takes frontmatter closed at end of file | 1.7 |
|
||||
| 2.0.6 | 2026-11-11 | Tests, and the parser fix they found; no new features. **Frontmatter readers agree:** the eight scripts that read page frontmatter (lint, retrieve, consolidate, both exporters, dedup, share, the mcp server) now all end it at a line that is exactly `---`, including one at the very end of the file; consolidate, dedup, OKF and share missed frontmatter closed without a final newline, and retrieve, Starlight and the mcp server ended it at any line starting with `---`. New `tests/unit/test_frontmatter_contract.py` feeds all eight the same cases. **Every lint check fires:** `tests/unit/test_lint_dirty.py` plants one fault per check (conformance, freshness, confidence, retention, decisions, orphans, graph, index/log, fingerprints, crux, review, contradictions, tags) in a copy of the fixture and asserts exactly which files each reports; the golden `lint.json` only proved the checks stay quiet on a clean KB | 1.7 |
|
||||
| 2.0.5 | 2026-11-11 | The remaining fixes from the 2.0.0 script review, no new features. **`routines.py`:** a `routines:` list written at column 0 (as PyYAML writes it) is read, and `--add` matches its indent; `--do` is written as a JSON-escaped string, so backslashes and quotes round-trip (`C:\docs` made invalid YAML); `--remove` takes a multi-line value's continuation lines. **`save_conversation.py`:** an unclosed `<private>` redacts the rest of the message across its content blocks, not only the rest of one block; metadata outside the text is untouched. **OKF:** values with ` #`, a leading `- `/`? `/`: ` or a tab are quoted (`See issue #42` lost everything after `#`); a `# comment` in a code block is not the page title. **Search and consolidation:** tokens are Unicode words, so Polish queries match (`właścicielem` was `cicielem`). **Low-severity batch:** an impossible date in a workload file name no longer crashes the session brief; lint reads frontmatter closed on the last line without a newline, and an empty block; `wiki/…` references without a leading slash resolve in graph edges, supersession and `affects`, and count as one page in the most-linked list; Starlight exports a root page named like a reserved route as `<name>-page` instead of overwriting it, resolves `[[Page|label]]`, accepts a string `source_files` in `edges.json`, and builds the splash buttons and cards from the sections that exist; both exporters drop `<private>` spans. Tests for each | 1.7 |
|
||||
| 2.0.4 | 2026-11-11 | Security fixes from the 2.0.0 script review, no new features. **Secret scan (lint check 15):** hidden folders, `.pem`/`.key`/`.crt`/`.asc`, `.env*` and other dotfiles, and extensionless text files are scanned (only `.git` is skipped, binary files are detected); unquoted `password: …`, `client_secret=…` and `aws_secret_access_key = …` values are found when they look like secrets (a letter and a digit, or 20+ characters in mixed case), not prose; the size limit is 50 MB instead of 5 and a file over it is reported as not scanned instead of passed silently. **mcp:** `search_kb` returns only paths `read_page` would serve (it listed matches in a linked KB's `workload/` and saved conversations), and passes the query after `--`; the `.local.yaml` refusal ignores case and trailing dots; an OAuth `email` claim counts only with `email_verified: true` (`CKB_MCP_OAUTH_TRUST_EMAIL=1` for IdPs that never send it); DNS-rebinding protection is on by default for the public URL's host and loopback (`CKB_MCP_ALLOWED_HOSTS` replaces the list, `*` turns it off); a confirmation code works once. **capture:** link-local and cloud-metadata addresses are always refused and loopback/private networks need `--allow-private`, checked again on every redirect; a 90 s limit on the whole download; an unknown charset falls back and `<meta charset>` is read; `<form>` pages keep their text and an `<svg><title>` is not the page title; binary captures get safe extensions, never overwrite each other and are duplicate-checked. Tests: secret corpus, mcp search/read policy, capture fetching and parsing; the server's auth and confirmation changes are compiled but not run here (no MCP SDK) | 1.7 |
|
||||
| 2.0.3 | 2026-11-11 | Windows fixes from the 2.0.0 script review, no new features. **Encoding:** every script's output is UTF-8 whatever the console code page (a Polish page name or a `→` crashed lint, session start, retrieve, consolidate, dedup, the exporters, capture and share on a cp1252 console); every git/rg/yt-dlp call is decoded as UTF-8 (a git name like `Łukasz` crashed `session_start.py`; `Michał` came out garbled and gave the wrong author slug); hook input on stdin is read as UTF-8 bytes (autosave silently never saved under a non-ASCII user folder). **BOM:** Markdown, YAML and JSON are read as `utf-8-sig`, so a page saved by Notepad keeps its frontmatter. **Line endings:** a `sha256:` fingerprint matches the file as stored, with LF or with CRLF endings, in `lint_report.py`, `lint_quick.sh` and `consolidate.py`, so a `core.autocrlf` checkout no longer reports every source as changed; a fingerprint is compared as a prefix of the full digest, so a correct one shorter than 8 characters no longer reads as CHANGED, and one under 6 is reported as too short to check. **Paths:** lint prints POSIX paths and retrieve asks ripgrep for `/` separators, so the exact-match signal works on Windows. **Hooks:** `start_hook.py`/`autosave_hook.py --install` default to the interpreter that ran them, quoted with forward slashes (a `C:\Program Files\…` path broke the command); `--check` reports a hook whose interpreter is missing, and a settings file that isn't an object is an error, not a traceback. New `tests/unit/test_windows.py` simulates a cp1252 console, CRLF and BOM files, Polish git names and odd settings files | 1.7 |
|
||||
| 2.0.2 | 2026-11-11 | Security fixes from the 2.0.0 script review, no new features. **`share` module:** a message's file name and mailbox must be plain names, and its `from`, `share_id` and version must match its mailbox, or it is ignored with a warning, so a channel member can no longer write lines into the receiver's `ckb.yaml` (a newline in a file name became a `routines:` block) or reach outside `raw/inbox/` (`share_id: x/../../wiki/…`); the ledger refuses whitespace and control characters. Every commit that touched a message must come from an owner of its mailbox, not only the one that added it, and a mailbox listed twice in `members.yaml` is unowned. Only a verified retraction hides a message not yet taken. Channel `branch`/`url`/name are validated before they reach git, and `git clone` gets `--` (a `branch: --upload-pack=…` ran a command). The received copy always carries `untrusted: true`; the sender's `untrusted` and review fields are dropped. `<private>` spans are stripped from the title and `tldr` too, and an unclosed tag drops the rest of the text. With no `lint_report.py` the send is refused (exit 3) instead of going out unscanned. README states that `members.yaml` is trusted as written; a git host enforcing paths is the real guard. **`capture` module:** frontmatter values are left plain only when nothing in them is YAML syntax, else written as JSON strings, and the page title is one line, so a `<title>` with `---` in it can no longer close the frontmatter and drop `untrusted: true`. **Lint check 13:** a `## Crux` quoted from a chat or a person no longer needs a `## Sources` section (`AGENTS.md` §2); one quoting a local file still does. Tests: `tests/unit/` gains hostile-channel cases for share (10), capture frontmatter, and check 13 | 1.7 |
|
||||
| 2.0.1 | 2026-11-11 | Fixes from the 2.0.0 script review, no new features. **Python 3.8 again:** `removeprefix`/`removesuffix` (3.9+) replaced in `lint_report.py`, `retrieve_candidates.py`, `consolidate.py` and the mcp server; on 3.8 any KB with `wiki/graph/edges.json` crashed lint, the session-start check, retrieve and consolidate. **`routines.py --mark`** no longer writes `last_run:2026-…` with no space (invalid YAML for any real parser) on a freshly added routine, and keeps a trailing comment as a comment instead of making it part of the value. **Exporters stay inside their folder:** `export_okf.py --out` must name a folder inside `outputs/` (it is deleted and rebuilt; `--out .` used to delete the repo), and `export_starlight.py` copies an image only from inside `wiki/assets/` to inside its own assets, so `../assets/../../x` in page text can no longer read or write files elsewhere. Docs: the script count is eight core skills (`ckb-consolidate`, `ckb-routine`, `ckb-add-conversation` were missing) in `AGENTS.md`, both READMEs and both manuals. New `tests/unit/` (stdlib `unittest`, run by `smoke.sh`): a static Python 3.8 guard over every shipped script, `routines.py` round-trips, exporter containment, and `AGENTS.md` consistency with the skills on disk | 1.7 |
|
||||
| 2.0.0 | 2026-11-11 | **Breaking: PowerShell support removed** (D-0019). `ckb-lint/scripts/lint_quick.ps1` is deleted, and so are the PowerShell version comparison in `ckb-upgrade` Step 2 and every "or the `.ps1`" mention (`AGENTS.md` Rule E and §3, `ckb-lint`, its manual checklist, `ckb-sync-changes`, both READMEs and manuals). Without Python, the session-start fallback is `lint_quick.sh`, on Windows under Git Bash. Every script the template and its modules ship is Python (`AGENTS.md` §3); `lint_quick.sh` and the `mcp` container `entrypoint.sh` are the named exceptions. KBs that need PowerShell stay on the `1.x` branch (*"switch this KB to the 1.x branch"*), which gets fixes only. `ckb-upgrade` now deletes files that upstream removed from a skill or module folder it still ships, listed as **Removed files** in Step 5. No schema change | 1.7 |
|
||||
| **1.28.10** | 2026-11-11 | `1.x` backport of 2.0.9: golden file lists and summaries for both exporters | 1.7 |
|
||||
| 1.28.9 | 2026-11-11 | `1.x` backport of 2.0.8: mcp server tests with the MCP SDK (confirmation codes, allowed hosts, a real-HTTP 421 for a foreign `Host`, OAuth email verification with real signed tokens); skipped without the SDK, `CKB_MCP_PYTHON` opts the smoke test in | 1.7 |
|
||||
| 1.28.8 | 2026-11-11 | `1.x` backport of 2.0.7: `ckb-reset` names the phrase for a KB without git (`reset the wiki with no restore point`); the nine eval cases and the runner's `replies`, `template`/`upstream` setup, `record`/`replay`. Also from 2.0.0, so a 1.x KB moving to 2.x drops what 2.x removed: `ckb-upgrade` deletes a file upstream no longer ships inside a skill or module folder it still ships, listed as **Removed files** in Step 5 (the `ckb-upgrade/take-major` eval run found the 1.x skill had no rule for it) | 1.7 |
|
||||
| 1.28.7 | 2026-11-11 | `1.x` backport of 2.0.6: all eight frontmatter readers close at a `---` line, including one at end of file; frontmatter contract test and dirty-KB lint test | 1.7 |
|
||||
| 1.28.6 | 2026-11-11 | `1.x` backport of the 2.0.5 fixes, no new features: `routines.py` zero-indent lists, escaped `--do`, `--remove` continuation lines; `<private>` redaction across content blocks; OKF quoting and code-fence titles; Unicode search tokens; workload date guard, frontmatter at end of file, `wiki/` refs without a slash, Starlight route collisions, labelled wikilinks, splash sections, `<private>` dropped from exports. Same tests as 2.0.5 | 1.7 |
|
||||
| 1.28.5 | 2026-11-11 | `1.x` backport of the 2.0.4 fixes, no new features: wider secret scan (hidden folders, key files, dotfiles, extensionless text, unquoted secret-looking assignments, oversized files reported); mcp search filtered by the read policy, case-insensitive `.local.yaml` refusal, verified OAuth email only, DNS-rebinding protection on by default, single-use confirmation codes; capture refuses link-local/metadata always and private networks without `--allow-private`, total download limit, charset fallback, `<form>` pages, safe binary names. The PowerShell fallback's reduced secret set is unchanged. Same tests as 2.0.4 | 1.7 |
|
||||
| 1.28.4 | 2026-11-11 | `1.x` backport of the 2.0.3 Windows fixes, no new features: UTF-8 output and subprocess decoding in every script, UTF-8 hook stdin, `utf-8-sig` reads for BOM files, fingerprints that match LF or CRLF checkouts and short prefixes (`lint_report.py`, `lint_quick.sh`, `consolidate.py`, and on this line `lint_quick.ps1`, which is not run in CI), POSIX paths in lint output and `rg --path-separator /`, hook installers that default to the running interpreter, quote paths and check that it still exists. Same tests as 2.0.3 | 1.7 |
|
||||
| 1.28.3 | 2026-11-11 | `1.x` backport of the 2.0.2 fixes, no new features: `share` message names and identifiers validated (no `ckb.yaml` injection, no writes outside `raw/inbox/`), every commit on a message must be by a mailbox owner, duplicate `members.yaml` entries unown a mailbox, only verified retractions hide mail, channel branch/url validated before git, received copies always `untrusted: true`, `<private>` stripped from title and `tldr`, no send without the secret scan; `capture` frontmatter quoting and one-line titles; lint check 13 accepts a chat-attributed Crux without `## Sources`. Same tests as 2.0.2 | 1.7 |
|
||||
| 1.28.2 | 2026-11-11 | `1.x` backport of the 2.0.1 fixes, no new features: Python 3.8 compatibility (`removeprefix`/`removesuffix` replaced in lint, retrieve, consolidate and the mcp server), `routines.py --mark` writing `last_run:2026-…` and swallowing comments, `export_okf.py --out` confined to `outputs/`, Starlight image copies confined to `wiki/assets/`, script counts in `AGENTS.md`, READMEs and manuals. Same `tests/unit/` suite, run by `smoke.sh` | 1.7 |
|
||||
| 1.28.1 | 2026-11-11 | Release channel `1.x`: the maintenance branch for the 1.x line once 2.0 ships, fixes only, and the last line with PowerShell support (D-0019). Listed in the channel tables of `ckb-init`, `ckb-upgrade`, `AGENTS.md`, both READMEs and both manuals, and in the `ckb.yaml` comment. `ckb-upgrade` Step 2: a higher **major** version upstream stops the run before Step 4, quotes the breaking part of the upstream changelog row, and offers the new major or a switch to the maintenance branch; never crossed from a routine or batch run | 1.7 |
|
||||
| 1.28.0 | 2026-11-11 | New opt-in `share` module (D-0018): skill `ckb-share` and `share.py` (`join`/`send`/`unshare`/`list`/`receive`/`status`, stdlib + git). A **channel** is a separate git repo per trust group with `CHANNEL.md`, `members.yaml` (kb → owner emails) and one append-only mailbox per KB, `mail/<kb>/`, cloned into `tmp/share/<channel>/`. **Send** packs a self-contained copy of an `outputs/documents/`, `outputs/answers/` or `wiki/` page (`raw/archive/` only with `--raw-ok`): `<private>` spans and `## Notes` dropped, local links as text, Sources/Crux paths marked `<kb>:`; envelope `type: share`, `kind`, `share_id`, `version`, `from`, `to`, `sent_by`, `untrusted: true`; lint's secret patterns block the send (exit 3), a dry run prints the `ABOUT.md` sensitivity section, the user confirms. Re-sending makes the next version. **Receive** copies messages addressed to the KB into `raw/inbox/` with `share_channel`, `share_ref`, `received_on`, `submitted_by` (git author) and `supersedes_source`; a message whose git author is not an owner of its mailbox is UNVERIFIED and taken only with `--accept-unverified`; a retraction becomes `raw/retractions/` requests for every held version. A `received:` ledger in the script-owned `share:` block of `ckb.yaml` keeps handled messages from returning. `dedup_inbox.py` reports `SAME SHARE`; `ckb-ingest` and `ckb-retract` know share files and requests. Smoke test covers two KBs and a bare-repo channel end to end | 1.7 |
|
||||
| 1.27.0 | 2026-11-02 | New core skill `ckb-feynman`, adapted from the `feynman` skill in superhero-tech-super-brain: explains one page in plain words with a concrete example and a `→ [[page]] · [Title § Heading](/wiki/…#anchor)` line under each block, then sorts every thin spot into Wiki, Sources or Mine gaps without filling any from model knowledge, asks for an explain-back and ends with numbered next moves. Candidates come from `review: draft`/`needs_update`, single-source, stale or contradicted pages; topic pages are followed to their members; Crux fingerprints are checked as in `ckb-retrieve` Step 6; `<private>` spans are never explained. Sessions go to `outputs/teaching/feynman/YYYY-MM-DD_<slug>.md` (`type: feynman-session`, fingerprinted `## Sources`, gitignored with `outputs/teaching/`, no `wiki/log.md` entry); a Sources gap reaches `wiki/query-gaps.md` only on a yes. `ckb-teach-me` skips the folder; `ckb-init`, `AGENTS.md` routing row, both READMEs and manuals updated; eval case `ckb-feynman/session` with a recorded reference run (6/6). `outputs/teaching/` added to the directory contract; `run_evals.py` matches deleted files with glob semantics (`**` was one segment) | 1.7 |
|
||||
|
|
@ -429,27 +400,14 @@ Versions 1.4.0 and 1.5.0 were never published - the template jumped from
|
|||
|
||||
## Release channels
|
||||
|
||||
The template repo keeps four release branches and one integration branch:
|
||||
The template repo keeps three branches, and the version histories above track
|
||||
`main` only:
|
||||
|
||||
| Branch | What it is | Who should track it |
|
||||
|---|---|---|
|
||||
| `main` | **Stable** - the released template | Everyone, by default |
|
||||
| `test` | **Release candidate** - validated before merging to `main` | Anyone helping validate a release |
|
||||
| `experimental` | **Preview** - work merged from `dev` early, may be broken or reverted | People developing the template itself |
|
||||
| `1.x` | **Maintenance** - fixes for the 1.x line, the last with PowerShell | KBs that need PowerShell |
|
||||
| `dev` | **Integration** - every change lands here first | Nobody: not a channel |
|
||||
|
||||
**How a version is made (D-0022).** `VERSION` and this file's history change
|
||||
only when `dev` is merged into another branch, never by a commit on `dev`. The
|
||||
merge takes the next number by the usual rule (major for breaking changes,
|
||||
minor for features, patch for fixes; the highest kind in the merge wins) and
|
||||
adds its row here. A version keeps its number as it is promoted: `dev` →
|
||||
`experimental` → `test` → `main`, `dev` → `test` → `main`, or `dev` → `main`.
|
||||
Merging `dev` takes everything on it, so merge straight into `main` only when
|
||||
all of `dev` is ready to ship. After a version reaches `main`, `main` is
|
||||
merged back into `dev`, `test` and `experimental`, so `dev` starts from the
|
||||
released version and no channel falls behind the stable one. `1.x` stays outside this flow: its fixes are committed and
|
||||
numbered there directly.
|
||||
| `experimental` | **Development** - active work, may be broken or reverted | People developing the template itself |
|
||||
|
||||
The branch a KB tracks lives in `ckb.yaml`:
|
||||
|
||||
|
|
|
|||
|
|
@ -25,24 +25,18 @@ zastrzeżonej konwencji nazw plików. Nigdy nie było podniesienia wersji
|
|||
głównej — każda dotychczasowa wersja schematu była addytywna, więc dowolna
|
||||
strona napisana od 2026-07-13 jest dziś nadal poprawna.
|
||||
|
||||
Wersja szablonu stosuje tę samą regułę do narzędzi: wersja **główna**, gdy
|
||||
znika coś, na czym KB może polegać. Pierwsza taka, 2.0.0, usunęła obsługę
|
||||
PowerShella. Poprzednia wersja główna dostaje poprawki na gałęzi
|
||||
utrzymaniowej nazwanej od niej (`1.x`), a `ckb-upgrade` nigdy nie
|
||||
przechodzi przez wersję główną bez pytania.
|
||||
|
||||
---
|
||||
|
||||
## Spis treści
|
||||
|
||||
1. [Aktualny schemat strony (1.8)](#aktualny-schemat-strony-kb_schema_version-18)
|
||||
1. [Aktualny schemat strony (1.7)](#aktualny-schemat-strony-kb_schema_version-17)
|
||||
2. [Historia wersji schematu KB](#historia-wersji-schematu-kb)
|
||||
3. [Historia wersji szablonu](#historia-wersji-szablonu)
|
||||
4. [Migracja między wersjami](#migracja-między-wersjami)
|
||||
|
||||
---
|
||||
|
||||
## Aktualny schemat strony (`kb_schema_version: "1.8"`)
|
||||
## Aktualny schemat strony (`kb_schema_version: "1.7"`)
|
||||
|
||||
### Frontmatter — każda strona niezastrzeżona
|
||||
|
||||
|
|
@ -85,10 +79,7 @@ dodają:
|
|||
| `decided_on` | dla `accepted`/`rejected`/`reversed` | `YYYY-MM-DD`, data podjęcia decyzji. |
|
||||
| `decided_by` | gdy wiadomo | Nazwiska po przecinku. Gdy naprawdę nie wiadomo, wpisz `unknown` zamiast pomijać pole — „nie wiemy, kto to zdecydował" samo w sobie warto zapisać. |
|
||||
| `affects` | nie | Ścieżki wiki po przecinku, które ta decyzja ogranicza. |
|
||||
| `review_on` | nie | `YYYY-MM-DD` do ponownego rozważenia. Lint zgłasza je po przekroczeniu daty, dopóki nie ma `outcome_checked` w tym dniu lub później. |
|
||||
| `expected_outcome` | nie | *(1.8)* Jeden wiersz: co decyzja ma zmienić, zapisany przy jej zapisie. Dodany później kończy się `(added RRRR-MM-DD)`. |
|
||||
| `outcome` | przy przeglądzie | *(1.8)* `met` / `partly` / `missed` / `unclear` względem `expected_outcome`. Sprawdzane przez lint. |
|
||||
| `outcome_checked` | przy przeglądzie | *(1.8)* `RRRR-MM-DD` ostatniego przeglądu wyniku; sam datowany wpis trafia do sekcji `## Outcome`. |
|
||||
| `review_on` | nie | `YYYY-MM-DD` do ponownego rozważenia. Lint zgłasza je po przekroczeniu daty. |
|
||||
|
||||
Rekordy decyzji są **tylko do dopisywania**. Decyzji nigdy nie przepisuje się
|
||||
pod późniejszą zmianę zdania: zapisz nową, która ją zastępuje, a obie zostają
|
||||
|
|
@ -215,7 +206,7 @@ rankingowym).
|
|||
| `wiki/index.md` | 1.1 | Tabela routingu; jedyna strona niosąca `kb_schema_version` |
|
||||
| `wiki/overview.md` | 1.1 | Mapa KB z lotu ptaka |
|
||||
| `wiki/log.md` | 1.1 | Dziennik zmian `wiki/` w odwrotnej chronologii |
|
||||
| `wiki/error-book.md` | 1.1 | Powracające problemy (od 1.8: jeden wpis na przyczynę, z każdą próbą, jej oczekiwanym i zaobserwowanym wynikiem oraz kontekstem) |
|
||||
| `wiki/error-book.md` | 1.1 | Problemy systemowe wraz z przyczyną i naprawą |
|
||||
| `wiki/entities/` | 1.1 | Typowane strony encji |
|
||||
| `wiki/graph/` | 1.1 | `edges.json` plus słownik w `index.md` |
|
||||
| `wiki/query-gaps.md` | 1.2 | Pytania, na które wiki nie umiało odpowiedzieć, napędzające ingest sterowany popytem |
|
||||
|
|
@ -232,21 +223,6 @@ nawigacja pozostaje leniwa.
|
|||
|
||||
## Historia wersji schematu KB
|
||||
|
||||
### 1.8 — 2026-11-18 · pamięć ulepszeń
|
||||
|
||||
[D-0023](decisions/0023-improvement-memory.md), na wzór Self-Improvement
|
||||
Memory Google'a (arXiv 2611.18856). Addytywnie:
|
||||
- **Księga błędów według problemów**: wpisy `## E<n> — <przyczyna>` ze
|
||||
statusem i tabelą prób (data, zmiana, Expected, Observed, Context);
|
||||
scalone wpisy zostają jako aliasy `## E4 → E2`.
|
||||
- **Decyzje**: opcjonalne `expected_outcome`, `outcome`, `outcome_checked`;
|
||||
opcjonalne sekcje `## Tried` i dopisywana `## Outcome`.
|
||||
- **Lekcje**: wiersz `Context:` (agent/model, wersja szablonu), opcjonalne
|
||||
`Carried from:` i `Also recorded:`.
|
||||
|
||||
**Migracja** (`ckb-upgrade` krok 7 b5): stara tabela księgi błędów zostaje
|
||||
pod `## Earlier entries`; nic nie jest uzupełniane wstecz.
|
||||
|
||||
### 1.7 — 2026-11-02 · podsumowania tematów
|
||||
|
||||
[D-0016](decisions/0016-topic-summaries-and-consolidation.md). Nowy opcjonalny
|
||||
|
|
@ -372,20 +348,15 @@ Niezależna od schematu treści powyżej.
|
|||
|
||||
| Wersja | Data | Co weszło | Schemat |
|
||||
|---|---|---|---|
|
||||
| **2.4.0** | 2026-11-18 | Pamięć ulepszeń (D-0023, schemat 1.8), na wzór Self-Improvement Memory Google'a. **Księga błędów** (sprawdzenie 9 `ckb-lint`): jeden wpis na powracający problem z każdą próbą naprawy, tym, czemu miała zapobiec (zapisane najpierw), co pokazały kolejne przebiegi (`pending` → `held`/`recurred`/`partly`) i przy jakim modelu/szablonie; lint uzupełnia oczekujące obserwacje w każdym przebiegu, ponawia nieudaną naprawę tylko z czymś nowym, scala wpisy w aliasy; nowy szkielet. **Decyzje** (`ckb-decide`): `expected_outcome` przy zapisie, nowa procedura przeglądu wyniku dopisująca do `## Outcome` i ustawiająca `outcome`/`outcome_checked`, sekcja `## Tried` i sprawdzenie, gdy nowa decyzja wybiera kierunek już wypróbowany lub odrzucony. `lint_report.py` sprawdza słownik wyników, zamyka zaległy przegląd, gdy `outcome_checked` ≥ `review_on`, i prosi o wynik, gdy jest `expected_outcome`. **Lekcje** (`ckb-profile`): wiersz `Context:` i zasady stosowania lekcji z innego kontekstu, przejmowania lekcji z baz zewnętrznych, scalania. `session_start.py` wypisuje nowe lekcje z `linked/<nazwa>/wiki/lessons.md` jako `upstream lessons:` i pomija przekreślone. **`ckb-init`** krok 8b proponuje przeniesienie lekcji i problemów z księgi błędów do nowej KB. **`ckb-upgrade`** migracja b5. ADR-y szablonu mogą mieć te same pola. Odłożone: pętla samodoskonalenia szablonu (wymaga ewaluacji). Odrzucone: ładowanie całego zapisu do kontekstu. Testy: `tests/unit/test_sim_memory.py` | 1.8 |
|
||||
| 2.3.0 | 2026-11-12 | Przepływ gałęzi i wersji (D-0022): nowa gałąź integracyjna `dev`, na którą trafia cała praca; `VERSION` i changelog zmieniają się tylko przy scaleniu `dev` do `experimental`, `test` albo `main` (ścieżki `dev` → `experimental` → `test` → `main`, `dev` → `test` → `main`, `dev` → `main`), a wersja zachowuje numer przy promocji; po wydaniu `main` jest scalana z powrotem do `dev`, `test` i `experimental`; `1.x` ma własne poprawki. `experimental` staje się kanałem *podglądowym*; `dev` nie jest kanałem, a `ckb-init`/`ckb-upgrade` proponują zamiast niej `experimental`. Do tego **skille profilowe** w `user-skills/`, instalowane raz na osobę, a nie na KB: `ckb-create` buduje KB za pomocą `ckb-init` z pobranego szablonu, robi commit na `main` i push do pustego zdalnego repozytorium; `ckb-join` klonuje KB po URL i sprawdza tożsamość git, dowiązania, montowania `linked/` i Pythona, bez commitów. Żaden nie jest kopiowany do KB. Oba podręczniki mają o nich sekcję | 1.7 |
|
||||
| 2.2.0 | 2026-11-11 | Nowy opcjonalny moduł `convert` (D-0021): skill `ckb-convert` i `convert.py` (biblioteka standardowa; wymaga pandoca, LibreOffice opcjonalnie). `convert` zamienia dowolny plik Markdown z bazy na `.docx`, `.odt`, PDF lub HTML w nazwanym stylu firmowym, `templates/styles/<nazwa>.docx` (dokument referencyjny pandoca; opcjonalnie `<nazwa>.odt`/`<nazwa>.css`). PDF i ODT robi LibreOffice ze sformatowanego `.docx` (osobny profil), więc wszystkie formaty wyglądają tak samo; bez niego PDF robi silnik PDF pandoca, z informacją, że styl nie został zastosowany. Kopia jest czyszczona dla czytelnika spoza bazy: frontmatter → tytuł/autor (bez e-maila)/data/język, początkowy `# H1` → tytuł, komentarze szablonu usunięte, `[[wikilinki]]` i linki do ścieżek bazy → tekst (`--keep-links`), bloki kodu bez zmian. Istniejący plik wynikowy nie jest nadpisywany bez `--force`. **Style bez ręcznego wybierania czcionek:** `new-style` kopiuje domyślny dokument referencyjny pandoca i ustawia czcionkę tekstu i nagłówków, rozmiar, kolor nagłówków, format papieru (A4/Letter) i marginesy w `styles.xml`, motywie i `sectPr` treści, w kolejności wymaganej przez schemat; `--from` przyjmuje firmowy `.docx`/`.dotx` (typ zawartości przepisany, makra odrzucane); `edit-style`, `check-style` (style używane przez pandoca, których brakuje w szablonie), `styles`, `doctor`. Szkielet `templates/styles/README.md`; ustawienia `style`, `format`, `out_dir`, `toc`, `number_sections`, `keep_links` przez `default_config`; kierowanie przez blok modułu w `AGENTS.md`, po `ckb-voice`. Testy: `tests/unit/test_convert.py`, eval `ckb-module/install-convert`. Bez zmiany schematu | 1.7 |
|
||||
| 2.1.0 | 2026-11-11 | Nowy opcjonalny moduł `voice` (D-0020): skill `ckb-voice`, bez skryptu. Każdy plik prozy zapisywany pod ścieżkami `apply_to` (domyślnie `outputs/answers/`, `outputs/documents/`, `outputs/reports/`, `PROJECT-OVERVIEW*`; `outputs/okf/` i `outputs/starlight/` pominięte) jest przed zapisem przepisywany wybranym głosem, niezależnie od tego, który skill go przygotował; podpięcie to blok modułu w `AGENTS.md`, więc żaden skill bazowy się nie zmienił. **Profile to strony wiki**, `wiki/voice/<nazwa>.md` (`type: voice-profile`, `voice_of: team/person/third-party`, Tone, Formality, Sentence style, Keep, Avoid, Audience, Opinions, Sample, `## Sources`, chronione `## Notes`), tworzone i logowane przez kalibrację z przykładowych dokumentów; stałe preferencje wypowiedziane przy okazji zmieniają jedno pole. **Ustawienia** w `ckb.yaml` (`mode: auto/ask/off`, `profile`, `writer`, `apply_to`, `skip`, `chat`); kolejność profilu: nazwany w prośbie, potem `voice:` na stronie osoby w `workload/profiles/`, potem domyślny. **Zamrożone fragmenty** (frontmatter poza nowym polem `voice:`, Sources, Crux i cytaty z atrybucjami, Notes/Rules, znaczniki sprzeczności, `<private>`, kod, ścieżki, linki, liczby, nazwy, nagłówki szablonu) są porównywane przed zapisem; ogólnikowe twierdzenie jest zgłaszane, nigdy wycinane. `writer:` przekazuje przepisywanie innemu zainstalowanemu skillowi, np. osobistemu `ghost-writer`, z powrotem do `ckb-voice`, gdy go brak. Reguły zaadaptowane z tego skilla. `ckb-module` wpisuje `default_config` z manifestu do `config:` wpisu i przy reinstalacji zachowuje zmienione wartości. Nowy typ `voice-profile` i pole `voice`, addytywnie, bez zmiany schematu | 1.7 |
|
||||
| 2.0.9 | 2026-11-11 | Tylko testy. Złote wyniki obu eksportów na czystym fixture: dokładna lista plików (`tests/expected/okf-files.txt`, 15 plików; `starlight-files.txt`, 17) i podsumowanie, które każdy wypisuje (`okf-report.txt`, `starlight-report.txt`, z werdyktem zgodności OKF). Treść nie jest porównywana, bo OKF wpisuje datę eksportu. To zamyka ostatni punkt przeglądu skryptów 2.0.0 | 1.7 |
|
||||
| 2.0.8 | 2026-11-11 | Tylko testy. `tests/unit/test_mcp_server.py` obejmuje serwer mcp z zainstalowanym MCP SDK (2.3.0): kod potwierdzenia potwierdza dokładnie jeden zapis i jest związany z treścią i czasem ważności, zły `kb` jest odrzucany jako pierwszy, `_redact` maskuje sekrety, domyślna i nadpisana lista dozwolonych hostów, obcy nagłówek `Host` dostaje 421 przez prawdziwe HTTP, a host publiczny 200, oraz tokeny OAuth podpisane prawdziwym kluczem RSA — niezweryfikowany e-mail nie przechodzi już listy `@domena`, zweryfikowany przechodzi, `CKB_MCP_OAUTH_TRUST_EMAIL=1` to wyłącza, zła publiczność i wygasłe tokeny są odrzucane. Bez SDK testy są pomijane; `CKB_MCP_PYTHON=<venv>/bin/python bash tests/smoke.sh` je uruchamia. Potwierdzają zmiany serwera z 2.0.4, które dotąd były tylko skompilowane | 1.7 |
|
||||
| 2.0.7 | 2026-11-11 | Ewaluacje skilli niszczących i zmieniających stan oraz poprawka, którą jedna z nich znalazła; bez nowych funkcji. **`ckb-reset`:** w KB bez repozytorium git krok 0 wymagał „znacznie wyraźniejszego potwierdzenia”, nie mówiąc jakiego, więc dwa przebiegi poprosiły o dwie różne frazy; fraza jest teraz nazwana, **`reset the wiki with no restore point`**, a zwykłe `reset the wiki` się tam nie liczy. **Dziewięć nowych przypadków ewaluacji**, każdy raz wykonany przez agenta 2026-11-11 i zaliczony: `ckb-reset/no-confirm` (inwentarz, nic nie usunięto), `ckb-reset/confirmed` (zwykła fraza odrzucona, ścisła przyjęta; poziom 1 usunięty, szkielet przywrócony, `kb_schema_version` zachowane, raw i szablon nietknięte), `ckb-module/install` i `ckb-module/round-trip` (`AGENTS.md`, `.gitignore`, `ckb.yaml` identyczne co do bajtu po odinstalowaniu), `ckb-upgrade/major-guard` (1.28.7 → 2.x zatrzymuje się i pyta) i `ckb-upgrade/take-major` (VERSION 2.x, `lint_quick.ps1` usunięty, wiki nietknięte), `ckb-decide/supersede` (oba odnośniki ustawione, tekst D-0001 nietknięty), `ckb-ingest/check-in-waits` i `ckb-ingest/reviewed-page` (`needs_update`, `## Notes` co do bajtu). **Runner:** `replies` na odpowiedzi operatora, gdy skill się zatrzymuje; kroki przygotowania `template` (pliki szablonu, opcjonalnie ze starszego refa gita) i `upstream` (lokalne gołe repozytorium dla `ckb-upgrade`); `record` zapisuje zaliczony przebieg jako `reference/` z listą `.deleted`, a `replay` go odtwarza i sprawdza; test dymny odtwarza każdą referencję (dziś pięć). Czytnik frontmattera w runnerze przyjmuje frontmatter zamknięty na końcu pliku | 1.7 |
|
||||
| 2.0.6 | 2026-11-11 | Testy i poprawka parsera, którą znalazły; bez nowych funkcji. **Czytniki frontmattera są zgodne:** osiem skryptów czytających frontmatter stron (lint, wyszukiwanie, konsolidacja, oba eksporty, dedup, share, serwer mcp) kończy go teraz na linii będącej dokładnie `---`, także na samym końcu pliku; konsolidacja, dedup, OKF i share pomijały frontmatter zamknięty bez końcowego znaku nowej linii, a wyszukiwanie, Starlight i serwer mcp kończyły go na dowolnej linii zaczynającej się od `---`. Nowy `tests/unit/test_frontmatter_contract.py` podaje wszystkim ośmiu te same przypadki. **Każde sprawdzenie lintu działa:** `tests/unit/test_lint_dirty.py` podkłada po jednym błędzie na sprawdzenie (zgodność, świeżość, pewność, retencja, decyzje, sieroty, graf, indeks/log, odciski, crux, przegląd, sprzeczności, tagi) w kopii fixture'a i sprawdza, które dokładnie pliki zgłasza każde z nich; złoty `lint.json` dowodził tylko, że na czystej KB sprawdzenia milczą | 1.7 |
|
||||
| 2.0.5 | 2026-11-11 | Pozostałe poprawki z przeglądu skryptów 2.0.0, bez nowych funkcji. **`routines.py`:** lista `routines:` zapisana od kolumny 0 (tak pisze PyYAML) jest czytana, a `--add` dopasowuje jej wcięcie; `--do` jest zapisywane jako napis z escape'ami JSON, więc ukośniki odwrotne i cudzysłowy przechodzą w obie strony (`C:\docs` dawało niepoprawny YAML); `--remove` usuwa wiersze kontynuacji wartości wielowierszowej. **`save_conversation.py`:** niezamknięte `<private>` redaguje resztę wiadomości przez wszystkie jej bloki, a nie tylko resztę jednego bloku; metadane poza tekstem są nietknięte. **OKF:** wartości z ` #`, początkowym `- `/`? `/`: ` albo tabulatorem są cytowane (`See issue #42` traciło wszystko po `#`); `# komentarz` w bloku kodu nie jest tytułem strony. **Wyszukiwanie i konsolidacja:** tokeny to słowa Unicode, więc polskie zapytania pasują (`właścicielem` było `cicielem`). **Drobne błędy:** niemożliwa data w nazwie pliku workload nie wywraca już podsumowania sesji; lint czyta frontmatter zamknięty w ostatniej linii bez znaku nowej linii oraz pusty blok; odwołania `wiki/…` bez ukośnika na początku rozwiązują się w krawędziach grafu, zastępowaniu i `affects` oraz liczą się jako jedna strona na liście najczęściej linkowanych; Starlight eksportuje stronę w katalogu głównym nazwaną jak zarezerwowana ścieżka jako `<nazwa>-page`, zamiast ją nadpisywać, rozwiązuje `[[Strona|etykieta]]`, przyjmuje napis jako `source_files` w `edges.json` i buduje przyciski i karty strony startowej z sekcji, które istnieją; oba eksporty usuwają fragmenty `<private>`. Testy dla każdej | 1.7 |
|
||||
| 2.0.4 | 2026-11-11 | Poprawki bezpieczeństwa z przeglądu skryptów 2.0.0, bez nowych funkcji. **Skan sekretów (sprawdzenie 15):** skanowane są ukryte foldery, `.pem`/`.key`/`.crt`/`.asc`, `.env*` i inne pliki z kropką oraz pliki tekstowe bez rozszerzenia (pomijany jest tylko `.git`, pliki binarne są wykrywane); niecytowane wartości `password: …`, `client_secret=…` i `aws_secret_access_key = …` są wykrywane, gdy wyglądają na sekret (litera i cyfra albo 20+ znaków w mieszanej wielkości), a nie na prozę; limit rozmiaru to 50 MB zamiast 5, a plik ponad nim jest zgłaszany jako nieprzeskanowany, zamiast przechodzić po cichu. **mcp:** `search_kb` zwraca tylko ścieżki, które poda `read_page` (wymieniał trafienia w `workload/` i zapisanych rozmowach podpiętej KB), a zapytanie przekazuje po `--`; odmowa dla `.local.yaml` ignoruje wielkość liter i końcowe kropki; claim `email` z OAuth liczy się tylko z `email_verified: true` (`CKB_MCP_OAUTH_TRUST_EMAIL=1` dla dostawców, którzy go nie wysyłają); ochrona przed DNS rebinding jest domyślnie włączona dla hosta z publicznego URL i loopbacku (`CKB_MCP_ALLOWED_HOSTS` zastępuje listę, `*` ją wyłącza); kod potwierdzenia działa raz. **capture:** adresy link-local i metadanych chmury są zawsze odrzucane, a loopback i sieci prywatne wymagają `--allow-private`, sprawdzanego też przy każdym przekierowaniu; limit 90 s na całe pobieranie; nieznane kodowanie ma zapas, a `<meta charset>` jest czytane; strony z `<form>` zachowują tekst, a `<svg><title>` nie jest tytułem strony; pliki binarne dostają bezpieczne rozszerzenia, nigdy się nie nadpisują i przechodzą kontrolę duplikatów. Testy: korpus sekretów, polityka wyszukiwania i odczytu mcp, pobieranie i parsowanie w capture; zmiany uwierzytelniania i potwierdzeń w serwerze są skompilowane, ale nieuruchomione (brak MCP SDK) | 1.7 |
|
||||
| 2.0.3 | 2026-11-11 | Poprawki dla Windows z przeglądu skryptów 2.0.0, bez nowych funkcji. **Kodowanie:** wyjście każdego skryptu jest w UTF-8 niezależnie od strony kodowej konsoli (polska nazwa strony albo `→` wywracały lint, start sesji, wyszukiwanie, konsolidację, dedup, eksporty, capture i share na konsoli cp1252); każde wywołanie git/rg/yt-dlp jest dekodowane jako UTF-8 (nazwisko w gicie typu `Łukasz` wywracało `session_start.py`; `Michał` wychodziło zniekształcone i dawało zły slug autora); wejście hooka na stdin jest czytane jako bajty UTF-8 (autozapis po cichu nie działał w folderze użytkownika z polskimi znakami). **BOM:** Markdown, YAML i JSON są czytane jako `utf-8-sig`, więc strona zapisana w Notatniku zachowuje frontmatter. **Końce linii:** odcisk `sha256:` pasuje do pliku w postaci zapisanej, z końcami LF albo CRLF, w `lint_report.py`, `lint_quick.sh` i `consolidate.py`, więc checkout z `core.autocrlf` nie zgłasza już każdego źródła jako zmienionego; odcisk jest porównywany jako prefiks pełnego skrótu, więc poprawny krótszy niż 8 znaków nie jest już CHANGED, a krótszy niż 6 jest zgłaszany jako zbyt krótki. **Ścieżki:** lint wypisuje ścieżki POSIX, a wyszukiwanie prosi ripgrep o separator `/`, więc sygnał dokładnego trafienia działa na Windows. **Hooki:** `start_hook.py`/`autosave_hook.py --install` domyślnie wpisują interpreter, który je uruchomił, w cudzysłowie i z ukośnikami (ścieżka `C:\Program Files\…` psuła polecenie); `--check` zgłasza hook, którego interpretera brak, a plik ustawień, który nie jest obiektem, daje błąd zamiast tracebacku. Nowy `tests/unit/test_windows.py` symuluje konsolę cp1252, pliki CRLF i z BOM, polskie nazwiska w gicie i nietypowe pliki ustawień | 1.7 |
|
||||
| 2.0.2 | 2026-11-11 | Poprawki bezpieczeństwa z przeglądu skryptów 2.0.0, bez nowych funkcji. **Moduł `share`:** nazwa pliku wiadomości i skrzynki muszą być zwykłymi nazwami, a jej `from`, `share_id` i wersja muszą pasować do skrzynki, inaczej wiadomość jest pomijana z ostrzeżeniem, więc członek kanału nie może już dopisać wierszy do `ckb.yaml` odbiorcy (znak nowej linii w nazwie pliku stawał się blokiem `routines:`) ani pisać poza `raw/inbox/` (`share_id: x/../../wiki/…`); rejestr odrzuca białe znaki i znaki sterujące. Każdy commit, który dotknął wiadomości, musi pochodzić od właściciela skrzynki, nie tylko ten, który ją dodał, a skrzynka wpisana dwa razy w `members.yaml` nie ma właściciela. Tylko zweryfikowane wycofanie ukrywa niewziętą wiadomość. `branch`/`url`/nazwa kanału są sprawdzane, zanim trafią do gita, a `git clone` dostaje `--` (`branch: --upload-pack=…` uruchamiało polecenie). Odebrana kopia zawsze ma `untrusted: true`; pola `untrusted` i przeglądu nadawcy są usuwane. Fragmenty `<private>` są usuwane także z tytułu i `tldr`, a niezamknięty znacznik usuwa resztę tekstu. Bez `lint_report.py` wysyłka jest odrzucana (kod 3), zamiast iść bez skanu. README mówi, że `members.yaml` jest ufany tak, jak jest zapisany; prawdziwą ochroną jest serwer git pilnujący ścieżek. **Moduł `capture`:** wartości we frontmatterze zostają bez cudzysłowu tylko wtedy, gdy nie ma w nich składni YAML, inaczej są zapisywane jako napisy JSON, a tytuł strony to jedna linia, więc `<title>` z `---` nie zamknie już frontmattera i nie zgubi `untrusted: true`. **Lint, sprawdzenie 13:** `## Crux` cytujący rozmowę lub osobę nie wymaga już sekcji `## Sources` (`AGENTS.md` §2); cytujący lokalny plik nadal wymaga. Testy: `tests/unit/` dostaje wrogie przypadki kanału dla share (10), frontmatter capture i sprawdzenie 13 | 1.7 |
|
||||
| 2.0.1 | 2026-11-11 | Poprawki z przeglądu skryptów 2.0.0, bez nowych funkcji. **Znów Python 3.8:** `removeprefix`/`removesuffix` (3.9+) zastąpione w `lint_report.py`, `retrieve_candidates.py`, `consolidate.py` i serwerze mcp; na 3.8 każda KB z `wiki/graph/edges.json` wywracała lint, kontrolę na starcie sesji, wyszukiwanie i konsolidację. **`routines.py --mark`** nie zapisuje już `last_run:2026-…` bez spacji (niepoprawny YAML dla każdego prawdziwego parsera) w świeżo dodanej rutynie i zostawia końcowy komentarz komentarzem, zamiast doklejać go do wartości. **Eksporty nie wychodzą poza swój folder:** `export_okf.py --out` musi wskazywać folder wewnątrz `outputs/` (jest usuwany i budowany od nowa; `--out .` usuwało repozytorium), a `export_starlight.py` kopiuje obraz tylko z wnętrza `wiki/assets/` do własnych zasobów, więc `../assets/../../x` w treści strony nie może już czytać ani zapisywać plików gdzie indziej. Dokumentacja: skrypt ma osiem skilli rdzenia (brakowało `ckb-consolidate`, `ckb-routine`, `ckb-add-conversation`) w `AGENTS.md`, obu README i obu podręcznikach. Nowy `tests/unit/` (`unittest` z biblioteki standardowej, uruchamiany przez `smoke.sh`): statyczna straż Pythona 3.8 nad każdym dostarczanym skryptem, przebiegi `routines.py`, ograniczenie eksportów do ich folderu i zgodność `AGENTS.md` ze skillami na dysku | 1.7 |
|
||||
| 2.0.0 | 2026-11-11 | **Zmiana przełomowa: koniec obsługi PowerShella** (D-0019). Usunięte: `ckb-lint/scripts/lint_quick.ps1`, porównanie wersji w PowerShellu w kroku 2 `ckb-upgrade` i każda wzmianka „albo `.ps1`” (`AGENTS.md` reguła E i §3, `ckb-lint`, jego ręczna lista kontrolna, `ckb-sync-changes`, oba README i oba podręczniki). Bez Pythona zapasową kontrolą na starcie sesji jest `lint_quick.sh`, na Windows w Git Bash. Każdy skrypt szablonu i jego modułów jest w Pythonie (`AGENTS.md` §3); `lint_quick.sh` i kontenerowy `entrypoint.sh` modułu `mcp` to nazwane wyjątki. KB, które potrzebują PowerShella, zostają na gałęzi `1.x` (*„przełącz tę KB na gałąź 1.x”*), która dostaje tylko poprawki. `ckb-upgrade` usuwa teraz pliki, które źródło usunęło z folderu skilla lub modułu, który nadal dostarcza; krok 5 wypisuje je jako **Removed files**. Bez zmiany schematu | 1.7 |
|
||||
| **1.28.10** | 2026-11-11 | Przeniesienie 2.0.9 na `1.x`: złote listy plików i podsumowania obu eksportów | 1.7 |
|
||||
| 1.28.9 | 2026-11-11 | Przeniesienie 2.0.8 na `1.x`: testy serwera mcp z MCP SDK (kody potwierdzenia, dozwolone hosty, 421 przez prawdziwe HTTP dla obcego `Host`, weryfikacja e-maila OAuth na prawdziwie podpisanych tokenach); pomijane bez SDK, `CKB_MCP_PYTHON` włącza je w teście dymnym | 1.7 |
|
||||
| 1.28.8 | 2026-11-11 | Przeniesienie 2.0.7 na `1.x`: `ckb-reset` nazywa frazę dla KB bez gita (`reset the wiki with no restore point`); dziewięć przypadków ewaluacji i w runnerze `replies`, przygotowanie `template`/`upstream`, `record`/`replay`. Także z 2.0.0, żeby KB z linii 1.x przechodząca na 2.x pozbyła się tego, co 2.x usunęło: `ckb-upgrade` usuwa plik, którego źródło już nie dostarcza w folderze skilla lub modułu, który nadal dostarcza, i wypisuje go w kroku 5 jako **Removed files** (przebieg ewaluacji `ckb-upgrade/take-major` pokazał, że skill z 1.x nie miał na to reguły) | 1.7 |
|
||||
| 1.28.7 | 2026-11-11 | Przeniesienie 2.0.6 na `1.x`: wszystkie osiem czytników frontmattera kończy go na linii `---`, także na końcu pliku; test kontraktu frontmattera i test lintu na zabrudzonej KB | 1.7 |
|
||||
| 1.28.6 | 2026-11-11 | Przeniesienie poprawek 2.0.5 na `1.x`, bez nowych funkcji: listy rutyn od kolumny 0, `--do` z escape'ami, `--remove` z wierszami kontynuacji; redakcja `<private>` przez bloki wiadomości; cytowanie w OKF i tytuły poza blokami kodu; tokeny Unicode w wyszukiwaniu; ochrona przed złą datą w workload, frontmatter na końcu pliku, odwołania `wiki/` bez ukośnika, kolizje ścieżek w Starlight, wikilinki z etykietą, sekcje strony startowej, `<private>` usuwane z eksportów. Te same testy co w 2.0.5 | 1.7 |
|
||||
| 1.28.5 | 2026-11-11 | Przeniesienie poprawek 2.0.4 na `1.x`, bez nowych funkcji: szerszy skan sekretów (ukryte foldery, pliki kluczy, pliki z kropką, tekst bez rozszerzenia, niecytowane przypisania wyglądające na sekret, zgłaszanie zbyt dużych plików); wyszukiwanie mcp filtrowane polityką odczytu, odmowa `.local.yaml` niezależna od wielkości liter, tylko zweryfikowany e-mail z OAuth, ochrona przed DNS rebinding domyślnie włączona, jednorazowe kody potwierdzenia; capture zawsze odrzuca link-local i metadane, a sieci prywatne bez `--allow-private`, limit całego pobierania, zapas kodowania, strony z `<form>`, bezpieczne nazwy plików binarnych. Zredukowany zestaw sekretów w zapasowym skrypcie PowerShell bez zmian. Te same testy co w 2.0.4 | 1.7 |
|
||||
| 1.28.4 | 2026-11-11 | Przeniesienie poprawek dla Windows z 2.0.3 na `1.x`, bez nowych funkcji: wyjście UTF-8 i dekodowanie podprocesów w każdym skrypcie, stdin hooka w UTF-8, odczyt `utf-8-sig` dla plików z BOM, odciski pasujące do checkoutu z LF albo CRLF i do krótkich prefiksów (`lint_report.py`, `lint_quick.sh`, `consolidate.py`, a na tej linii także `lint_quick.ps1`, którego CI nie uruchamia), ścieżki POSIX w wyjściu lintu i `rg --path-separator /`, instalatory hooków domyślnie wpisujące uruchamiający je interpreter, ze ścieżką w cudzysłowie i sprawdzeniem, czy nadal istnieje. Te same testy co w 2.0.3 | 1.7 |
|
||||
| 1.28.3 | 2026-11-11 | Przeniesienie poprawek 2.0.2 na `1.x`, bez nowych funkcji: w `share` nazwy i identyfikatory wiadomości są sprawdzane (bez wstrzykiwania do `ckb.yaml`, bez zapisu poza `raw/inbox/`), każdy commit wiadomości musi pochodzić od właściciela skrzynki, podwójny wpis w `members.yaml` odbiera skrzynce właściciela, tylko zweryfikowane wycofanie ukrywa pocztę, gałąź i URL kanału są sprawdzane przed gitem, odebrane kopie zawsze mają `untrusted: true`, `<private>` usuwane z tytułu i `tldr`, bez skanu sekretów nie ma wysyłki; w `capture` cytowanie frontmattera i jednoliniowe tytuły; sprawdzenie 13 lintu przyjmuje Crux przypisany rozmowie bez `## Sources`. Te same testy co w 2.0.2 | 1.7 |
|
||||
| 1.28.2 | 2026-11-11 | Przeniesienie poprawek 2.0.1 na `1.x`, bez nowych funkcji: zgodność z Pythonem 3.8 (`removeprefix`/`removesuffix` zastąpione w lincie, wyszukiwaniu, konsolidacji i serwerze mcp), `routines.py --mark` zapisujące `last_run:2026-…` i połykające komentarze, `export_okf.py --out` ograniczone do `outputs/`, kopie obrazów w Starlight ograniczone do `wiki/assets/`, liczba skryptów w `AGENTS.md`, README i podręcznikach. Ten sam zestaw `tests/unit/`, uruchamiany przez `smoke.sh` | 1.7 |
|
||||
| 1.28.1 | 2026-11-11 | Kanał wydawniczy `1.x`: gałąź utrzymaniowa linii 1.x po wydaniu 2.0, tylko poprawki, ostatnia z obsługą PowerShella (D-0019). Dopisany do tabel kanałów w `ckb-init`, `ckb-upgrade`, `AGENTS.md`, obu README i obu podręcznikach oraz do komentarza w `ckb.yaml`. `ckb-upgrade` krok 2: wyższa wersja **główna** w źródle zatrzymuje przebieg przed krokiem 4, cytuje przełomową część wiersza changeloga i proponuje nową wersję główną albo przejście na gałąź utrzymaniową; nigdy nie przechodzi przez nią z rutyny ani trybu wsadowego | 1.7 |
|
||||
| 1.28.0 | 2026-11-11 | Nowy opcjonalny moduł `share` (D-0018): skill `ckb-share` i `share.py` (`join`/`send`/`unshare`/`list`/`receive`/`status`, biblioteka standardowa + git). **Kanał** to osobne repozytorium git na grupę zaufania z `CHANNEL.md`, `members.yaml` (baza → e-maile właścicieli) i jedną skrzynką tylko do dopisywania na bazę, `mail/<baza>/`, klonowane do `tmp/share/<kanał>/`. **Wysyłka** pakuje samodzielną kopię strony z `outputs/documents/`, `outputs/answers/` lub `wiki/` (`raw/archive/` tylko z `--raw-ok`): bez fragmentów `<private>` i `## Notes`, linki lokalne jako tekst, ścieżki w Sources/Crux oznaczone `<baza>:`; koperta `type: share`, `kind`, `share_id`, `version`, `from`, `to`, `sent_by`, `untrusted: true`; wzorce sekretów z lintu blokują wysyłkę (kod 3), próba pokazuje sekcję wrażliwości z `ABOUT.md`, użytkownik potwierdza. Ponowna wysyłka tworzy kolejną wersję. **Odbiór** kopiuje wiadomości do bazy do `raw/inbox/` z `share_channel`, `share_ref`, `received_on`, `submitted_by` (autor w gicie) i `supersedes_source`; wiadomość, której autor nie jest właścicielem skrzynki, jest NIEZWERYFIKOWANA i brana tylko z `--accept-unverified`; wycofanie staje się żądaniami w `raw/retractions/` dla każdej posiadanej wersji. Rejestr `received:` w należącym do skryptu bloku `share:` w `ckb.yaml` nie pozwala obsłużonym wiadomościom wrócić. `dedup_inbox.py` zgłasza `SAME SHARE`; `ckb-ingest` i `ckb-retract` znają pliki i żądania z share. Test dymny obejmuje dwie bazy i kanał na gołym repozytorium od początku do końca | 1.7 |
|
||||
| 1.27.0 | 2026-11-02 | Nowy skill bazowy `ckb-feynman`, zaadaptowany ze skilla `feynman` z superhero-tech-super-brain: wyjaśnia jedną stronę prostymi słowami na konkretnym przykładzie, z linią `→ [[page]] · [Tytuł § Nagłówek](/wiki/…#kotwica)` pod każdym fragmentem, potem przypisuje każde rozrzedzone miejsce do luk Wiki, Źródła lub Moje, nie łatając żadnej wiedzą modelu, prosi o wyjaśnienie z powrotem i kończy ponumerowanymi kolejnymi krokami. Kandydaci to strony `review: draft`/`needs_update`, z jednym źródłem, nieaktualne lub ze sprzecznością; strony tematyczne prowadzą do stron członkowskich; odciski Crux sprawdzane jak w kroku 6 `ckb-retrieve`; fragmenty `<private>` nigdy nie są wyjaśniane. Sesje trafiają do `outputs/teaching/feynman/YYYY-MM-DD_<slug>.md` (`type: feynman-session`, `## Sources` z odciskami, ignorowane przez gita razem z `outputs/teaching/`, bez wpisu w `wiki/log.md`); luka w źródłach trafia do `wiki/query-gaps.md` tylko po zgodzie. `ckb-teach-me` pomija ten folder; zaktualizowane `ckb-init`, wiersz routingu w `AGENTS.md`, oba README i oba podręczniki; przypadek eval `ckb-feynman/session` z zapisanym przebiegiem wzorcowym (6/6). `outputs/teaching/` dodane do kontraktu katalogów; `run_evals.py` dopasowuje usunięte pliki semantyką glob (`**` było jednym segmentem) | 1.7 |
|
||||
|
|
@ -436,29 +407,14 @@ Wersje 1.4.0 i 1.5.0 nigdy nie zostały opublikowane — szablon przeskoczył z
|
|||
|
||||
## Kanały wydawnicze
|
||||
|
||||
Repozytorium szablonu utrzymuje cztery gałęzie wydań i jedną integracyjną:
|
||||
Repozytorium szablonu utrzymuje trzy gałęzie, a powyższe historie wersji
|
||||
śledzą wyłącznie `main`:
|
||||
|
||||
| Gałąź | Czym jest | Kto powinien ją śledzić |
|
||||
|---|---|---|
|
||||
| `main` | **Stabilna** — wydany szablon | Wszyscy, domyślnie |
|
||||
| `test` | **Kandydat do wydania** — walidowany przed scaleniem do `main` | Każdy, kto pomaga walidować wydanie |
|
||||
| `experimental` | **Podglądowa** — zmiany scalone z `dev` wcześnie, mogą być zepsute albo wycofane | Osoby rozwijające sam szablon |
|
||||
| `1.x` | **Utrzymaniowa** — poprawki linii 1.x, ostatniej z PowerShellem | KB, które potrzebują PowerShella |
|
||||
| `dev` | **Integracyjna** — tu najpierw trafia każda zmiana | Nikt: to nie jest kanał |
|
||||
|
||||
**Jak powstaje wersja (D-0022).** `VERSION` i historia w tym pliku zmieniają
|
||||
się tylko przy scaleniu `dev` do innej gałęzi, nigdy przez commit na `dev`.
|
||||
Scalenie dostaje kolejny numer według zwykłej zasady (główna dla zmian
|
||||
łamiących, poboczna dla funkcji, poprawkowa dla poprawek; wygrywa najwyższy
|
||||
rodzaj w scaleniu) i dopisuje tu swój wiersz. Wersja zachowuje numer przy
|
||||
promocji: `dev` → `experimental` → `test` → `main`, `dev` → `test` → `main`
|
||||
albo `dev` → `main`. Scalenie `dev` zabiera wszystko, co na niej jest, więc
|
||||
wprost do `main` scalaj tylko wtedy, gdy cała `dev` jest gotowa do wydania.
|
||||
Gdy wersja trafi do `main`, `main` jest scalana z powrotem do `dev`, `test` i
|
||||
`experimental`, żeby `dev` zaczynała od wydanej wersji, a żaden kanał nie
|
||||
został w tyle za stabilnym. `1.x` jest
|
||||
poza tym przepływem: jej poprawki są commitowane i numerowane bezpośrednio na
|
||||
niej.
|
||||
| `experimental` | **Rozwojowa** — bieżąca praca, może być zepsuta albo wycofana | Osoby rozwijające sam szablon |
|
||||
|
||||
Śledzona przez KB gałąź mieszka w `ckb.yaml`:
|
||||
|
||||
|
|
|
|||
|
|
@ -46,7 +46,7 @@ Python is *recommended*, not strictly required:
|
|||
|
||||
| Without Python | What happens |
|
||||
|---|---|
|
||||
| Session-start health check | A bash fallback runs instead (on Windows, under Git Bash, which comes with Git for Windows). It covers malformed pages, stale pages, changed sources and the commonest secret shapes, and says that crux quotes and the context budget were not checked. |
|
||||
| Session-start health check | A bash/PowerShell fallback runs instead. It covers malformed pages, stale pages, changed sources and the commonest secret shapes, and says that crux quotes and the context budget were not checked. |
|
||||
| "Ingest" duplicate check | The agent compares `sha256sum` digests of inbox and archive files by hand and skips the URL comparison. |
|
||||
| "Lint" | The agent works a manual checklist with `grep`. It's slower and scoped, and it says what it skipped. |
|
||||
| Questions | The agent ranks candidates by hand from the indexes and `grep` instead of the fusion script. |
|
||||
|
|
@ -99,24 +99,6 @@ If the target folder already looks like a KB (it has a `wiki/` or
|
|||
`AGENTS.md` already), the agent stops and asks before touching anything. It
|
||||
won't silently overwrite an existing knowledge base.
|
||||
|
||||
### Creating or joining a shared wiki from anywhere
|
||||
|
||||
Two skills are meant for your own agent profile (`~/.claude/skills/`), not
|
||||
for a KB, so they work before any KB exists on your machine. Install them
|
||||
once from [`user-skills/`](../user-skills/README.md):
|
||||
|
||||
- **`ckb-create`** - "Create a new wiki in `~/kb/team` with origin
|
||||
`<url>`". Give it an *empty* repository on your git host. It fetches the
|
||||
current template, builds the KB with that template's `ckb-init`, commits
|
||||
on `main` and pushes, then gives you a line to forward to colleagues.
|
||||
- **`ckb-join`** - "Join the knowledge base at `<url>`", optionally "into
|
||||
`<folder>`". It clones the KB, checks it really is one, and tells you
|
||||
what still needs fixing on your machine: git identity, symlinks on
|
||||
Windows, `linked/` mounts that point at someone else's disk, Python.
|
||||
|
||||
Neither skill commits to an existing KB. After either one, open the folder
|
||||
in your agent and carry on there.
|
||||
|
||||
### Building on top of someone else's wiki
|
||||
|
||||
A Cascade KB can sit on top of one or more *upstream* knowledge bases,
|
||||
|
|
@ -302,16 +284,6 @@ marks the old one superseded - without touching the old page's reasoning.
|
|||
Anything you leave out, it asks for in one round; if you're mid-flow, say so
|
||||
and it records what you gave it and tells you which fields it left open.
|
||||
|
||||
It also asks what the decision should change and when you'd expect to see
|
||||
it ("reporting runs in Postgres alone by March"). That goes down *before*
|
||||
anyone knows the result, as `expected_outcome` with a `review_on` date.
|
||||
When the date comes, lint reminds you; say "review decision 7" and the agent
|
||||
records what actually happened (met, partly, missed, unclear) in the
|
||||
page's `## Outcome`, without touching anything written earlier. Anything
|
||||
you built or tested and dropped on the way goes under `## Tried`. If a
|
||||
later decision picks one of those again, the agent points that out and asks
|
||||
what has changed since.
|
||||
|
||||
Then ask about them however you like:
|
||||
|
||||
> "What did we decide about the billing database?"
|
||||
|
|
@ -375,9 +347,7 @@ This runs a health check across the whole wiki:
|
|||
that source, since it tells you who to chase
|
||||
- pages whose source has actually changed get flagged - see below
|
||||
- quotes that no longer appear in the source they cite get flagged
|
||||
- recurring systemic issues get written into `wiki/error-book.md`, one
|
||||
entry per problem with every fix tried, what each was expected to stop,
|
||||
and what the following lint runs saw
|
||||
- recurring systemic issues get written into `wiki/error-book.md`
|
||||
- credentials committed by accident (keys, tokens, private keys, a password
|
||||
in a URL) anywhere in `wiki/`, `outputs/`, `workload/` or `raw/`, and any
|
||||
`<private>` passage that leaked into a wiki page, get flagged - never
|
||||
|
|
@ -670,22 +640,16 @@ Say:
|
|||
|
||||
### Which channel you're pulling from
|
||||
|
||||
The template repo keeps four release branches, and by default you get the
|
||||
stable one:
|
||||
The template repo keeps four branches, and by default you get the stable
|
||||
one:
|
||||
|
||||
| Branch | What it is | Who should be on it |
|
||||
|---|---|---|
|
||||
| `main` | **Stable** - the released template | You, unless you have a reason not to be |
|
||||
| `test` | **Release candidate** - validated before it reaches `main` | You're helping validate a release, or you need a fix that's landed but not shipped |
|
||||
| `experimental` | **Preview** - work merged from `dev` early, may be broken or reverted | You're developing the template itself |
|
||||
| `experimental` | **Development** - active work, may be broken or reverted | You're developing the template itself |
|
||||
| `1.x` | **Maintenance** - the 1.x line after 2.0: fixes only; the last line with PowerShell support | You need PowerShell, or can't move to 2.0 yet |
|
||||
|
||||
There is a fifth branch, `dev`, where template work lands first. It is not a
|
||||
channel: the version only changes when `dev` is merged into one of the four
|
||||
above, so an upgrade from `dev` would never find anything newer. Changes
|
||||
travel `dev` → `experimental` → `test` → `main`, `dev` → `test` → `main`, or
|
||||
straight `dev` → `main`, keeping their version number along the way.
|
||||
|
||||
To use a different one, say which:
|
||||
|
||||
> "Upgrade from the test branch." / "Check experimental for updates." /
|
||||
|
|
@ -963,14 +927,6 @@ Nothing becomes a lesson unless you ask. A lesson that should bind everyone
|
|||
always belongs in `AGENTS.md`; the agent will suggest that rather than edit
|
||||
it. Skill: `.agents/skills/ckb-profile/SKILL.md`.
|
||||
|
||||
Each lesson notes the context it came from: the agent/model and the template
|
||||
version. After a model or template change, the agent treats older lessons
|
||||
as strong hints to recheck rather than settled facts. If your KB links
|
||||
another KB under `linked/`, that KB's new lessons appear in your brief as
|
||||
*upstream*; they rank below your own, and "adopt that lesson" copies one in.
|
||||
When you create a new KB from this one, `ckb-init` offers to carry lessons
|
||||
and error-book problems across.
|
||||
|
||||
### Save a conversation
|
||||
|
||||
Every new session gets a title the agent picks from your first message
|
||||
|
|
@ -1120,8 +1076,6 @@ install one. Say:
|
|||
| `software` | The KB documents software you're building: source repos as gitignored clones in `src/`, code mapped into wiki entities, and specs with OpenSpec | [OPENSPEC.md](OPENSPEC.md) · [module README](../.agents/modules/software/README.md) |
|
||||
| `capture` | Save links, articles, PDFs and video transcripts into `raw/inbox/` as dated snapshots, with a Wayback fallback and duplicate check | [module README](../.agents/modules/capture/README.md) |
|
||||
| `share` | Send a document to another KB through a shared git repo (one append-only mailbox per KB), and take what other KBs sent into `raw/inbox/`, with versions, retractions and a sender check | [module README](../.agents/modules/share/README.md) |
|
||||
| `voice` | Write everything the KB sends out (kept answers, documents, reports, the project overview) in your team's voice, from a profile kept as a wiki page in `wiki/voice/`. Wording changes; facts, quotes, sources and code don't | [module README](../.agents/modules/voice/README.md) |
|
||||
| `convert` | Turn any Markdown file (a document from a template, a kept answer, a report) into Word, ODT, PDF or HTML through pandoc, in a house style kept in `templates/styles/`: describe it ("Georgia 11pt, navy headings, A4") or bring your company's Word template | [module README](../.agents/modules/convert/README.md) |
|
||||
| `mcp` | Use the KB from Claude's web/desktop/mobile apps, Claude Code or another agent through an MCP server: search, read, add material, undo a misfiled submission. Several KBs can be connected at once | [MCP.md](MCP.md) · [module README](../.agents/modules/mcp/README.md) |
|
||||
|
||||
Skill: `.agents/skills/ckb-module/SKILL.md`.
|
||||
|
|
|
|||
|
|
@ -48,7 +48,7 @@ Python jest *zalecany*, nie bezwzględnie wymagany:
|
|||
|
||||
| Bez Pythona | Co się dzieje |
|
||||
|---|---|
|
||||
| Kontrola na starcie sesji | Zamiast niej działa zapasowy skrypt bash (na Windows w Git Bash, dołączonym do Git for Windows). Wykrywa strony uszkodzone, przeterminowane, zmienione źródła i najczęstsze postaci sekretów; zaznacza, że cytaty Crux i budżet kontekstu nie zostały sprawdzone. |
|
||||
| Kontrola na starcie sesji | Zamiast niej działa zapasowy skrypt bash/PowerShell. Wykrywa strony uszkodzone, przeterminowane, zmienione źródła i najczęstsze postaci sekretów; zaznacza, że cytaty Crux i budżet kontekstu nie zostały sprawdzone. |
|
||||
| Sprawdzanie duplikatów przy „Ingest” | Agent ręcznie porównuje skróty `sha256sum` plików ze skrzynki i archiwum, a porównanie adresów URL pomija. |
|
||||
| „Lint” | Agent przechodzi ręczną listę kontrolną z `grep` — wolniej, w ograniczonym zakresie, i mówi, co pominął. |
|
||||
| Pytania | Agent szereguje kandydatów ręcznie z indeksów i `grep` zamiast skryptu fuzji. |
|
||||
|
|
@ -103,26 +103,6 @@ Jeśli docelowy folder wygląda już jak baza wiedzy (ma `wiki/` lub
|
|||
`AGENTS.md`), agent zatrzyma się i zapyta, zanim czegokolwiek dotknie — nie
|
||||
nadpisze po cichu istniejącej bazy wiedzy.
|
||||
|
||||
### Tworzenie wspólnej wiki albo dołączanie do niej z dowolnego miejsca
|
||||
|
||||
Dwa skille są przeznaczone do twojego profilu agenta (`~/.claude/skills/`),
|
||||
a nie do KB, więc działają, zanim na twoim komputerze powstanie jakakolwiek
|
||||
KB. Zainstaluj je raz z [`user-skills/`](../user-skills/README.md):
|
||||
|
||||
- **`ckb-create`** - „Create a new wiki in `~/kb/team` with origin
|
||||
`<url>`”. Podaj mu *puste* repozytorium na swoim serwerze git. Pobiera
|
||||
aktualny szablon, buduje KB za pomocą `ckb-init` z tego szablonu, robi
|
||||
commit na `main` i push, a na koniec daje ci zdanie do przekazania
|
||||
współpracownikom.
|
||||
- **`ckb-join`** - „Join the knowledge base at `<url>`”, opcjonalnie „into
|
||||
`<folder>`”. Klonuje KB, sprawdza, czy to naprawdę KB, i mówi, co jeszcze
|
||||
trzeba poprawić na twoim komputerze: tożsamość git, dowiązania
|
||||
symboliczne na Windowsie, montowania `linked/` wskazujące na cudzy dysk,
|
||||
Pythona.
|
||||
|
||||
Żaden z nich nie robi commitów do istniejącej KB. Po każdym otwórz folder w
|
||||
agencie i pracuj dalej tam.
|
||||
|
||||
### Budowanie na bazie cudzej wiki
|
||||
|
||||
Cascade KB może opierać się na jednej lub wielu *nadrzędnych* bazach
|
||||
|
|
@ -314,15 +294,6 @@ zastąpioną — nie ruszając jej uzasadnienia. O to, czego nie podasz, dopyta
|
|||
jednej turze; jeśli jesteś w środku pracy, powiedz to, a zapisze, co ma, i
|
||||
wskaże, które pola zostawił otwarte.
|
||||
|
||||
Zapyta też, co decyzja ma zmienić i kiedy powinno to być widać („raporty
|
||||
działają na samym Postgresie do marca”). Zapisuje to *zanim* znany jest
|
||||
wynik, jako `expected_outcome` z datą `review_on`. Gdy data nadejdzie, lint
|
||||
przypomni; powiedz „review decision 7”, a agent zapisze, co faktycznie się
|
||||
stało (met, partly, missed, unclear) w sekcji `## Outcome`, nie ruszając
|
||||
niczego zapisanego wcześniej. To, co po drodze zbudowano lub przetestowano i
|
||||
porzucono, trafia do `## Tried`. Jeśli późniejsza decyzja znów wybiera coś
|
||||
stamtąd, agent to zauważy i zapyta, co się od tego czasu zmieniło.
|
||||
|
||||
Potem pytaj, jak chcesz:
|
||||
|
||||
> „Co zdecydowaliśmy w sprawie bazy danych billingu?"
|
||||
|
|
@ -391,9 +362,7 @@ To uruchamia przegląd kondycji całej wiki:
|
|||
patrz niżej
|
||||
- cytaty, których nie ma już w źródle, na które się powołują, zostają
|
||||
oflagowane
|
||||
- powtarzające się problemy systemowe trafiają do `wiki/error-book.md`,
|
||||
jeden wpis na problem, z każdą wypróbowaną naprawą, tym, czemu miała
|
||||
zapobiec, i tym, co pokazały kolejne przebiegi lintu
|
||||
- powtarzające się problemy systemowe trafiają do `wiki/error-book.md`
|
||||
- przypadkowo zacommitowane dane uwierzytelniające (klucze, tokeny, klucze
|
||||
prywatne, hasło w adresie URL) gdziekolwiek w `wiki/`, `outputs/`,
|
||||
`workload/` lub `raw/`, a także fragment `<private>`, który trafił na
|
||||
|
|
@ -700,22 +669,16 @@ Powiedz:
|
|||
|
||||
### Z jakiego kanału pobierasz
|
||||
|
||||
Repozytorium szablonu utrzymuje cztery gałęzie wydań i domyślnie dostajesz
|
||||
tę stabilną:
|
||||
Repozytorium szablonu utrzymuje cztery gałęzie i domyślnie dostajesz tę
|
||||
stabilną:
|
||||
|
||||
| Gałąź | Czym jest | Kto powinien na niej być |
|
||||
|---|---|---|
|
||||
| `main` | **Stabilna** — wydany szablon | Ty, o ile nie masz powodu, żeby być gdzie indziej |
|
||||
| `test` | **Kandydat do wydania** — walidowany, zanim trafi do `main` | Pomagasz walidować wydanie albo potrzebujesz poprawki, która weszła, ale nie została wydana |
|
||||
| `experimental` | **Podglądowa** — zmiany scalone z `dev` wcześnie, mogą być zepsute albo wycofane | Rozwijasz sam szablon |
|
||||
| `experimental` | **Rozwojowa** — bieżąca praca, może być zepsuta albo wycofana | Rozwijasz sam szablon |
|
||||
| `1.x` | **Utrzymaniowa** — linia 1.x po wydaniu 2.0: tylko poprawki; ostatnia z obsługą PowerShella | Potrzebujesz PowerShella albo nie możesz jeszcze przejść na 2.0 |
|
||||
|
||||
Jest też piąta gałąź, `dev`, na którą najpierw trafia praca nad szablonem. To
|
||||
nie jest kanał: wersja zmienia się dopiero przy scaleniu `dev` do jednej z
|
||||
czterech powyższych, więc upgrade z `dev` nigdy nie znalazłby nic nowszego.
|
||||
Zmiany idą `dev` → `experimental` → `test` → `main`, `dev` → `test` → `main`
|
||||
albo wprost `dev` → `main`, zachowując po drodze swój numer wersji.
|
||||
|
||||
Żeby użyć innej, powiedz której:
|
||||
|
||||
> „Upgrade from the test branch.” / „Check experimental for updates.” /
|
||||
|
|
@ -1006,14 +969,6 @@ Nic nie staje się lekcją, jeśli o to nie poprosisz. Lekcja, która ma zawsze
|
|||
obowiązywać wszystkich, należy do `AGENTS.md`; agent to zasugeruje, zamiast go
|
||||
edytować. Skill: `.agents/skills/ckb-profile/SKILL.md`.
|
||||
|
||||
Każda lekcja zapisuje kontekst, z którego pochodzi: agenta/model i wersję
|
||||
szablonu. Po zmianie modelu lub szablonu agent traktuje starsze lekcje jako
|
||||
mocne wskazówki do sprawdzenia, a nie pewniki. Jeśli twoja KB podpina inną
|
||||
w `linked/`, nowe lekcje tamtej pojawiają się w twoim podsumowaniu jako
|
||||
*zewnętrzne* (upstream); są niżej niż twoje, a „adopt that lesson” kopiuje
|
||||
jedną do ciebie. Przy tworzeniu nowej KB z tej `ckb-init` proponuje
|
||||
przeniesienie lekcji i problemów z księgi błędów.
|
||||
|
||||
### Zapisywanie rozmowy
|
||||
|
||||
Każda nowa sesja dostaje tytuł, który agent sam wybiera na podstawie
|
||||
|
|
@ -1172,8 +1127,6 @@ nieaktywne, dopóki ich nie zainstalujesz. Powiedz:
|
|||
| `software` | Baza dokumentuje tworzone oprogramowanie: repozytoria jako ignorowane klony w `src/`, kod mapowany na encje wiki, specyfikacje z OpenSpec | [OPENSPEC.pl.md](OPENSPEC.pl.md) · [README modułu](../.agents/modules/software/README.pl.md) |
|
||||
| `capture` | Zapisywanie linków, artykułów, PDF-ów i transkrypcji filmów w `raw/inbox/` jako datowanych zrzutów, z Wayback w razie niepowodzenia i sprawdzaniem duplikatów | [README modułu](../.agents/modules/capture/README.pl.md) |
|
||||
| `share` | Wysyłanie dokumentu do innej bazy przez wspólne repozytorium git (jedna skrzynka na bazę, tylko dopisywanie) i odbieranie tego, co wysłały inne bazy, do `raw/inbox/` — z wersjami, wycofaniami i sprawdzeniem nadawcy | [README modułu](../.agents/modules/share/README.md) |
|
||||
| `voice` | Wszystko, co baza wysyła na zewnątrz (zachowane odpowiedzi, dokumenty, raporty, przegląd projektu), pisane głosem zespołu według profilu trzymanego jako strona wiki w `wiki/voice/`. Zmieniają się sformułowania; fakty, cytaty, źródła i kod — nie | [README modułu](../.agents/modules/voice/README.md) |
|
||||
| `convert` | Zamiana dowolnego pliku Markdown (dokumentu z szablonu, zachowanej odpowiedzi, raportu) na Word, ODT, PDF lub HTML przez pandoca, w stylu firmowym trzymanym w `templates/styles/`: wystarczy go opisać („Georgia 11pt, granatowe nagłówki, A4”) albo przynieść firmowy szablon Worda | [README modułu](../.agents/modules/convert/README.pl.md) |
|
||||
| `mcp` | Korzystanie z bazy w aplikacjach Claude (web/desktop/mobile), Claude Code lub innym agencie przez serwer MCP: wyszukiwanie, odczyt, dodawanie materiału, cofanie źle skierowanego zgłoszenia. Można podłączyć kilka baz naraz | [MCP.pl.md](MCP.pl.md) · [README modułu](../.agents/modules/mcp/README.pl.md) |
|
||||
|
||||
Skill: `.agents/skills/ckb-module/SKILL.md`.
|
||||
|
|
|
|||
|
|
@ -1,89 +0,0 @@
|
|||
---
|
||||
type: decision
|
||||
tldr: Outgoing text gets a team voice through an opt-in `voice` module — profiles are wiki pages in wiki/voice/ (type voice-profile), settings live in ckb.yaml, an AGENTS.md block routes every prose file under apply_to through ckb-voice, frozen spans (frontmatter, Sources, Crux, quotes, Notes, code, numbers, names) never change, and an external rewriting skill can be plugged in with `writer:`.
|
||||
status: accepted
|
||||
decided_on: 2026-11-11
|
||||
decided_by: Michał Kopeć
|
||||
affects: .agents/modules/voice/, .agents/skills/ckb-module/SKILL.md, README.md, docs/MANUAL.md, docs/CHANGELOG.md
|
||||
confidence: 0.7
|
||||
quality: 0.8
|
||||
last_updated: 2026-11-11
|
||||
freshness_window_days: 365
|
||||
retention: high
|
||||
---
|
||||
|
||||
# D-0020 — A voice module for text that leaves the KB
|
||||
|
||||
**Status:** Accepted · **Decided:** 2026-11-11 · **Deciders:** Michał Kopeć
|
||||
|
||||
## Context
|
||||
|
||||
Kept answers, documents from templates, consolidation reports and the
|
||||
project overview are read by people outside the KB, and they read like a
|
||||
model wrote them. Michał already runs a personal `ghost-writer` skill
|
||||
(banned AI vocabulary, rhythm, the abstraction trap, named voice profiles)
|
||||
in his home directory, and wanted the same pass on everything the KB sends
|
||||
out, with the profile kept in the KB itself so the team can maintain it.
|
||||
|
||||
## Decision
|
||||
|
||||
1. **An opt-in module** (D-0001 pattern), `voice`, with one skill,
|
||||
`ckb-voice`, and no script. Many KBs never publish anything, so the base
|
||||
pays no context for it.
|
||||
2. **The profile is a wiki page**, `wiki/voice/<name>.md`, `type:
|
||||
voice-profile`, with `voice_of` (team/person/third-party) and the usual
|
||||
`## Sources` and protected `## Notes`. It is knowledge the team reviews
|
||||
and corrects. A skill-folder file would be invisible to teammates and
|
||||
lost on a clone. Pages are created, and logged, by `ckb-voice` on the
|
||||
first calibration, never by the install.
|
||||
3. **Settings live in `ckb.yaml`** under the module's `config:` (`mode`,
|
||||
`profile`, `writer`, `apply_to`, `skip`, `chat`). `ckb-module` gains
|
||||
`default_config` in the manifest to write them on install and keeps
|
||||
edited values on a reinstall.
|
||||
4. **The hook is the `AGENTS.md` block, not edits to each skill.** The
|
||||
installed fragment says that any prose file written under `apply_to`
|
||||
goes through `ckb-voice`, whichever skill drafted it. `ckb-document`,
|
||||
`ckb-retrieve`, `ckb-consolidate` and `ckb-project-summary` stay
|
||||
unchanged, and a future skill writing to `outputs/` is covered without
|
||||
a change.
|
||||
5. **Wording only; content is frozen.** Frontmatter, `## Sources`, `## Crux`,
|
||||
quotes and their attributions, `## Notes`/`## Rules`, contradiction
|
||||
markers, `<private>` spans, code, paths, links, numbers, names and a
|
||||
template's headings are kept byte-for-byte and diffed before writing.
|
||||
Ghost-writer's rule to cut any claim that can't be made specific is
|
||||
inverted. Such a claim is kept and flagged, because in a KB its source
|
||||
may say more and dropping it changes the content.
|
||||
6. **Profile precedence:** named in the request, then `voice:` on the
|
||||
person's `workload/profiles/` page, then the configured default. Never
|
||||
two profiles in one text.
|
||||
7. **Pluggable writer.** `writer:` can name another installed skill (a
|
||||
personal `ghost-writer`). `ckb-voice` still resolves the profile and runs
|
||||
the freeze check; when the skill is missing on a machine it falls back to
|
||||
its own rules.
|
||||
8. **Out of scope by construction:** `wiki/`, `raw/`, `workload/`,
|
||||
`templates/`, and the exports (`outputs/okf/`, `outputs/starlight/`),
|
||||
which mirror wiki pages rather than speak for anyone.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
- **Depend on the user's home `ghost-writer`.** It's not in the repo, so
|
||||
teammates wouldn't have it and the profile would live outside the KB.
|
||||
It's kept as an option through `writer:`.
|
||||
- **Profiles in `workload/profiles/` beside personal profiles.** Those are
|
||||
per person and outside retrieval; a house voice is shared knowledge that
|
||||
deserves review status and a log.
|
||||
- **A rewrite step in every output-writing skill.** Four skills to edit now,
|
||||
and every future one to remember. The single `AGENTS.md` rule does the
|
||||
same job.
|
||||
- **Rewrite wiki pages too.** The wiki is evidence for retrieval and lint;
|
||||
voice belongs at the boundary, not in the store.
|
||||
|
||||
## Consequences
|
||||
|
||||
- One more page type, `voice-profile`, and one field, `voice`, additive on
|
||||
schema 1.7 with no version bump.
|
||||
- A rewrite costs a model pass per output file; `mode: ask` or `off` turns
|
||||
it down.
|
||||
- The freeze check runs in the agent, not in a script, so it is only as
|
||||
strict as the agent following it. A script diffing frozen spans is the
|
||||
natural follow-up if drift shows up.
|
||||
|
|
@ -1,90 +0,0 @@
|
|||
---
|
||||
type: decision
|
||||
tldr: Markdown leaves the KB as Word/ODT/PDF/HTML through an opt-in `convert` module — pandoc does the conversion, the look is a named reference .docx in templates/styles/ that a stdlib script can build or adjust from a few settings or copy from a company .docx/.dotx, PDF and ODT go through LibreOffice from the styled .docx so every format matches, and the Markdown stays the source.
|
||||
status: accepted
|
||||
decided_on: 2026-11-11
|
||||
decided_by: Michał Kopeć
|
||||
affects: .agents/modules/convert/, tests/unit/test_convert.py, tests/evals/ckb-module/install-convert/, README.md, docs/MANUAL.md, docs/CHANGELOG.md
|
||||
confidence: 0.75
|
||||
quality: 0.8
|
||||
last_updated: 2026-11-11
|
||||
freshness_window_days: 365
|
||||
retention: high
|
||||
---
|
||||
|
||||
# D-0021 — A convert module for documents that leave as Office files
|
||||
|
||||
**Status:** Accepted · **Decided:** 2026-11-11 · **Deciders:** Michał Kopeć
|
||||
|
||||
## Context
|
||||
|
||||
`ckb-document`, kept answers and reports all write Markdown. The people they
|
||||
go to want a Word file or a PDF in the company's look. `ckb-document` Step 4
|
||||
says to make a `.docx` "with the general document skills", which leaves the
|
||||
fonts, sizes and margins to whatever the agent picks each time. Michał wanted
|
||||
a pandoc front end with design templates, so users get a consistent document
|
||||
without thinking about typography.
|
||||
|
||||
## Decision
|
||||
|
||||
1. **An opt-in module** (D-0001 pattern), `convert`, with one skill,
|
||||
`ckb-convert`, and one stdlib script, `convert.py`. pandoc is a system
|
||||
tool not every KB needs.
|
||||
2. **A style is a reference `.docx`** in `templates/styles/<name>.docx`,
|
||||
pandoc's own mechanism: it takes styles, page setup, header and footer
|
||||
from it and ignores the text. Optional `<name>.odt` and `<name>.css` cover
|
||||
ODT and HTML. `templates/` already holds the user's document templates and
|
||||
isn't a retrieval layer. `ckb-document` lists only `templates/*.md`, so the
|
||||
subfolder doesn't clash.
|
||||
3. **Styles from settings, not by hand.** `new-style`/`edit-style` copy
|
||||
pandoc's default reference and patch body font, heading font, body size,
|
||||
heading colour, paper (A4/Letter) and margins straight into
|
||||
`styles.xml`, `theme1.xml` and the body `sectPr`, keeping the schema's
|
||||
child order so Word opens the result. `--from` takes a company `.docx` or
|
||||
`.dotx` (content type rewritten) and `check-style` lists the styles pandoc
|
||||
uses that it lacks. Anything richer (logos, cover pages) is edited in
|
||||
Word, and the skill says so.
|
||||
4. **One look for every format.** PDF and ODT are produced by LibreOffice from
|
||||
the styled `.docx`, in a private profile so an open LibreOffice doesn't
|
||||
block it. Without LibreOffice, PDF falls back to a pandoc PDF engine and
|
||||
the skill reports that the style wasn't applied.
|
||||
5. **KB Markdown is cleaned for an outside reader**, in the copy only:
|
||||
frontmatter → title/author/date/lang metadata (e-mail dropped), the
|
||||
leading `# H1` → title, template comments dropped, wikilinks and KB-path
|
||||
links → text (`keep_links` opts out), code blocks untouched.
|
||||
6. **The Markdown stays the source**, always kept. An existing converted file
|
||||
is never overwritten without `--force`; the skill asks, since it may have
|
||||
been edited in Word.
|
||||
7. **Settings in `ckb.yaml`** through `default_config` (D-0020): `style`,
|
||||
`format`, `out_dir`, `toc`, `number_sections`, `keep_links`.
|
||||
8. **Hook through the `AGENTS.md` block**, as D-0020 did: any request for an
|
||||
Office/PDF file goes through `ckb-convert`, after `ckb-voice` when that is
|
||||
installed. `ckb-document` is unchanged.
|
||||
9. **pandoc is a non-blocking dependency** of the install. The module is
|
||||
committed and shared, and a teammate without pandoc gets install
|
||||
instructions at first use rather than a blocked install for everyone.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
- **python-docx or the general docx skill** to build documents directly.
|
||||
These need a third-party package or produce a different look per run, and
|
||||
they can't read the Markdown the KB already has. pandoc is the standard
|
||||
tool for exactly this conversion.
|
||||
- **Ship a binary `house.docx` in the module.** A binary in the template
|
||||
repo, and a single fixed look. Generating it from pandoc's default plus
|
||||
settings keeps the repo text-only and the look adjustable.
|
||||
- **pandoc's LaTeX route for PDF.** It needs a TeX install and a second style
|
||||
definition that drifts from the Word one. LibreOffice reuses the `.docx`.
|
||||
- **Edit `ckb-document` to convert.** That would cover one producer only.
|
||||
Answers, reports and wiki pages need conversion too.
|
||||
|
||||
## Consequences
|
||||
|
||||
- No new page types or fields; no schema change.
|
||||
- Fonts aren't embedded in `.docx`; a rare font shows as a substitute. The
|
||||
README and skill say so.
|
||||
- The XML patching covers the settings listed and nothing else. A company
|
||||
template with unusual structure gets `check-style` and a pointer to Word.
|
||||
- Tests: `tests/unit/test_convert.py` (clean-up always; style patching and
|
||||
conversion when pandoc is present) and an install eval,
|
||||
`ckb-module/install-convert`, not yet run.
|
||||
|
|
@ -1,76 +0,0 @@
|
|||
---
|
||||
type: decision
|
||||
tldr: All template work lands on a `dev` integration branch; VERSION and the changelog change only when dev is merged into experimental, test or main (dev→experimental→test→main, dev→test→main, or dev→main), a version keeps its number when promoted, main is merged back into dev/test/experimental after a release, and 1.x keeps its own fixes; dev is not a channel.
|
||||
status: accepted
|
||||
decided_on: 2026-11-12
|
||||
decided_by: Michał Kopeć
|
||||
affects: AGENTS.md, README.md, README.pl.md, docs/MANUAL.md, docs/MANUAL.pl.md, docs/CHANGELOG.md, docs/CHANGELOG.pl.md, .agents/skills/ckb-upgrade/, .agents/skills/ckb-init/SKILL.md, VERSION
|
||||
confidence: 0.85
|
||||
quality: 0.8
|
||||
last_updated: 2026-11-12
|
||||
freshness_window_days: 365
|
||||
retention: high
|
||||
---
|
||||
|
||||
# D-0022 — Work lands on `dev`; the version changes only when `dev` is merged
|
||||
|
||||
**Status:** Accepted · **Decided:** 2026-11-12 · **Deciders:** Michał Kopeć
|
||||
|
||||
## Context
|
||||
|
||||
Until 2.2.0 every change was committed straight to `main` with its own
|
||||
version bump, and `test` and `experimental` were never updated after they were
|
||||
created: on 2026-11-12 both still pointed at the 1.9.0 commit, 27 commits
|
||||
behind `main`. A KB switched to either channel would have received *older*
|
||||
tooling than the stable one. Work in progress also had nowhere to live
|
||||
without being released.
|
||||
|
||||
## Decision
|
||||
|
||||
1. **`dev` is the integration branch.** Every change to the template lands
|
||||
there first. A commit on `dev` never changes `VERSION` or adds a
|
||||
changelog row.
|
||||
2. **A version is made by merging `dev`.** Merging `dev` into `experimental`,
|
||||
`test` or `main` bumps `VERSION` and adds the changelog row in the merge
|
||||
commit. The number follows the existing rule: major for breaking changes
|
||||
or significant architecture changes, minor for new features, patch for
|
||||
fixes and documentation; the highest kind in the merge wins.
|
||||
3. **Paths.** `dev` → `experimental` → `test` → `main`, `dev` → `test` →
|
||||
`main`, or `dev` → `main`. A version keeps its number while it is
|
||||
promoted; promotion never bumps it again.
|
||||
4. **After a release, `main` is merged back** into `dev`, `test` and
|
||||
`experimental`, so `dev` starts from the released version and no channel
|
||||
is ever behind the stable one.
|
||||
5. **`1.x` stays as it is**: the maintenance line for 1.x, with fixes
|
||||
committed and numbered on it directly.
|
||||
6. **`dev` is not a channel.** `ckb-upgrade` compares `VERSION`, which `dev`
|
||||
never moves, so a KB on `dev` would never see an upgrade. Asked for `dev`,
|
||||
`ckb-init` and `ckb-upgrade` offer `experimental`.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Merging `dev` takes everything on it. A direct `dev` → `main` merge is
|
||||
right only when all of `dev` is ready to ship; otherwise go through
|
||||
`experimental` or `test`.
|
||||
- Versions can be cut on `experimental` or `test` before `main` sees them,
|
||||
so a KB on those channels can be *ahead* of `main`; `ckb-upgrade` already
|
||||
reports that as ahead, not current.
|
||||
- Two changes merged from `dev` at different times can't share a number,
|
||||
because the second merge always starts from the first's `VERSION`.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
- **Bump on every commit (the old practice).** Rejected: it leaves no place
|
||||
for unfinished work and no reason to keep the pre-release channels moving.
|
||||
- **Make `dev` a channel too.** Rejected: without version changes on it, an
|
||||
upgrade could never tell a KB on `dev` that anything had changed.
|
||||
|
||||
## Evidence
|
||||
|
||||
> change the branch structure ... keep 1.X.X branch for fixing, create a
|
||||
> experimental, dev and test branches, version is changed only when dev is
|
||||
> merged to any other branch. The typical merging path will be
|
||||
> dev->experimental->test->main or dev->test->main or dev->main major,
|
||||
> minor, and breaking changes versioning stays as it is
|
||||
|
||||
— Chat conversation, Michał Kopeć, 2026-11-12
|
||||
|
|
@ -1,125 +0,0 @@
|
|||
---
|
||||
type: decision
|
||||
tldr: Schema 1.8 keeps the KB's own improvement history the way Google's Self-Improvement Memory does: error-book entries per recurring problem with every attempt, its expected and observed result and its context; decisions with an expected_outcome checked at review and a ## Tried section; lessons with a Context line, upstream lessons from linked KBs, lessons carried into a new KB, and merges that keep aliases. A self-improvement loop over the template is deferred until evals exist; loading the whole record into context unretrieved is rejected.
|
||||
status: accepted
|
||||
decided_on: 2026-11-18
|
||||
decided_by: Michał Kopeć
|
||||
affects: AGENTS.md, wiki/index.md, wiki/error-book.md, wiki/decisions/index.md, .agents/skills/ckb-lint/, .agents/skills/ckb-decide/, .agents/skills/ckb-profile/, .agents/skills/ckb-init/, .agents/skills/ckb-upgrade/
|
||||
review_on: 2027-02-18
|
||||
expected_outcome: By the review, at least one error-book problem in a real KB has two or more attempts with a filled-in Observed column, and at least one decision with an expected_outcome has had its outcome recorded; if neither has happened, the format is too heavy and should be cut back.
|
||||
confidence: 0.7
|
||||
quality: 0.8
|
||||
last_updated: 2026-11-18
|
||||
freshness_window_days: 365
|
||||
retention: high
|
||||
---
|
||||
|
||||
# D-0023 — Improvement memory: attempts, expected outcomes, lesson context
|
||||
|
||||
**Status:** Accepted · **Decided:** 2026-11-18 · **Deciders:** Michał Kopeć
|
||||
|
||||
## Context
|
||||
|
||||
Yu et al., *Self-Improvement Memory Enables Continual Recursive
|
||||
Self-Improvement* (Google, arXiv 2611.18856, 2026-11-13), studies agents
|
||||
that improve their own harness. When the model or the task changes, the
|
||||
improved harness alone does not say why each change was made or whether it
|
||||
worked. Their Self-Improvement Memory (SIM) keeps, per recurring problem,
|
||||
every attempt with its rationale, the tasks it was **predicted** to fix
|
||||
(written before evaluation), what it actually fixed, and the setting it ran
|
||||
in. Continuing with SIM beat continuing with the harness alone in all ten
|
||||
of their settings (+2.36 points on average across ten paired coding runs,
|
||||
p = 0.003). The record helped most by keeping the *reason* for an inherited
|
||||
change, so the next optimizer adapted it instead of reverting it, and by
|
||||
keeping failed attempts so they were not retried blind.
|
||||
|
||||
A Cascade KB already improves itself in small ways: lint records systemic
|
||||
issues in the error book, people record lessons, decisions record why. At
|
||||
2.2.0 none of these held SIM's three working parts. The error book was one
|
||||
row per incident. Nothing wrote down an expected result before the result
|
||||
was known. Lessons did not say which model or template they were learned
|
||||
under.
|
||||
|
||||
## Decision
|
||||
|
||||
Schema 1.8. Every addition is optional and additive.
|
||||
|
||||
1. **Error book by problem.** `wiki/error-book.md` holds one entry per
|
||||
recurring problem (`## E<n> — <root-cause hypothesis>`, status
|
||||
`open`/`watching`/`resolved`, a `Constraint:` once known), each with a
|
||||
table of attempts: date, what changed, **Expected** (written first),
|
||||
**Observed** (`pending`, then `held`/`recurred`/`partly` with a date),
|
||||
**Context**. Lint check 9 appends to an existing problem before opening a
|
||||
new one, fills in pending observations on each run, and never rewrites an
|
||||
attempt. Old single-table error books are kept as `## Earlier entries`.
|
||||
2. **Expected outcomes on decisions.** `expected_outcome` (one line, written
|
||||
when the decision is recorded; one added later is marked `(added
|
||||
YYYY-MM-DD)`), and at review `outcome` (`met`/`partly`/`missed`/`unclear`),
|
||||
`outcome_checked` and a dated entry appended to `## Outcome`. Lint
|
||||
validates the vocabulary and treats a review as done once
|
||||
`outcome_checked` is on or after `review_on`.
|
||||
3. **Context on lessons and attempts.** A lesson carries `- **Context:**
|
||||
<agent/model>, template <VERSION>[, setting]`. A lesson from a different
|
||||
context is a strong hint to recheck, not a rule; a lesson without one is
|
||||
context unknown.
|
||||
4. **What was tried.** Decision records gain an optional `## Tried` section,
|
||||
for what was built or tested and dropped, kept apart from *Alternatives
|
||||
considered* (weighed, not tried). Template ADRs use it too. Picking a
|
||||
direction that is listed as tried, or reversing a rejected decision,
|
||||
makes `ckb-decide` ask what is new since then.
|
||||
5. **Experience across KBs.** The session brief lists new lessons from each
|
||||
`linked/<name>/wiki/lessons.md` as `upstream`, ranked below local ones
|
||||
and read-only. "Adopt that lesson" copies one in with a `Carried from:`
|
||||
line. `ckb-init`, run inside a populated KB, offers once to carry chosen
|
||||
lessons and error-book problems into the new KB; carried problems become
|
||||
`watching`, both files `review: needs_update`. Profiles are never carried.
|
||||
6. **Merges keep aliases.** A merged error-book entry stays as
|
||||
`## E4 → E2 — merged YYYY-MM-DD`, and its attempts move across marked
|
||||
`(from E4)`. A merged lesson is struck through with `merged into "<rule>"`
|
||||
and the survivor gets `Also recorded:`. Struck-through lessons are no
|
||||
longer listed in the brief.
|
||||
|
||||
## Tried
|
||||
|
||||
Nothing was piloted before this decision. The paper's results come from
|
||||
harness optimisation on benchmarks, not from knowledge bases, so how well
|
||||
this transfers is the open question. See `review_on` and `expected_outcome`
|
||||
above.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
- **A self-improvement loop for the template** — the paper's own setting:
|
||||
propose edits to skills, score them on an eval set, check a held-out
|
||||
split and earlier passing cases, keep the winners, all with SIM recording
|
||||
the attempts. **Deferred, to consider later.** It needs a behavioural eval
|
||||
set first (the routing and retrieval evals already listed as gaps). Once
|
||||
one exists, use the paper's two lessons: hold out part of the eval set,
|
||||
and check whether previously passing cases still pass after a change.
|
||||
- **Load the whole record into context, unretrieved** — SIM gives the
|
||||
optimizer the full memory every round with no retrieval or truncation.
|
||||
**Rejected.** It works for one optimizer's notes, which stay small. A
|
||||
KB's error book, lessons and decisions grow without bound and compete
|
||||
with the context budget lint enforces (check 19). The brief already lists
|
||||
new lessons; the rest is read index-first when a task bears on it.
|
||||
- **Machine-readable JSON for the error book**, as SIM stores it.
|
||||
Rejected: every other KB record is Markdown that people edit and review,
|
||||
and nothing needs to parse attempts automatically yet.
|
||||
- **Backfilling expected outcomes and lesson context on upgrade.** Rejected:
|
||||
a prediction written after the result is hindsight, and a guessed context
|
||||
is worse than an honest "unknown".
|
||||
|
||||
## Consequences
|
||||
|
||||
- Recording a decision asks one more question (what it should change), and
|
||||
lint asks for an outcome when a review comes due. That is more friction;
|
||||
the review date above checks whether it is used.
|
||||
- The error book becomes longer and more useful only if lint really goes
|
||||
back to pending attempts. The skill says so; nothing in a script enforces
|
||||
it.
|
||||
- A KB that links others sees their lessons in its brief, which may be
|
||||
noise if the KBs differ a lot. Upstream lessons rank last and are only
|
||||
listed, never applied unasked.
|
||||
|
||||
## Sources
|
||||
|
||||
- `https://arxiv.org/abs/2611.18856` — Yu et al., 2026-11-13, read 2026-11-18 (§3.2, §3.3, App. D.2–D.3, F.6)
|
||||
|
|
@ -10,10 +10,6 @@ but they live here, in the template layer, because:
|
|||
pages the content layer is allowed to delete.
|
||||
|
||||
`ckb-upgrade` carries this folder along with the rest of the template layer.
|
||||
|
||||
Since D-0023 these records may carry `expected_outcome`, `## Tried` and an
|
||||
appended `## Outcome`, like any decision: write what a change should do
|
||||
before it ships, and check it when `review_on` comes.
|
||||
`ckb-decide` never writes here — it is not a place for a KB's project decisions.
|
||||
|
||||
| # | Decision |
|
||||
|
|
@ -37,7 +33,3 @@ before it ships, and check it when `review_on` comes.
|
|||
| [D-0017](0017-capture-module-and-skill-evals.md) | Opt-in `capture` module (stdlib fetch, Wayback only over a failed/thinner page, agent tool fallback, untrusted marking, dedup at capture, `yt-dlp` with consent); structural skill evals with a prepare/check runner; multi-agent setup documented as untested |
|
||||
| [D-0018](0018-share-mailbox-module.md) | Opt-in `share` module: KBs exchange documents through a git channel with one append-only mailbox per KB; received mail lands in `raw/inbox/` (untrusted) and retractions in `raw/retractions/`; the git author must own the mailbox; handled messages are kept in a ledger in `ckb.yaml` |
|
||||
| [D-0019](0019-two-dot-zero-drops-powershell.md) | Template 2.0.0 drops PowerShell; every script the template and its modules ship is Python (bash fallback and the container entrypoint named as exceptions); 1.x continues on a `1.x` maintenance branch; `ckb-upgrade` never crosses a major version without asking |
|
||||
| [D-0020](0020-voice-module.md) | Opt-in `voice` module: outgoing prose (kept answers, documents, reports, the project overview) is rewritten in a voice whose profile is a wiki page in `wiki/voice/`; settings in `ckb.yaml`; routed by the `AGENTS.md` block, not per-skill edits; frozen spans never change, vague claims are flagged rather than cut; `writer:` plugs in an external rewriting skill |
|
||||
| [D-0021](0021-convert-module.md) | Opt-in `convert` module: Markdown becomes Word/ODT/PDF/HTML through pandoc in a named house style, a reference `.docx` in `templates/styles/` built from a few settings or copied from a company `.docx`/`.dotx`; PDF and ODT go through LibreOffice from the styled `.docx`; KB links and frontmatter are cleaned in the copy; the Markdown stays the source |
|
||||
| [D-0022](0022-dev-branch-and-merge-versioning.md) | All work lands on `dev`; `VERSION` changes only when `dev` is merged into `experimental`, `test` or `main`, a version keeps its number when promoted, `main` is merged back after a release, `1.x` keeps its own fixes, and `dev` is not a channel |
|
||||
| [D-0023](0023-improvement-memory.md) | Schema 1.8: error book per recurring problem with every attempt, its expected and observed result and context; decisions with `expected_outcome` checked at review and a `## Tried` section; lessons with context, upstream lessons from `linked/`, lessons carried by `ckb-init`, merges with aliases; a self-improvement loop deferred until evals exist; loading the whole record unretrieved rejected |
|
||||
|
|
|
|||
|
|
@ -36,8 +36,6 @@ run fails there.
|
|||
| `ckb-decide/record` | 2026-11-02 | yes |
|
||||
| `ckb-reset/no-confirm`, `ckb-reset/confirmed` | 2026-11-11 | confirmed only |
|
||||
| `ckb-module/install`, `ckb-module/round-trip` | 2026-11-11 | install only |
|
||||
| `ckb-module/install-voice` | not run yet | no |
|
||||
| `ckb-module/install-convert` | not run yet | no |
|
||||
| `ckb-upgrade/major-guard`, `ckb-upgrade/take-major` | 2026-11-11 | no (a reference would copy the template's docs) |
|
||||
| `ckb-decide/supersede` | 2026-11-11 | yes |
|
||||
| `ckb-ingest/check-in-waits`, `ckb-ingest/reviewed-page` | 2026-11-11 | reviewed-page only |
|
||||
|
|
|
|||
|
|
@ -1,53 +0,0 @@
|
|||
{
|
||||
"skill": "ckb-module",
|
||||
"fixture": "minimal-kb",
|
||||
"setup": [
|
||||
{
|
||||
"template": [
|
||||
".agents/skills",
|
||||
".agents/modules",
|
||||
"AGENTS.md",
|
||||
".gitignore"
|
||||
]
|
||||
}
|
||||
],
|
||||
"prompt": "Install the convert module. You don't need to ask me first.",
|
||||
"assert": [
|
||||
{
|
||||
"file_exists": ".agents/skills/ckb-convert/SKILL.md"
|
||||
},
|
||||
{
|
||||
"file_exists": ".agents/skills/ckb-convert/scripts/convert.py"
|
||||
},
|
||||
{
|
||||
"file_exists": "templates/styles/README.md"
|
||||
},
|
||||
{
|
||||
"file_contains": {
|
||||
"path": "AGENTS.md",
|
||||
"regex": "(?i)MODULE: convert"
|
||||
}
|
||||
},
|
||||
{
|
||||
"file_contains": {
|
||||
"path": "ckb.yaml",
|
||||
"regex": "name: convert"
|
||||
}
|
||||
},
|
||||
{
|
||||
"file_contains": {
|
||||
"path": "ckb.yaml",
|
||||
"regex": "style: house"
|
||||
}
|
||||
},
|
||||
{
|
||||
"file_absent": "templates/styles/*.docx"
|
||||
},
|
||||
{
|
||||
"unchanged": ".agents/modules/**/*"
|
||||
},
|
||||
{
|
||||
"unchanged": "wiki/**/*"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
@ -1,56 +0,0 @@
|
|||
{
|
||||
"skill": "ckb-module",
|
||||
"fixture": "minimal-kb",
|
||||
"setup": [
|
||||
{
|
||||
"template": [
|
||||
".agents/skills",
|
||||
".agents/modules",
|
||||
"AGENTS.md",
|
||||
".gitignore"
|
||||
]
|
||||
}
|
||||
],
|
||||
"prompt": "Install the voice module. You don't need to ask me first.",
|
||||
"assert": [
|
||||
{
|
||||
"file_exists": ".agents/skills/ckb-voice/SKILL.md"
|
||||
},
|
||||
{
|
||||
"file_exists": ".agents/skills/ckb-voice/references/rules.md"
|
||||
},
|
||||
{
|
||||
"file_contains": {
|
||||
"path": "AGENTS.md",
|
||||
"regex": "(?i)MODULE: voice"
|
||||
}
|
||||
},
|
||||
{
|
||||
"file_contains": {
|
||||
"path": "ckb.yaml",
|
||||
"regex": "name: voice"
|
||||
}
|
||||
},
|
||||
{
|
||||
"file_contains": {
|
||||
"path": "ckb.yaml",
|
||||
"regex": "mode: auto"
|
||||
}
|
||||
},
|
||||
{
|
||||
"file_contains": {
|
||||
"path": "ckb.yaml",
|
||||
"regex": "profile: house"
|
||||
}
|
||||
},
|
||||
{
|
||||
"file_absent": "wiki/voice/**"
|
||||
},
|
||||
{
|
||||
"unchanged": ".agents/modules/**/*"
|
||||
},
|
||||
{
|
||||
"unchanged": "wiki/**/*"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
@ -1,146 +0,0 @@
|
|||
"""convert module: the Markdown clean-up is pure and always tested; the style
|
||||
patching and real conversions run only where pandoc is installed."""
|
||||
import contextlib
|
||||
import importlib.util
|
||||
import io
|
||||
import re
|
||||
import shutil
|
||||
import tempfile
|
||||
import unittest
|
||||
import xml.dom.minidom
|
||||
import zipfile
|
||||
from pathlib import Path
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[2]
|
||||
SPEC = importlib.util.spec_from_file_location(
|
||||
"convert", str(ROOT / ".agents/modules/convert/skills/ckb-convert/scripts/convert.py"))
|
||||
convert = importlib.util.module_from_spec(SPEC)
|
||||
SPEC.loader.exec_module(convert)
|
||||
|
||||
DOC = """---
|
||||
type: document
|
||||
created: 2026-11-11
|
||||
author: Ada Lovelace <ada@example.com>
|
||||
---
|
||||
|
||||
# Status: Atlas
|
||||
|
||||
<!-- Ask the user. -->
|
||||
See [[Atlas Retry Policy]] ([atlas](/wiki/entities/atlas.md)), [Maria](/wiki/entities/maria.md),
|
||||
[[x/y/page|the page]], [web](https://example.com) and .
|
||||
|
||||
```md
|
||||
[[keep]] <!-- keep --> [k](/wiki/k.md)
|
||||
```
|
||||
"""
|
||||
|
||||
|
||||
class Prepare(unittest.TestCase):
|
||||
def test_metadata_from_frontmatter_and_heading(self):
|
||||
meta, body = convert.prepare(DOC, keep_links=False)
|
||||
self.assertEqual(meta, {"title": "Status: Atlas", "author": "Ada Lovelace", "date": "2026-11-11"})
|
||||
self.assertNotIn("# Status", body)
|
||||
self.assertNotIn("type: document", body)
|
||||
|
||||
def test_kb_links_become_text_web_links_and_images_stay(self):
|
||||
_, body = convert.prepare(DOC, keep_links=False)
|
||||
self.assertIn("See Atlas Retry Policy, Maria,", body)
|
||||
self.assertIn("the page,", body)
|
||||
self.assertIn("[web](https://example.com)", body)
|
||||
self.assertIn("", body)
|
||||
self.assertNotIn("Ask the user", body)
|
||||
|
||||
def test_code_blocks_untouched(self):
|
||||
_, body = convert.prepare(DOC, keep_links=False)
|
||||
self.assertIn("[[keep]] <!-- keep --> [k](/wiki/k.md)", body)
|
||||
|
||||
def test_keep_links(self):
|
||||
_, body = convert.prepare(DOC, keep_links=True)
|
||||
self.assertIn("[Atlas Retry Policy](/wiki/entities/atlas.md)", body)
|
||||
self.assertIn("[Maria](/wiki/entities/maria.md)", body)
|
||||
|
||||
def test_frontmatter_title_wins_and_heading_stays(self):
|
||||
meta, body = convert.prepare("---\ntitle: Report\n---\n\n# Intro\n\nText\n", False)
|
||||
self.assertEqual(meta["title"], "Report")
|
||||
self.assertIn("# Intro", body)
|
||||
|
||||
def test_heading_after_text_is_not_the_title(self):
|
||||
meta, body = convert.prepare("Some text.\n\n# Later\n", False)
|
||||
self.assertNotIn("title", meta)
|
||||
self.assertIn("# Later", body)
|
||||
|
||||
|
||||
class SchemaOrder(unittest.TestCase):
|
||||
def test_insert_respects_order(self):
|
||||
inner = '<w:rFonts w:ascii="A"/><w:sz w:val="24"/><w:lang w:val="en"/>'
|
||||
out = convert.set_child(inner, "color", '<w:color w:val="112233"/>', convert.RPR_ORDER)
|
||||
self.assertLess(out.index("w:color"), out.index("w:sz"))
|
||||
self.assertGreater(out.index("w:color"), out.index("w:rFonts"))
|
||||
out = convert.set_child(out, "sz", '<w:sz w:val="22"/>', convert.RPR_ORDER)
|
||||
self.assertEqual(out.count("<w:sz "), 1)
|
||||
self.assertLess(out.index("w:sz"), out.index("w:lang"))
|
||||
|
||||
|
||||
@unittest.skipUnless(shutil.which("pandoc"), "pandoc not installed")
|
||||
class WithPandoc(unittest.TestCase):
|
||||
def setUp(self):
|
||||
self.tmp = tempfile.TemporaryDirectory()
|
||||
self.root = Path(self.tmp.name)
|
||||
(self.root / "outputs/documents").mkdir(parents=True)
|
||||
(self.root / "outputs/documents/r.md").write_text(DOC, encoding="utf-8")
|
||||
|
||||
def tearDown(self):
|
||||
self.tmp.cleanup()
|
||||
|
||||
def cli(self, *a):
|
||||
with contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(io.StringIO()):
|
||||
return convert.main(["--root", str(self.root)] + list(a))
|
||||
|
||||
def test_style_settings_land_in_valid_xml(self):
|
||||
self.assertEqual(self.cli("new-style", "house", "--body-font", "Georgia", "--size", "11",
|
||||
"--heading-color", "#1f3864", "--paper", "a4", "--margin-cm", "2"), 0)
|
||||
z = zipfile.ZipFile(self.root / "templates/styles/house.docx")
|
||||
for n in z.namelist():
|
||||
if n.endswith(".xml"):
|
||||
xml.dom.minidom.parseString(z.read(n))
|
||||
styles = z.read("word/styles.xml").decode()
|
||||
doc = z.read("word/document.xml").decode()
|
||||
default = re.search(r"<w:rPrDefault>.*?</w:rPrDefault>", styles, re.S).group(0)
|
||||
self.assertIn('w:ascii="Georgia"', default)
|
||||
self.assertIn('<w:sz w:val="22"/>', default)
|
||||
h1 = re.search(r'<w:style [^>]*w:styleId="Heading1".*?</w:style>', styles, re.S).group(0)
|
||||
self.assertIn('<w:color w:val="1F3864"/>', h1)
|
||||
self.assertEqual(h1.count("<w:color "), 1)
|
||||
self.assertIn('<w:pgSz w:w="11906" w:h="16838"/>', doc)
|
||||
self.assertIn('w:top="1134"', doc)
|
||||
|
||||
def test_convert_docx_and_refuse_overwrite(self):
|
||||
self.cli("new-style", "house")
|
||||
self.assertEqual(self.cli("convert", str(self.root / "outputs/documents/r.md")), 0)
|
||||
out = self.root / "outputs/documents/r.docx"
|
||||
self.assertTrue(out.exists())
|
||||
doc = zipfile.ZipFile(out).read("word/document.xml").decode()
|
||||
self.assertIn("Status: Atlas", doc)
|
||||
self.assertNotIn("Ask the user", doc)
|
||||
self.assertEqual(self.cli("convert", str(self.root / "outputs/documents/r.md")), 1)
|
||||
self.assertEqual(self.cli("convert", str(self.root / "outputs/documents/r.md"), "--force"), 0)
|
||||
|
||||
def test_dotx_becomes_docx(self):
|
||||
self.cli("new-style", "house")
|
||||
dotx = self.root / "Company.dotx"
|
||||
shutil.copyfile(self.root / "templates/styles/house.docx", dotx)
|
||||
convert.rewrite_zip(dotx, {"[Content_Types].xml": lambda x: x.replace(convert.DOCX_CT, convert.DOTX_CT)})
|
||||
self.assertEqual(self.cli("new-style", "company", "--from", str(dotx)), 0)
|
||||
ct = zipfile.ZipFile(self.root / "templates/styles/company.docx").read("[Content_Types].xml").decode()
|
||||
self.assertIn(convert.DOCX_CT, ct)
|
||||
self.assertNotIn(convert.DOTX_CT, ct)
|
||||
|
||||
def test_refusals(self):
|
||||
self.assertEqual(self.cli("new-style", "Bad Name"), 1)
|
||||
self.assertEqual(self.cli("edit-style", "nope", "--size", "10"), 1)
|
||||
self.assertEqual(self.cli("convert", str(self.root / "outputs/documents/r.md"),
|
||||
"--style", "nope", "--style-required"), 1)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
|
|
@ -1,109 +0,0 @@
|
|||
"""Schema 1.8 (D-0023): decisions carry an expected outcome checked at review,
|
||||
and the session brief lists upstream lessons from linked KBs and skips
|
||||
struck-through ones."""
|
||||
import json
|
||||
import shutil
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
from datetime import date
|
||||
from pathlib import Path
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[2]
|
||||
FIX = ROOT / "tests/fixtures/minimal-kb"
|
||||
SCRIPTS = ROOT / ".agents/skills/ckb-lint/scripts"
|
||||
LINT = SCRIPTS / "lint_report.py"
|
||||
TODAY = "2026-11-18"
|
||||
sys.path.insert(0, str(SCRIPTS))
|
||||
import session_start # noqa: E402
|
||||
|
||||
DECISION = ("---\ntype: decision\ntldr: {n}\nstatus: accepted\ndecided_on: 2026-09-01\n"
|
||||
"decided_by: A\n{extra}---\n\n# D-{n}\n")
|
||||
|
||||
|
||||
class DecisionOutcomes(unittest.TestCase):
|
||||
@classmethod
|
||||
def setUpClass(cls):
|
||||
cls.tmp = tempfile.TemporaryDirectory()
|
||||
kb = Path(cls.tmp.name) / "kb"
|
||||
shutil.copytree(str(FIX), str(kb))
|
||||
d = kb / "wiki" / "decisions"
|
||||
d.mkdir(exist_ok=True)
|
||||
pages = {
|
||||
"0091-expects.md": "review_on: 2026-11-01\nexpected_outcome: Fewer orphans.\n",
|
||||
"0092-checked.md": "review_on: 2026-11-01\nexpected_outcome: Fewer orphans.\n"
|
||||
"outcome: partly\noutcome_checked: 2026-11-10\n",
|
||||
"0093-plain-due.md": "review_on: 2026-11-01\n",
|
||||
"0094-bad-outcome.md": "outcome: great\noutcome_checked: 2026-11-10\n",
|
||||
"0095-no-outcome.md": "outcome_checked: 2026-11-10\n",
|
||||
"0096-old-check.md": "review_on: 2026-11-15\nexpected_outcome: X.\n"
|
||||
"outcome: met\noutcome_checked: 2026-11-10\n",
|
||||
}
|
||||
for name, extra in pages.items():
|
||||
(d / name).write_text(DECISION.format(n=name[:4], extra=extra), encoding="utf-8")
|
||||
idx = d / "index.md"
|
||||
old = idx.read_text(encoding="utf-8") if idx.is_file() else "# Decisions\n"
|
||||
idx.write_text(old + "".join(f"\n- [{n}]({n})" for n in pages) + "\n", encoding="utf-8")
|
||||
r = subprocess.run([sys.executable, str(LINT), "--json", "--today", TODAY], cwd=str(kb),
|
||||
capture_output=True, text=True, encoding="utf-8")
|
||||
cls.findings = json.loads(r.stdout)["trees"][0]["decisions"]
|
||||
|
||||
@classmethod
|
||||
def tearDownClass(cls):
|
||||
cls.tmp.cleanup()
|
||||
|
||||
def about(self, name):
|
||||
return [f for f in self.findings if name in f]
|
||||
|
||||
def test_due_review_with_expectation_asks_for_outcome(self):
|
||||
(f,) = self.about("0091")
|
||||
self.assertIn("due for review", f)
|
||||
self.assertIn("record `outcome`", f)
|
||||
|
||||
def test_outcome_checked_after_review_on_closes_it(self):
|
||||
self.assertEqual(self.about("0092"), [])
|
||||
|
||||
def test_plain_due_review_unchanged(self):
|
||||
(f,) = self.about("0093")
|
||||
self.assertIn("due for review", f)
|
||||
self.assertNotIn("expected_outcome", f)
|
||||
|
||||
def test_outcome_vocabulary(self):
|
||||
self.assertTrue(any("`outcome: great`" in f for f in self.about("0094")))
|
||||
|
||||
def test_checked_without_outcome(self):
|
||||
self.assertTrue(any("no `outcome`" in f for f in self.about("0095")))
|
||||
|
||||
def test_check_before_review_on_does_not_close_it(self):
|
||||
self.assertTrue(any("due for review" in f for f in self.about("0096")))
|
||||
|
||||
|
||||
LESSONS = ("---\ntype: lessons\ntldr: Lessons.\n---\n\n# Lessons\n\n"
|
||||
"### 2026-11-01 — {a}\n- **Scope:** KB\n\n"
|
||||
"### 2026-11-02 — ~~{b}~~ — dropped 2026-11-05: no longer true\n- **Scope:** KB\n")
|
||||
|
||||
|
||||
class UpstreamLessons(unittest.TestCase):
|
||||
def test_local_and_upstream_listed_struck_skipped(self):
|
||||
with tempfile.TemporaryDirectory() as t:
|
||||
root = Path(t)
|
||||
(root / "wiki").mkdir()
|
||||
(root / "wiki/lessons.md").write_text(LESSONS.format(a="Local rule", b="Dead local"), encoding="utf-8")
|
||||
up = root / "linked" / "parent" / "wiki"
|
||||
up.mkdir(parents=True)
|
||||
(up / "lessons.md").write_text(LESSONS.format(a="Parent rule", b="Dead parent"), encoding="utf-8")
|
||||
out = "\n".join(session_start.lessons_lines(root, None, date(2026, 11, 18)))
|
||||
self.assertIn("lessons: 1 in wiki/lessons.md", out)
|
||||
self.assertIn("Local rule", out)
|
||||
self.assertIn("upstream lessons: 1 in linked/parent/wiki/lessons.md", out)
|
||||
self.assertIn("Parent rule", out)
|
||||
self.assertNotIn("Dead", out)
|
||||
|
||||
def test_nothing_without_lessons(self):
|
||||
with tempfile.TemporaryDirectory() as t:
|
||||
self.assertEqual(session_start.lessons_lines(Path(t), None, date(2026, 11, 18)), [])
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
|
|
@ -1,42 +0,0 @@
|
|||
# Profile skills
|
||||
|
||||
Skills a person installs **once in their own agent profile**, not inside a
|
||||
knowledge base. They work from any folder, before any KB exists on the
|
||||
machine. `ckb-init` and `ckb-upgrade` never copy this folder into a KB.
|
||||
|
||||
| Skill | What it does | Say |
|
||||
|---|---|---|
|
||||
| `ckb-create` | Creates a new KB in a folder and publishes it to an empty git remote, ready for colleagues | "Create a new wiki in `~/kb/team` with origin `<url>`" |
|
||||
| `ckb-join` | Clones an existing KB from its origin URL, checks it works on this machine | "Join the knowledge base at `<url>`" (optionally "into `<folder>`") |
|
||||
|
||||
`ckb-create` holds no scaffold logic of its own: it fetches the template at
|
||||
run time and follows that version's `ckb-init`. An old copy in a profile
|
||||
therefore still builds a current KB.
|
||||
|
||||
## Install
|
||||
|
||||
Claude Code (macOS / Linux):
|
||||
|
||||
```bash
|
||||
git clone --depth 1 https://git.wierzbowa.cloud/michal/ckb.git /tmp/ckb
|
||||
mkdir -p ~/.claude/skills
|
||||
cp -R /tmp/ckb/user-skills/ckb-create /tmp/ckb/user-skills/ckb-join ~/.claude/skills/
|
||||
rm -rf /tmp/ckb
|
||||
```
|
||||
|
||||
Windows (PowerShell):
|
||||
|
||||
```powershell
|
||||
git clone --depth 1 https://git.wierzbowa.cloud/michal/ckb.git $env:TEMP\ckb
|
||||
New-Item -ItemType Directory -Force $HOME\.claude\skills | Out-Null
|
||||
Copy-Item -Recurse $env:TEMP\ckb\user-skills\ckb-create, $env:TEMP\ckb\user-skills\ckb-join $HOME\.claude\skills\
|
||||
Remove-Item -Recurse -Force $env:TEMP\ckb
|
||||
```
|
||||
|
||||
Other agents: copy the two folders into that agent's user-level skills
|
||||
directory, or point it at the `SKILL.md` files.
|
||||
|
||||
To update, repeat the copy. To remove, delete the two folders.
|
||||
|
||||
If your profile also has an old `ckb-init` copy, you can remove it:
|
||||
`ckb-init` belongs inside a KB, and `ckb-create` covers the from-anywhere case.
|
||||
|
|
@ -1,181 +0,0 @@
|
|||
---
|
||||
name: ckb-create
|
||||
description: Create a brand-new shared Cascade Knowledge Base in a folder and publish it to an empty git remote, so colleagues can join it straight away — fetches the current template, scaffolds the KB with that template's own ckb-init, commits on `main`, adds the given URL as `origin` and pushes. Installed in a user's profile, so it works from any folder. Use for "create a new wiki in this folder with this origin", "start a shared knowledge base", "new KB for the team", "set up a wiki and push it to our git server". Not for a local-only scaffold with no remote (that is ckb-init inside a KB) or for joining a KB that already exists on the remote (that is ckb-join).
|
||||
---
|
||||
|
||||
# Create a shared Cascade KB
|
||||
|
||||
## Purpose
|
||||
|
||||
One action from "I have an empty remote repo" to "the team can clone a
|
||||
working KB". This skill lives in a person's profile (`~/.claude/skills/`),
|
||||
not in any KB, so it never gets upgraded with the template. It therefore
|
||||
holds **no scaffold knowledge of its own**: it fetches the template and
|
||||
follows the `ckb-init` that ships with it, then does the publishing that
|
||||
`ckb-init` deliberately leaves out.
|
||||
|
||||
Never pushes to a remote that already has commits, never force-pushes,
|
||||
never creates the remote repository itself (that is the git host's job and
|
||||
the user's permissions).
|
||||
|
||||
## How to run this skill
|
||||
|
||||
### Step 1 — Collect the three inputs
|
||||
|
||||
- **Target folder** — where the new KB lives on this machine. Resolve to an
|
||||
absolute path and say it back before writing anything. A relative path is
|
||||
relative to the current working directory, not to any KB.
|
||||
- **Origin URL** — the remote repository, already created on the host
|
||||
(GitHub, GitLab, Gitea, Azure DevOps…) and **empty**: no README, no
|
||||
licence, no `.gitignore`. If the user has not created it yet, tell them
|
||||
to, and to leave "initialise with README" unticked.
|
||||
- **Template channel** (optional) — `main` unless the user names `test`,
|
||||
`experimental`, or a fork/mirror URL. Same rules as `ckb-init`'s
|
||||
"Which branch" table.
|
||||
|
||||
Ask only for what is missing, in one message.
|
||||
|
||||
### Step 2 — Pre-flight
|
||||
|
||||
Run these and stop on the first failure, reporting git's own error:
|
||||
|
||||
```bash
|
||||
git --version
|
||||
git config user.name; git config user.email
|
||||
git ls-remote <origin-url>
|
||||
```
|
||||
|
||||
- **No git identity** — every log entry and commit in a Cascade KB carries
|
||||
the author, so a team KB needs one. Ask for name and email and set them
|
||||
with `git config --global` only on a yes; otherwise stop.
|
||||
- **`ls-remote` fails** — authentication or a wrong URL. Report the raw
|
||||
error, suggest checking the URL and that the user can push to it
|
||||
(SSH key, credential helper, personal access token). Don't guess a
|
||||
corrected URL.
|
||||
- **`ls-remote` prints any refs** — the remote is not empty. Stop: "That
|
||||
remote already has history. If it is an existing KB, say *join the
|
||||
knowledge base at `<url>`* instead; if it only has an auto-generated
|
||||
README, delete the repo and recreate it empty, or tell me to proceed and
|
||||
I'll stop before pushing." Never merge an unrelated history here.
|
||||
- **Target folder** — apply `ckb-init`'s Step 2 rules (an existing `wiki/`
|
||||
or `AGENTS.md` means stop and ask). Additionally, if the target is already
|
||||
inside a git work tree (`git -C <target> rev-parse --is-inside-work-tree`),
|
||||
stop: a shared KB needs its own repository, not a subfolder of another.
|
||||
|
||||
### Step 3 — Fetch the template
|
||||
|
||||
```bash
|
||||
rm -rf <scratch>
|
||||
git clone --depth 1 --branch <branch> <template-url> <scratch>
|
||||
git -C <scratch> rev-parse --short HEAD
|
||||
cat <scratch>/VERSION
|
||||
```
|
||||
|
||||
`<template-url>` defaults to `https://git.wierzbowa.cloud/michal/ckb.git`.
|
||||
`<scratch>` is a fresh temp directory outside the target (`mktemp -d`, or
|
||||
the session scratchpad). Note the URL, branch, short hash and `VERSION` for
|
||||
the report.
|
||||
|
||||
### Step 4 — Scaffold with the template's own `ckb-init`
|
||||
|
||||
Read `<scratch>/.agents/skills/ckb-init/SKILL.md` (and its
|
||||
`references/edge-cases.md` if a case comes up) and follow it with:
|
||||
|
||||
- **template source** = the scratch clone (its Step 3a, already done — do
|
||||
not clone again);
|
||||
- **target** = the folder from Step 1 (its Steps 1–2 are already done);
|
||||
- `ckb.yaml`'s `template:` block = the template URL and branch from Step 3.
|
||||
|
||||
Ask the questions `ckb-init` asks (the `ABOUT.md` purpose sentence, the
|
||||
`LICENSE` copyright line). Those answers matter more for a shared KB, since
|
||||
everyone will see them.
|
||||
|
||||
**Two overrides to `ckb-init`, because this KB is shared:**
|
||||
|
||||
- Its Step 11 is **not optional** and not "ask first": initialise the
|
||||
repository on `main` — the branch `ckb-sync-changes` assumes:
|
||||
```bash
|
||||
git -C <target> init -b main
|
||||
```
|
||||
(On git older than 2.28: `git init` then `git symbolic-ref HEAD refs/heads/main`.)
|
||||
- Its "don't add a remote and don't push" is replaced by Step 6 below.
|
||||
|
||||
If `ckb-init` in the fetched template differs from what this skill
|
||||
expects (renamed steps, a new step), the fetched `ckb-init` wins: it is
|
||||
the current contract, this skill is only the wrapper.
|
||||
|
||||
### Step 5 — First commit
|
||||
|
||||
```bash
|
||||
cd <target>
|
||||
test -L CLAUDE.md && test -L .claude/skills # both must be symlinks
|
||||
git add .
|
||||
git status --short | head -50 # show what goes in
|
||||
git commit -m "Initialize Cascade Knowledge Base from ckb template v<VERSION>"
|
||||
```
|
||||
|
||||
`git add .` is safe here and only here: the folder holds nothing but the
|
||||
fresh scaffold, and its `.gitignore` is already in place. If `git status`
|
||||
shows anything that is not scaffold (a stray `.env`, files that were in the
|
||||
folder before), stop and ask before committing it. If either symlink check
|
||||
fails, fix it before committing (`ln -s AGENTS.md CLAUDE.md`,
|
||||
`ln -s ../.agents/skills .claude/skills`) — a team member who clones a KB
|
||||
whose `CLAUDE.md` is a plain copy gets a stale system prompt.
|
||||
|
||||
### Step 6 — Publish
|
||||
|
||||
```bash
|
||||
git remote add origin <origin-url>
|
||||
git push -u origin main
|
||||
git ls-remote origin refs/heads/main # must equal: git rev-parse HEAD
|
||||
```
|
||||
|
||||
If the push is rejected, report the raw error and stop — the remote gained
|
||||
history after Step 2, or the user lacks push rights. Never `--force`.
|
||||
|
||||
### Step 7 — Clean up and report
|
||||
|
||||
```bash
|
||||
rm -rf <scratch>
|
||||
```
|
||||
|
||||
Tell the user, briefly:
|
||||
|
||||
- the folder, the origin URL, and that `main` is pushed and tracking
|
||||
`origin/main`;
|
||||
- the template source (URL, branch, short hash, `VERSION`); name the channel
|
||||
in words if it is not `main`;
|
||||
- what they answered for `ABOUT.md` and `LICENSE`;
|
||||
- **how colleagues join**, as a line they can forward:
|
||||
> Install the `ckb-join` skill, then say: *join the knowledge base at
|
||||
> `<origin-url>`*. Or by hand: `git clone <origin-url>` and open the
|
||||
> folder in your agent.
|
||||
- that they must grant those colleagues access on the git host — this
|
||||
skill cannot;
|
||||
- next step: open the folder in the agent (`cd <target> && claude`) so the
|
||||
KB's own skills load, drop material into `raw/inbox/` and say *Ingest*;
|
||||
"sync changes" shares the result.
|
||||
|
||||
## Edge cases
|
||||
|
||||
- **Remote has only a host-generated README/licence** — still "not empty".
|
||||
Recreating the repo empty is cleaner than merging; offer that first. If
|
||||
the user insists on keeping it, finish Steps 3–5, then hand over to the
|
||||
new KB's own `ckb-sync-changes`, whose unrelated-histories path asks how
|
||||
to merge.
|
||||
- **Template clone fails** — report the raw error and stop. Don't fall back
|
||||
to a stale `ckb-init` in the user's profile or to a scaffold from memory.
|
||||
- **The user runs this from inside another KB** — fine; the target must
|
||||
still be a separate folder outside it (`ckb-init`'s edge case on nesting
|
||||
applies). The current KB's own rules (log, workload note) apply to the
|
||||
current session as usual; nothing is written into the current KB.
|
||||
- **Windows** — `ckb-init`'s symlinks need Developer Mode or an elevated
|
||||
shell, and `git config core.symlinks true`. If symlinks can't be created,
|
||||
stop before Step 5 and say so; don't commit copies.
|
||||
- **SSH vs HTTPS** — use the URL exactly as given; the joiner can use
|
||||
either form of the same repository.
|
||||
|
||||
---
|
||||
|
||||
*Licensed under the Apache License, Version 2.0 —
|
||||
<http://www.apache.org/licenses/LICENSE-2.0>.*
|
||||
|
|
@ -1,153 +0,0 @@
|
|||
---
|
||||
name: ckb-join
|
||||
description: Join an existing shared Cascade Knowledge Base by its git origin URL — clone it into a folder (given, or a sensible default), check that it really is a Cascade KB, verify git identity, symlinks and upstream mounts, and leave it ready to open in the agent. Installed in a user's profile, so it works from any folder. Use for "join the knowledge base at this URL", "join our wiki", "get me set up on the team KB", "clone our wiki into this folder", "I've been invited to a KB". Not for creating a new KB (ckb-create) or for syncing a KB you already have (ckb-sync-changes inside it).
|
||||
---
|
||||
|
||||
# Join a shared Cascade KB
|
||||
|
||||
## Purpose
|
||||
|
||||
Turn an origin URL into a working local copy of a team KB, and tell the
|
||||
person what (if anything) is still missing on their machine. This skill
|
||||
lives in a person's profile (`~/.claude/skills/`), not in any KB; once the
|
||||
clone exists, the KB's own skills take over.
|
||||
|
||||
Read-only towards the shared history: it clones, inspects and reports. It
|
||||
never commits, pushes, or edits files in the KB. Anything it can't fix
|
||||
without writing to the KB is reported, not done.
|
||||
|
||||
## How to run this skill
|
||||
|
||||
### Step 1 — Inputs
|
||||
|
||||
- **Origin URL** — required. Ask if missing.
|
||||
- **Folder** — optional. Default: `<current working directory>/<repo-name>`,
|
||||
where `<repo-name>` is the last path segment of the URL without `.git`.
|
||||
If the current directory is itself inside a git work tree or a KB, don't
|
||||
default into it — ask where to put the clone instead.
|
||||
|
||||
Resolve the folder to an absolute path and say it back before cloning.
|
||||
|
||||
### Step 2 — Pre-flight
|
||||
|
||||
```bash
|
||||
git --version
|
||||
git config user.name; git config user.email
|
||||
git ls-remote --symref <origin-url> HEAD
|
||||
```
|
||||
|
||||
- **No git identity** — the KB stamps every log entry, workload note and
|
||||
commit with it, so colleagues see who changed what. Ask for name and
|
||||
email and set them with `git config --global` on a yes. If they decline,
|
||||
continue but say the agent will fall back to the OS user name.
|
||||
- **`ls-remote` fails** — report git's raw error. The usual causes: the
|
||||
person hasn't been granted access yet (ask the KB owner), or no
|
||||
credentials for that host (SSH key, credential helper, token). Stop.
|
||||
- **`ls-remote` returns nothing** — the remote is empty: nobody has
|
||||
published a KB there. Say so and suggest the owner runs `ckb-create`.
|
||||
Stop.
|
||||
- **Folder exists**:
|
||||
- empty → clone into it;
|
||||
- already a clone of the same remote (`git -C <folder> remote get-url
|
||||
origin` matches) → nothing to clone; say "you've already joined — open
|
||||
the folder and say *sync changes* to update", then go to Step 4 to
|
||||
check it;
|
||||
- anything else → stop and ask for another folder. Never clone over
|
||||
existing files.
|
||||
|
||||
### Step 3 — Clone
|
||||
|
||||
```bash
|
||||
git clone <origin-url> <folder>
|
||||
```
|
||||
|
||||
Clone the remote's default branch (shown by `ls-remote --symref`). If it is
|
||||
not `main`, say so: the KB's `ckb-sync-changes` assumes `main`, so the owner
|
||||
should either rename the branch or know that sync will need adjusting.
|
||||
|
||||
On Windows, clone with `git clone -c core.symlinks=true …` so `CLAUDE.md`
|
||||
and `.claude/skills` arrive as symlinks (needs Developer Mode or an
|
||||
elevated shell).
|
||||
|
||||
### Step 4 — Check it is a working Cascade KB
|
||||
|
||||
From the folder:
|
||||
|
||||
```bash
|
||||
test -f AGENTS.md && test -f wiki/index.md && test -f ckb.yaml
|
||||
test -L CLAUDE.md && test -L .claude/skills
|
||||
cat VERSION
|
||||
grep kb_schema_version wiki/index.md
|
||||
```
|
||||
|
||||
- **`AGENTS.md` or `wiki/index.md` missing** — this is not a Cascade KB (or
|
||||
not a finished one). Say what was found, leave the clone in place, and
|
||||
ask whether to delete it. Never delete without a yes.
|
||||
- **Symlinks are plain files** — symlinks were not checked out (typically
|
||||
Windows without `core.symlinks`). The agent would read a stale or empty
|
||||
system prompt and see no skills. Tell the user how to fix it on their
|
||||
machine: enable Developer Mode, `git config core.symlinks true`, then
|
||||
`git checkout -- CLAUDE.md .claude/skills`. Don't commit anything.
|
||||
|
||||
Then report what the KB brings with it, from the files alone:
|
||||
|
||||
- **Purpose** — the `tldr` or first lines of `ABOUT.md`.
|
||||
- **Template** — `VERSION`, and `ckb.yaml`'s `template:` branch if it is not
|
||||
`main`.
|
||||
- **Modules** — `ckb.yaml`'s `kb_modules:`; for `software`, note that
|
||||
`src/` clones are not shared through this repo and must be cloned
|
||||
separately if the person needs them.
|
||||
- **Upstream mounts** —
|
||||
- `linked/<name>` symlinks: check each target exists on this machine
|
||||
(`test -e linked/<name>`). A dangling one points at a path on the
|
||||
owner's machine; the person needs that upstream KB locally at the same
|
||||
relative location, or their own symlink (not committed) to it.
|
||||
- `libs/<name>/` with `source.yaml`: connector-backed, its generated index
|
||||
came with the clone; nothing to do unless they are asked to be its admin.
|
||||
- `libs/` folders mentioned in `wiki/` or the docs but absent: git-copy
|
||||
libs are gitignored, so they never arrive with a clone. List them and
|
||||
say who to ask for the source.
|
||||
- **Python** — the first of `python3`, `python`, `py -3` that reports 3.x.
|
||||
If none, say once that the KB still works on its fallback paths and point
|
||||
to "Prerequisites" in its `docs/MANUAL.md`.
|
||||
|
||||
### Step 5 — Session brief (optional, when Python is available)
|
||||
|
||||
```bash
|
||||
cd <folder> && <python> .agents/skills/ckb-lint/scripts/session_start.py --title "Joined the knowledge base"
|
||||
```
|
||||
|
||||
Show the `ckb check:` and `routines:` lines only if they need action. Don't
|
||||
act on them here — that happens in a session inside the KB.
|
||||
|
||||
### Step 6 — Report
|
||||
|
||||
Keep it short:
|
||||
|
||||
- the folder, the origin, the branch, and the KB's purpose line;
|
||||
- anything from Step 4 the person has to fix on their machine, each with
|
||||
its one-line fix — or "nothing to fix";
|
||||
- **next step:** open the folder in the agent (`cd <folder> && claude`) so
|
||||
the KB's own skills and rules load. Good first things to say there:
|
||||
*set up my profile*, *onboard me on <topic>*, or a question. *Sync
|
||||
changes* pulls colleagues' work and shares theirs.
|
||||
|
||||
## Edge cases
|
||||
|
||||
- **The person already has a ZIP copy of the KB** — a ZIP has no `origin`.
|
||||
Clone fresh into a new folder rather than wiring git into the unpacked
|
||||
copy; if they made local changes there, they can copy those files over
|
||||
after the clone and sync.
|
||||
- **They were given a URL to the upstream template (`…/ckb.git`)** rather
|
||||
than a team KB — that repo is the template itself. Joining it is almost
|
||||
never what they want; ask whether they meant to *create* a new KB
|
||||
(`ckb-create`) or have a team KB URL.
|
||||
- **Large repository** — fine to clone in full; don't use `--depth`, since
|
||||
`ckb-sync-changes` merges and needs history.
|
||||
- **Several KBs** — each is its own folder and its own clone; nothing is
|
||||
shared between them unless one mounts the other under `linked/`.
|
||||
|
||||
---
|
||||
|
||||
*Licensed under the Apache License, Version 2.0 —
|
||||
<http://www.apache.org/licenses/LICENSE-2.0>.*
|
||||
|
|
@ -22,7 +22,4 @@ number and its page, and the newer decision points back at it.
|
|||
## Open questions
|
||||
|
||||
Decisions still at `proposed`, and any decision whose `review_on` date has
|
||||
passed without an `outcome_checked` on or after it, are the ones worth
|
||||
chasing. `ckb-lint` reports both. A decision with an `expected_outcome` is
|
||||
reviewed by comparing it with what happened (`ckb-decide`, "review
|
||||
D-NNNN"); the result is appended to its `## Outcome`.
|
||||
passed, are the ones worth chasing. `ckb-lint` reports both.
|
||||
|
|
|
|||
|
|
@ -1,34 +1,15 @@
|
|||
---
|
||||
type: error-book
|
||||
tldr: Recurring ingest/lint problems, each with every fix tried against it, what each fix was expected to change, and what it actually did.
|
||||
last_updated: 2026-11-18
|
||||
tldr: Table of known ingest/lint errors, root causes, and the constraints derived from them.
|
||||
last_updated: 2026-10-09
|
||||
---
|
||||
|
||||
# Error Book
|
||||
|
||||
One entry per **recurring problem**, not per incident. Each entry names the
|
||||
root cause as a hypothesis and keeps every attempt to fix it, in order,
|
||||
including the ones that did not work. Before opening a new entry, check
|
||||
whether an existing one already explains the failure and append to it
|
||||
instead. `ckb-lint` (check 9) owns the format.
|
||||
Records systematic compilation errors, their root causes,
|
||||
and the reusable constraints derived from them.
|
||||
|
||||
<!-- Entry format:
|
||||
| Date | Error | Root Cause | Fix / Constraint |
|
||||
|------|-------|-----------|------------------|
|
||||
|
||||
## E1 — <root-cause hypothesis, one line>
|
||||
- **Opened:** YYYY-MM-DD · **Status:** open | watching | resolved
|
||||
- **Constraint:** <the rule that should prevent recurrence, once one is known>
|
||||
|
||||
| Date | Attempt (what changed, where) | Expected | Observed | Context |
|
||||
|------|-------------------------------|----------|----------|---------|
|
||||
| YYYY-MM-DD | <the fix> (`path/changed.md`) | <what it should stop, written before the result is known> | pending | <model/agent>, template <VERSION> |
|
||||
|
||||
Observed is `pending` until the next lint run that could show it, then
|
||||
`held YYYY-MM-DD`, `recurred YYYY-MM-DD: <how>` or `partly YYYY-MM-DD: <how>`.
|
||||
An attempt is never deleted or reworded after the fact; a later attempt
|
||||
supersedes it.
|
||||
|
||||
A merged entry keeps its number as an alias:
|
||||
## E4 → E2 — merged YYYY-MM-DD (same root cause)
|
||||
-->
|
||||
|
||||
*(No problems recorded yet.)*
|
||||
*(Agent maintains this during lint and ingest operations.)*
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
kb_schema_version: "1.8"
|
||||
kb_schema_version: "1.7"
|
||||
---
|
||||
|
||||
# Knowledge Base Index
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue