Template 1.13.0: conversation autosave switch with per-machine hook check

- ckb.yaml: conversations.autosave (default false). On, Rule E saves every
  session at its end without asking; ckb-add-conversation toggles it on
  request.
- Per-machine half: autosave_hook.py --check/--install/--remove manages a
  Claude Code Stop hook in gitignored .claude/settings.local.json. Rule E
  runs --check at session start when autosave is on and asks before
  changing machine configuration; toggling the switch asks the same.
- save_conversation.py --from-hook reads transcript_path from hook stdin.
- ckb-init writes the block, ckb-upgrade leaves it alone.
- Manual, READMEs and changelog in English and Polish; Polish changelog
  also gains the missing 1.11.1 and 1.12.0 rows.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
Michał Kopeć 2026-10-16 09:38:35 +02:00
parent 6b7f0222c6
commit 29bb631b27
15 changed files with 327 additions and 22 deletions

View file

@ -1,6 +1,6 @@
---
name: ckb-add-conversation
description: Save the current Claude Code conversation (or an earlier session of this project) verbatim into raw/saved-conversations/<YYYY-MM-DD>/ as the original JSONL plus a readable Markdown rendering, and search those saved conversations when asked what was discussed or instructed before. Saved conversations never enter retrieval or the wiki on their own. Use for "save this conversation", "save the chat", "archive this session", "keep a copy of our talk", and for "did we discuss X", "what did I tell you about X", "what did I ask you to do about Y last time", "find the conversation where ...".
description: Save the current Claude Code conversation (or an earlier session of this project) verbatim into raw/saved-conversations/<YYYY-MM-DD>/ as the original JSONL plus a readable Markdown rendering, and search those saved conversations when asked what was discussed or instructed before. Saved conversations never enter retrieval or the wiki on their own. Use for "save this conversation", "save the chat", "archive this session", "keep a copy of our talk", for "did we discuss X", "what did I tell you about X", "what did I ask you to do about Y last time", "find the conversation where ...", and for toggling the autosave switch: "save conversations automatically", "turn on/off conversation autosave", "stop saving every conversation".
---
# Add conversation skill
@ -24,8 +24,10 @@ What this skill is **not**:
- Not ingest. A saved conversation becomes wiki knowledge only when the user
copies its `.md` into `raw/inbox/` and says "Ingest" — the copy is theirs
to make, so the choice of what enters the wiki stays explicit.
- Not automatic. The agent asks at session end (Rule E) and saves only on a
clear yes. Never save because a session "seems important".
- Not automatic by default. The agent asks at session end (Rule E) and
saves only on a clear yes. Never save because a session "seems
important". The one exception is the `autosave` switch below, which the
user turns on deliberately.
## Where transcripts come from
@ -120,6 +122,71 @@ with the header the script would write, see `INDEX_HEADER` in the script).
Tell the user once that the readable `.md` can be produced later by re-running
the script with `--from <that jsonl>` once Python is available.
## The autosave switch
`ckb.yaml` carries:
```yaml
conversations:
autosave: false # true: save every session's transcript at session end without asking
```
With `autosave: true`, Rule E saves the conversation at session end without
asking and reports the path in one line; the workload note names the file as
usual. With `false` or no block at all, the agent asks once, as described
above. The switch is repo-level and committed, so everyone working in this
KB gets the same behaviour.
**Toggling it on request** ("save conversations automatically", "turn off
autosave"): read `ckb.yaml`, change only the `autosave` value, write the
file back with everything else byte-for-byte intact (`template:` and
`kb_modules:` belong to other skills). Add the `conversations:` block if it
is missing. Confirm the new value in one line, then run the per-machine
check described below and ask about the hook. When turning it on, say once
that every session will become a tracked file in the repo, including
whatever file contents and command output the agent prints — the caveat in
Save Step 2 no longer gets a chance to be said per session.
**The per-machine half.** The agent-side rule saves at session end only
when the agent reaches that step; a session killed mid-turn is not saved. A
Claude Code `Stop` hook closes that gap: it runs `save_conversation.py
--from-hook` after every turn, and the script updates the same files in
place. The hook reads the transcript path from the hook's stdin JSON, so the
right session is saved even when several run in parallel.
Hooks are machine configuration, not template: they live in
`.claude/settings.local.json`, which is gitignored. So the switch in
`ckb.yaml` travels with the repo, and every machine that opens the repo has
to be brought in line separately. `scripts/autosave_hook.py` does that:
```bash
<python> .agents/skills/ckb-add-conversation/scripts/autosave_hook.py --check # exit 0 = consistent, 1 = action needed
<python> .agents/skills/ckb-add-conversation/scripts/autosave_hook.py --install # merge the hook into settings.local.json
<python> .agents/skills/ckb-add-conversation/scripts/autosave_hook.py --remove # take it out, leave the rest intact
```
`--install` takes `--python <cmd>` so the hook command uses the interpreter
that actually works on this machine (resolve `<python>` as `AGENTS.md` §3
describes and pass it). It merges into an existing file and refuses to
touch one that is not valid JSON.
**Never change machine configuration silently.** Two moments call for the
check, and both end in a question, not an action:
1. *Session start* (Rule E) — when `autosave: true`, run `--check`. On exit 1
tell the user in one line what is out of line and ask whether to
install (or remove) the hook on this machine. Apply only on a yes. If
they decline, do not ask again this session; autosave then relies on the
session-end rule alone, which is worth saying once.
2. *Toggling the switch* — right after flipping `autosave` in `ckb.yaml`,
run `--check` and ask the same question, so the switch and this machine
agree from the first session. Turning autosave off and leaving the hook
installed would keep saving every session, which is exactly what the
user just asked to stop.
Without Python the hook cannot run either, so there is nothing to install:
say so once and rely on the session-end rule.
## How to run this skill — Recall
Triggers: "did we discuss X", "have we talked about X before", "what did I

View file

@ -0,0 +1,126 @@
#!/usr/bin/env python3
"""Check, install or remove the per-machine Claude Code Stop hook that makes
conversation autosave mechanical.
autosave_hook.py --check # one line of status; exit 0 = nothing to do, 1 = action needed
autosave_hook.py --install # add the hook to .claude/settings.local.json (merge, never overwrite)
autosave_hook.py --remove # take it out again, leaving everything else intact
The hook lives in .claude/settings.local.json, which is per machine and
gitignored. It runs save_conversation.py --from-hook after every turn, so the
transcript on disk is always current even if the session dies mid-turn.
Python 3.8+, standard library only.
"""
import argparse
import json
import sys
from pathlib import Path
SETTINGS = Path(".claude") / "settings.local.json"
SCRIPT = ".agents/skills/ckb-add-conversation/scripts/save_conversation.py"
MARK = "save_conversation.py --from-hook"
def read_yaml_autosave(path=Path("ckb.yaml")) -> bool:
"""Minimal reader: find `autosave:` under `conversations:`. No YAML parser needed."""
if not path.exists():
return False
in_block = False
for raw in path.read_text(encoding="utf-8").splitlines():
line = raw.split("#", 1)[0].rstrip()
if not line.strip():
continue
if not line.startswith((" ", "\t")):
in_block = line.strip() == "conversations:"
continue
if in_block and line.strip().startswith("autosave:"):
return line.split(":", 1)[1].strip().lower() in ("true", "yes", "on")
return False
def load_settings():
if not SETTINGS.exists():
return {}
try:
return json.loads(SETTINGS.read_text(encoding="utf-8") or "{}")
except json.JSONDecodeError as e:
sys.exit(f"error: {SETTINGS} is not valid JSON ({e}); fix it by hand before installing the hook")
def hook_command(python: str) -> str:
return f"{python} {SCRIPT} --from-hook >/dev/null 2>&1 || true"
def installed(settings) -> bool:
for group in settings.get("hooks", {}).get("Stop", []) or []:
for h in group.get("hooks", []) or []:
if MARK in str(h.get("command", "")):
return True
return False
def install(python: str):
s = load_settings()
if installed(s):
print(f"already installed in {SETTINGS}")
return
s.setdefault("hooks", {}).setdefault("Stop", []).append(
{"hooks": [{"type": "command", "command": hook_command(python)}]})
SETTINGS.parent.mkdir(parents=True, exist_ok=True)
SETTINGS.write_text(json.dumps(s, indent=2) + "\n", encoding="utf-8")
print(f"installed Stop hook in {SETTINGS}: {hook_command(python)}")
def remove():
s = load_settings()
if not installed(s):
print(f"not installed in {SETTINGS}")
return
groups = []
for group in s["hooks"]["Stop"]:
kept = [h for h in group.get("hooks", []) if MARK not in str(h.get("command", ""))]
if kept:
group["hooks"] = kept
groups.append(group)
if groups:
s["hooks"]["Stop"] = groups
else:
del s["hooks"]["Stop"]
if not s["hooks"]:
del s["hooks"]
SETTINGS.write_text(json.dumps(s, indent=2) + "\n", encoding="utf-8")
print(f"removed Stop hook from {SETTINGS}")
def check() -> int:
auto = read_yaml_autosave()
have = installed(load_settings()) if SETTINGS.exists() else False
if auto and not have:
print(f"autosave: on in ckb.yaml, Stop hook NOT installed in {SETTINGS} — ask the user, then --install")
return 1
if not auto and have:
print(f"autosave: off in ckb.yaml, but a Stop hook is still installed in {SETTINGS} — ask the user, then --remove")
return 1
print(f"autosave: {'on, hook installed' if auto else 'off, no hook'}")
return 0
def main(argv=None):
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
g = ap.add_mutually_exclusive_group(required=True)
g.add_argument("--check", action="store_true")
g.add_argument("--install", action="store_true")
g.add_argument("--remove", action="store_true")
ap.add_argument("--python", default="python3", help="interpreter to put in the hook command (default python3)")
a = ap.parse_args(argv)
if a.check:
return check()
if a.install:
install(a.python)
else:
remove()
return 0
if __name__ == "__main__":
sys.exit(main())

View file

@ -9,6 +9,7 @@ Markdown rendering next to it, then updates raw/saved-conversations/index.md.
save_conversation.py --list # list this project's sessions, newest first
save_conversation.py --session <id> # save a specific session (id or unique prefix)
save_conversation.py --from <file.jsonl> # save a transcript file given explicitly
save_conversation.py --from-hook # Claude Code hook: read {"transcript_path": ...} from stdin
save_conversation.py --title "..." # override the derived title
save_conversation.py --dry-run # say what would be written, write nothing
@ -266,6 +267,8 @@ def main(argv=None):
ap.add_argument("--list", action="store_true", help="list this project's sessions and exit")
ap.add_argument("--session", help="session id (or unique prefix) to save; default: most recently written")
ap.add_argument("--from", dest="from_file", help="save this transcript file instead of looking one up")
ap.add_argument("--from-hook", action="store_true",
help="read Claude Code hook JSON from stdin and save its transcript_path")
ap.add_argument("--title", help="override the derived title")
ap.add_argument("--root", default=".", help="KB root (default: current directory)")
ap.add_argument("--today", help="override the save date, YYYY-MM-DD (tests)")
@ -275,6 +278,14 @@ def main(argv=None):
root = Path(args.root).resolve()
today = args.today or datetime.now().strftime("%Y-%m-%d")
if args.from_hook:
try:
hook = json.load(sys.stdin)
except (json.JSONDecodeError, ValueError):
sys.exit("error: --from-hook expects hook JSON on stdin")
args.from_file = hook.get("transcript_path")
if not args.from_file:
sys.exit("error: hook JSON carries no transcript_path")
if args.from_file:
src = Path(args.from_file).expanduser().resolve()
if not src.is_file():

View file

@ -263,8 +263,10 @@ a fresh KB by accident is easy, and the local working tree is exactly how it
happens.
`ckb.yaml` is also the modules manifest (`ckb-module` owns the `kb_modules:`
list). A fresh KB has no modules, so at init time the file holds the
`template:` block alone.
list) and carries the conversation autosave switch (`ckb-add-conversation`
owns `conversations:`). A fresh KB has no modules, so at init time the file
holds the `template:` block, an empty `kb_modules: []`, and
`conversations:` with `autosave: false`.
For `LICENSE`, copy the Apache License 2.0 text, but **ask the user first**
whether to keep the copyright line as-is (appropriate if this new KB is

View file

@ -298,8 +298,9 @@ Only if `template_upgrade_available` and at least one item was accepted:
- If the user switched channel for this run (Step 0), write the new
`branch:` into `ckb.yaml`'s `template:` block now that the switch has
actually happened. Create the file with just that block if it doesn't
exist; if it does, edit only `template:` and leave `kb_modules:` exactly
as found — that list belongs to `ckb-module`. Persisting the branch is
exist; if it does, edit only `template:` and leave `kb_modules:` and
`conversations:` exactly as found — those belong to `ckb-module` and
`ckb-add-conversation`. Persisting the branch is
what stops the *next* upgrade from silently pulling the KB back to
whichever channel it was on before.

2
.gitignore vendored
View file

@ -18,5 +18,7 @@ outputs/teaching
.env
__pycache__/
*.pyc
# Per-machine Claude Code settings (e.g. the conversation autosave Stop hook). Never shared.
.claude/settings.local.json
# Local scratch for ideas about changing the template. Never committed, never part of the template.
ideas/

View file

@ -15,7 +15,7 @@ Maintain this root layout:
```
├── .agents/modules/ # Optional modules, inert until installed
├── ckb.yaml # Repo manifest: template branch, installed modules
├── ckb.yaml # Repo manifest: template branch, installed modules, conversation autosave
├── docs/ # Manual, changelog, OpenSpec guide, template design records
│ └── decisions/ # The template's own ADRs (D-0001…) — not KB content
├── tests/ # Fixture KB + smoke test for the deterministic scripts
@ -277,6 +277,19 @@ bash .agents/skills/ckb-lint/scripts/lint_quick.sh
powershell -ExecutionPolicy Bypass -File .agents/skills/ckb-lint/scripts/lint_quick.ps1 # Windows
```
When `ckb.yaml` has `conversations.autosave: true`, run a third check:
```bash
<python> .agents/skills/ckb-add-conversation/scripts/autosave_hook.py --check
```
Exit 1 means this machine's configuration does not match the switch (the
Stop hook that makes autosave mechanical is missing, or is still installed
after autosave was turned off). Ask once whether to change
`.claude/settings.local.json` accordingly, and apply only on a yes —
`ckb-add-conversation` owns the details. Skip the check entirely when
autosave is off and no hook file exists; stay quiet on exit 0.
`git status` covers unsynchronized history — if there are uncommitted
changes or the branch is ahead/behind its remote-tracking branch, say so and
suggest `ckb-sync-changes`. `--quick` covers knowledge rot: one line stating
@ -288,11 +301,14 @@ is non-zero and suggest `ckb-lint`; stay quiet when it is clean.
At session end, update `workload/` and repeat the unsynchronized-change
check. Do not fetch or push unless the user asks.
Also at session end, when the session did real work (ingested, answered,
decided, changed files), ask once whether to save the conversation with
`ckb-add-conversation`, the same way the sync check is a suggestion and not
an action. Skip the question for a trivial session. Save only on a clear
yes; never save on your own initiative.
Also at session end, read `conversations.autosave` in `ckb.yaml`:
- `true` — save the conversation with `ckb-add-conversation` without
asking, and report the saved path in one line.
- `false` or absent — when the session did real work (ingested, answered,
decided, changed files), ask once whether to save, the same way the sync
check is a suggestion and not an action. Skip the question for a trivial
session. Save only on a clear yes; never save on your own initiative.
### Rule F: Demand-Driven Context
When the KB cannot answer something, identify the missing knowledge and

View file

@ -419,10 +419,13 @@ add yourself.
- **Session start** → read `wiki/index.md` and the latest workload summary;
run `git status` and `lint_report.py --quick`; suggest `ckb-sync-changes`
or `ckb-lint` only when either reports something
or `ckb-lint` only when either reports something; when conversation
autosave is on, also check this machine has the gitignored Stop hook in
`.claude/settings.local.json` and ask before installing it
- **Session end** → append to `workload/`; repeat the unsynchronized-change
check; after a session that did real work, ask once whether to save the
conversation (`ckb-add-conversation`) - saved only on a yes
conversation (`ckb-add-conversation`) - saved only on a yes, or without
asking when `conversations.autosave: true` is set in `ckb.yaml`
- **Every turn that touches the KB** → a note in `workload/` (Rule D)
- **Unanswerable question** → a `wiki/query-gaps.md` entry, the one write
`ckb-retrieve` owns; answers are never filed back as pages automatically
@ -518,7 +521,10 @@ conversations stay outside retrieval: questions are still answered from the
wiki alone. You can ask about the conversations themselves ("did we discuss
X", "what did I tell you about Y") and get the exact exchange quoted back.
To bring one into the wiki, copy its `.md` into `raw/inbox/` and say
"Ingest". Skill: `.agents/skills/ckb-add-conversation/SKILL.md`.
"Ingest". Say "save conversations automatically" to flip
`conversations.autosave` in `ckb.yaml`, after which every session is saved
at its end without a question. Skill:
`.agents/skills/ckb-add-conversation/SKILL.md`.
### Quiz Mode (on demand)
Ask to be quizzed on the wiki ("quiz me on X", "test my knowledge") for a

View file

@ -460,7 +460,10 @@ albo zaplanowanego agenta.
- **Start sesji** → odczyt `wiki/index.md` i ostatniego podsumowania
workload; `git status` i `lint_report.py --quick`; sugestia
`ckb-sync-changes` lub `ckb-lint` tylko wtedy, gdy któreś coś zgłosi
`ckb-sync-changes` lub `ckb-lint` tylko wtedy, gdy któreś coś zgłosi;
przy włączonym autozapisie rozmów sprawdza też, czy ta maszyna ma hook
`Stop` w ignorowanym przez gita `.claude/settings.local.json`, i pyta
przed jego zainstalowaniem
- **Koniec sesji** → dopisanie do `workload/`; powtórzenie sprawdzenia
niezsynchronizowanych zmian
- **Każda tura dotykająca KB** → notatka w `workload/` (Reguła D)
@ -570,7 +573,9 @@ w tym folderze. Zapisane rozmowy pozostają poza wyszukiwaniem: na pytania
agent nadal odpowiada wyłącznie z wiki. Możesz natomiast pytać o same
rozmowy („czy rozmawialiśmy o X", „co ci mówiłem o Y") i dostać zacytowaną
dokładną wymianę zdań. Aby przenieść rozmowę do wiki, skopiuj jej `.md` do
`raw/inbox/` i powiedz „Ingest". Skill:
`raw/inbox/` i powiedz „Ingest". Powiedz „save conversations automatically",
aby przełączyć `conversations.autosave` w `ckb.yaml` - od tej pory każda
sesja jest zapisywana na końcu bez pytania. Skill:
`.agents/skills/ckb-add-conversation/SKILL.md`.
### Tryb quizu (na żądanie)

View file

@ -1 +1 @@
1.12.0
1.13.0

View file

@ -1,8 +1,12 @@
# Cascade KB manifest — repo-level configuration, not the wiki's content contract
# (kb_schema_version stays in wiki/index.md). Written by ckb-init, read by
# ckb-upgrade (template:) and ckb-module (kb_modules:).
# ckb-upgrade (template:), ckb-module (kb_modules:) and ckb-add-conversation
# (conversations:).
template:
repo: https://git.wierzbowa.cloud/michal/ckb.git
branch: main # main | test | experimental
kb_modules: []
conversations:
autosave: false # true: save every session's transcript at session end without asking

View file

@ -284,7 +284,8 @@ docs. Independent of the content schema above.
| Version | Date | What landed | Schema |
|---|---|---|---|
| **1.12.0** | 2026-10-16 | `ckb-add-conversation`: on request, copies the session's Claude Code transcript (JSONL, byte for byte) into `raw/saved-conversations/<date>/` with a readable `.md` rendering and an `index.md`; answers "did we discuss X" / "what did I tell you about Y" from those files. Saved conversations are outside retrieval and outside ingest until the user copies one into `raw/inbox/`. Rule E asks once at session end whether to save; `ckb-retrieve`, `ckb-ingest`, `ckb-reset` (tier 3) and `ckb-init` know the folder; smoke test renders a fixture transcript | 1.5 |
| **1.13.0** | 2026-10-16 | Conversation autosave switch: `conversations.autosave` in `ckb.yaml` (default `false`). On, Rule E saves every session at its end without asking; `ckb-add-conversation` toggles it on request ("save conversations automatically"). Per-machine half: `autosave_hook.py --check/--install/--remove` manages a Claude Code `Stop` hook in gitignored `.claude/settings.local.json`; Rule E runs the check at session start when autosave is on and asks before changing machine configuration; `save_conversation.py --from-hook` takes the transcript path from hook stdin. `ckb-init` writes the block, `ckb-upgrade` leaves it alone | 1.5 |
| 1.12.0 | 2026-10-16 | `ckb-add-conversation`: on request, copies the session's Claude Code transcript (JSONL, byte for byte) into `raw/saved-conversations/<date>/` with a readable `.md` rendering and an `index.md`; answers "did we discuss X" / "what did I tell you about Y" from those files. Saved conversations are outside retrieval and outside ingest until the user copies one into `raw/inbox/`. Rule E asks once at session end whether to save; `ckb-retrieve`, `ckb-ingest`, `ckb-reset` (tier 3) and `ckb-init` know the folder; smoke test renders a fixture transcript | 1.5 |
| 1.11.1 | 2026-10-09 | Five defects fixed, all reported by a downstream KB. `retrieve_candidates.py`: `load_pages` walks sorted, so a golden expectation no longer encodes one machine's directory order (the smoke test failed on a clean clone); a source cited by N pages now corroborates all N instead of whichever page was walked first. `lint_report.py` check 12: a cited directory is legal and unfingerprinted, no longer reported as missing (same fix in `lint_quick.sh`/`.ps1`). Check 8: a root-log `POINTER` is no longer read as a duplicate of the decisions-log entry it points at. Check 13: a quote attributed to a conversation or a person counts as attributed, not unattributed. `AGENTS.md` §2 documents directory citations and the two attribution shapes; fixture KB covers all three lint regressions | 1.5 |
| 1.11.0 | 2026-09-29 | Python made optional where it can be: `<python>` interpreter resolution (`python3`/`python`/`py -3`) in `AGENTS.md`; per-OS install guide in the manual; `lint_quick.sh`/`.ps1` fallback for the session-start check (smoke-tested against `--quick`); manual lint checklist and no-script retrieval path; exporters state Python as a hard requirement; inline `python3 -c` dropped from `ckb-upgrade`/`ckb-reset`; D-0003. Lint check 13 matches each Crux block only against the source attributed under it (multi-source Crux no longer cross-fails; wrapped quotes matched as one block); fixture KB gains a second source | 1.5 |
| 1.10.0 | 2026-09-24 | Skill descriptions and bodies slimmed (edge cases → `references/`); `retrieve_candidates.py` takes over rank fusion; docs moved to `docs/`, template ADRs restored to `docs/decisions/`; `tests/` fixture + `smoke.sh`; `ckb.yaml` shipped; Rule B names the decisions-log exception; scaffold `overview.md` describes content, not schema; "Sync the wiki" trigger dropped | 1.5 |

View file

@ -291,7 +291,10 @@ Niezależna od schematu treści powyżej.
| Wersja | Data | Co weszło | Schemat |
|---|---|---|---|
| **1.11.0** | 2026-09-29 | Python opcjonalny tam, gdzie to możliwe: wybór interpretera `<python>` (`python3`/`python`/`py -3`) w `AGENTS.md`; instrukcja instalacji per system w podręczniku; zapasowe `lint_quick.sh`/`.ps1` dla kontroli na starcie sesji (testowane smoke wobec `--quick`); ręczna lista kontrolna lintu i ścieżka wyszukiwania bez skryptu; eksporty deklarują Pythona jako wymóg twardy; usunięte wbudowane `python3 -c` z `ckb-upgrade`/`ckb-reset`; D-0003. Kontrola lintu 13 porównuje każdy blok Crux tylko ze źródłem przypisanym pod nim (Crux z wielu źródeł już nie daje fałszywych wyników; cytaty łamane na kilka linii sprawdzane jako jeden blok); KB testowy zyskuje drugie źródło | 1.5 |
| **1.13.0** | 2026-10-16 | Przełącznik autozapisu rozmów: `conversations.autosave` w `ckb.yaml` (domyślnie `false`). Po włączeniu Reguła E zapisuje każdą sesję na jej końcu bez pytania; `ckb-add-conversation` przełącza go na żądanie („save conversations automatically”). Połowa per maszyna: `autosave_hook.py --check/--install/--remove` zarządza hookiem `Stop` Claude Code w ignorowanym przez gita `.claude/settings.local.json`; Reguła E uruchamia kontrolę na starcie sesji przy włączonym autozapisie i pyta przed zmianą konfiguracji maszyny; `save_conversation.py --from-hook` bierze ścieżkę transkryptu ze stdin hooka. `ckb-init` zapisuje blok, `ckb-upgrade` go nie rusza | 1.5 |
| 1.12.0 | 2026-10-16 | `ckb-add-conversation`: na żądanie kopiuje transkrypt sesji Claude Code (JSONL, bajt w bajt) do `raw/saved-conversations/<data>/` wraz z czytelną wersją `.md` i `index.md`; odpowiada na „did we discuss X” / „what did I tell you about Y” z tych plików. Zapisane rozmowy są poza wyszukiwaniem i poza ingestem, dopóki użytkownik nie skopiuje jednej do `raw/inbox/`. Reguła E pyta raz na końcu sesji, czy zapisać; `ckb-retrieve`, `ckb-ingest`, `ckb-reset` (poziom 3) i `ckb-init` znają ten folder; test smoke renderuje transkrypt z fixture | 1.5 |
| 1.11.1 | 2026-10-09 | Pięć usterek naprawionych, wszystkie zgłoszone przez KB pochodną. `retrieve_candidates.py`: `load_pages` przechodzi katalogi w kolejności posortowanej, więc oczekiwany wynik testu nie koduje już kolejności katalogów jednej maszyny (test smoke nie przechodził na czystym klonie); źródło cytowane przez N stron potwierdza teraz wszystkie N, a nie tylko pierwszą napotkaną. `lint_report.py` kontrola 12: cytowany katalog jest legalny i bez skrótu, nie jest już zgłaszany jako brakujący (ta sama poprawka w `lint_quick.sh`/`.ps1`). Kontrola 8: `POINTER` w dzienniku głównym nie jest już czytany jako duplikat wpisu dziennika decyzji, na który wskazuje. Kontrola 13: cytat przypisany do rozmowy lub osoby liczy się jako przypisany, nie jako nieprzypisany. `AGENTS.md` §2 dokumentuje cytowanie katalogów i dwie formy atrybucji; KB testowy pokrywa wszystkie trzy regresje lintu | 1.5 |
| 1.11.0 | 2026-09-29 | Python opcjonalny tam, gdzie to możliwe: wybór interpretera `<python>` (`python3`/`python`/`py -3`) w `AGENTS.md`; instrukcja instalacji per system w podręczniku; zapasowe `lint_quick.sh`/`.ps1` dla kontroli na starcie sesji (testowane smoke wobec `--quick`); ręczna lista kontrolna lintu i ścieżka wyszukiwania bez skryptu; eksporty deklarują Pythona jako wymóg twardy; usunięte wbudowane `python3 -c` z `ckb-upgrade`/`ckb-reset`; D-0003. Kontrola lintu 13 porównuje każdy blok Crux tylko ze źródłem przypisanym pod nim (Crux z wielu źródeł już nie daje fałszywych wyników; cytaty łamane na kilka linii sprawdzane jako jeden blok); KB testowy zyskuje drugie źródło | 1.5 |
| 1.10.0 | 2026-09-24 | Odchudzone opisy i treści skilli (przypadki brzegowe → `references/`); `retrieve_candidates.py` przejmuje fuzję rankingów; dokumentacja przeniesiona do `docs/`, ADR-y szablonu przywrócone w `docs/decisions/`; fixture `tests/` + `smoke.sh`; dołączony `ckb.yaml`; Reguła B nazywa wyjątek dziennika decyzji; szkieletowy `overview.md` opisuje treść, nie schemat; usunięty wyzwalacz „Sync the wiki” | 1.5 |
| 1.9.0 | 2026-09-22 | Kanały wydawnicze: gałęzie `main`/`test`/`experimental`, świadome gałęzi `ckb-init` i `ckb-upgrade`, blok `template:` w `ckb.yaml` | 1.5 |
| 1.8.0 | 2026-09-21 | Siedem pomysłów zaadaptowanych z Graftu: crux/notes/skróty źródeł, tryb `--quick` lintu, ranking po stopniu wejściowym, promień rażenia w ingeście, dokończony słownik krawędzi | → 1.5 |

View file

@ -696,6 +696,20 @@ I tell you about naming last week", "what did I ask you to do about the
export". The agent searches the saved `.md` files and quotes the exact
exchange, with the date.
If you would rather not be asked, say "save conversations automatically":
the agent flips `autosave: true` under `conversations:` in `ckb.yaml`, and
from then on every session is saved at its end without a question. "Turn
off autosave" flips it back. The switch is committed with the repo, so it
applies to everyone working in that KB. Because it is a rule the agent
follows at session end, a session that is killed mid-turn would be missed -
so the feature has a per-machine half: a Claude Code `Stop` hook in
`.claude/settings.local.json` (gitignored) that re-saves the transcript
after every turn. The agent never installs it on its own. When autosave is
on, the session-start check notices a machine where the hook is missing (or
one where autosave was turned off but the hook is still there) and asks
once whether to change that machine's configuration; it applies the change
only if you say yes. Each machine that opens the repo gets asked once.
If a conversation holds knowledge that belongs in the wiki, copy its `.md`
into `raw/inbox/` and say "Ingest" - the copy is yours to make, so nothing
enters the wiki without you choosing it. Note that a transcript is
@ -865,6 +879,7 @@ scripts' output.
| "Reset the wiki" / "Make this a clean template" | **Destructive.** Deletes accumulated knowledge and restores the empty scaffold, after an inventory and a typed confirmation | `ckb-reset` |
| "Sync changes" / "Sync with git" | Commits, pulls, resolves conflicts, pushes to `origin` | `ckb-sync-changes` |
| "Save this conversation" | Copies the session transcript (JSONL + readable `.md`) into `raw/saved-conversations/<date>/`; outside retrieval | `ckb-add-conversation` |
| "Save conversations automatically" / "Turn off autosave" | Flips `conversations.autosave` in `ckb.yaml`; on, every session is saved at its end without asking | `ckb-add-conversation` |
| "Did we discuss X" / "What did I tell you about X" | Searches saved conversations and quotes the exchange | `ckb-add-conversation` |
| "Quiz me on X" | One-off scored knowledge test | `ckb-quiz` |
| "Teach me the wiki" / "Teach me about X" | Plans and runs a spaced-out course with progress tracking | `ckb-teach-me` |

View file

@ -457,6 +457,9 @@ Agent przypomina o tym również sam, automatycznie: na początku i na końcu
sesji pracy wykonuje szybkie, tylko-do-odczytu sprawdzenie, czy jest coś
niezacommitowanego lub niewypchniętego, i informuje, czy warto uruchomić
„sync changes” — nigdy nie wypycha zmian samodzielnie, bez twojej prośby.
W tym samym duchu na końcu sesji, w której wykonano realną pracę, pyta raz,
czy zapisać rozmowę (zob. „Zapisywanie rozmowy” w Przykładach użycia) — i
zapisuje tylko wtedy, gdy się zgodzisz.
### Budowanie współdzielonej kaskady (synchronizacja na poziomie KB)
@ -707,6 +710,46 @@ W pełni opisane w [§2](#2-dodawanie-wiedzy) — w skrócie: wrzuć materiał d
`raw/inbox/` i powiedz „Ingest”, albo po prostu powiedz agentowi w
rozmowie, jeśli to wystarczająco krótkie, żeby podać wprost.
### Zapisywanie rozmowy
Powiedz „save this conversation”, a agent skopiuje transkrypt sesji do
`raw/saved-conversations/<RRRR-MM-DD>/` — oryginalny plik JSONL, który
przechowuje Claude Code, bajt w bajt, plus czytelną wersję `.md` tej samej
wymiany zdań (twoje wiadomości i odpowiedzi agenta dosłownie, wywołania
narzędzi jako jednolinijkowe notatki, wyniki narzędzi skrócone, prywatne
rozumowanie agenta pominięte). `raw/saved-conversations/index.md` wymienia
wszystko, co zapisano. Wcześniejsze sesje tego samego projektu też można
zapisać: poproś, a agent wyświetli listę do wyboru.
Zapisane rozmowy są celowo **poza** wiki. Na pytania agent nadal odpowiada
wyłącznie z `wiki/`, `linked/` i `libs/` — transkrypt sam z siebie nigdy
nie staje się dowodem. Możesz natomiast pytać o same rozmowy: „czy
rozmawialiśmy o przełączeniu rozliczeń”, „co ci mówiłem o nazewnictwie w
zeszłym tygodniu”, „o co cię prosiłem w sprawie eksportu”. Agent przeszukuje
zapisane pliki `.md` i cytuje dokładną wymianę zdań wraz z datą.
Jeśli wolisz nie być pytany, powiedz „save conversations automatically”:
agent przestawi `autosave: true` w bloku `conversations:` w `ckb.yaml` i od
tej pory każda sesja jest zapisywana na końcu bez pytania. „Turn off
autosave” przestawia z powrotem. Przełącznik jest commitowany z
repozytorium, więc dotyczy wszystkich pracujących w tej KB. Ponieważ jest to
reguła, którą agent wykonuje na końcu sesji, sesja przerwana w połowie tury
zostałaby pominięta — dlatego funkcja ma też połowę per maszyna: hook
`Stop` Claude Code w `.claude/settings.local.json` (ignorowanym przez gita),
który ponownie zapisuje transkrypt po każdej turze. Agent nigdy nie
instaluje go samodzielnie. Przy włączonym autozapisie kontrola na starcie
sesji zauważa maszynę, na której hooka brakuje (albo taką, na której
autozapis wyłączono, a hook wciąż jest), i pyta raz, czy zmienić
konfigurację tej maszyny; zmianę wprowadza tylko po twojej zgodzie. Każda
maszyna otwierająca repozytorium zostaje zapytana raz.
Jeśli rozmowa zawiera wiedzę, która należy do wiki, skopiuj jej `.md` do
`raw/inbox/` i powiedz „Ingest” — kopię robisz ty, więc nic nie trafia do
wiki bez twojego wyboru. Pamiętaj, że transkrypt jest dosłowny: zawiera
wszystko, co agent wypisał w trakcie sesji (zawartość plików, wyniki
poleceń), i staje się śledzonym plikiem w repozytorium.
Skill: `.agents/skills/ckb-add-conversation/SKILL.md`.
### Indeksowanie zewnętrznego źródła
Powiedz:
@ -875,6 +918,9 @@ lub `main`; z `--update` po zamierzonej zmianie wyjścia skryptów.
| „Lint” | Sprawdza kondycję wiki, automatycznie naprawia to, co bezpiecznie może | `ckb-lint` |
| „Zresetuj wiki” / „Zrób z tego czysty szablon” | **Destrukcyjne.** Usuwa zgromadzoną wiedzę i odtwarza pusty szkielet, po inwentarzu i potwierdzeniu wpisaną frazą | `ckb-reset` |
| „Sync changes” / „Sync with git” | Commituje, pobiera, rozwiązuje konflikty, wypycha do `origin` | `ckb-sync-changes` |
| „Save this conversation” | Kopiuje transkrypt sesji (JSONL + czytelne `.md`) do `raw/saved-conversations/<data>/`; poza wyszukiwaniem | `ckb-add-conversation` |
| „Did we discuss X” / „What did I tell you about X” | Przeszukuje zapisane rozmowy i cytuje wymianę zdań | `ckb-add-conversation` |
| „Save conversations automatically” / „Turn off autosave” | Przestawia `conversations.autosave` w `ckb.yaml`; po włączeniu każda sesja jest zapisywana na końcu bez pytania | `ckb-add-conversation` |
| „Quiz me on X” | Jednorazowy, punktowany sprawdzian wiedzy | `ckb-quiz` |
| „Teach me the wiki” / „Teach me about X” | Planuje i prowadzi rozłożony w czasie kurs ze śledzeniem postępu | `ckb-teach-me` |
| „Onboard me on X” / „Where do I start with X” | Krótka, prowadzona kolejność czytania po grafie | `ckb-onboard-me` |