Template 1.22.0: agent-knowledge release 1

Seven features from the 2026-10-31 agent-knowledge research, no schema
change (kb_schema_version stays 1.5):

- F1 session-start hook: session_start.py --hook, start_hook.py, opt-in
  via session.start_hook in ckb.yaml (D-0011)
- F2 kept answers in outputs/answers/, lint check 16 (D-0013)
- F3 ingest check-in before writing; batch mode skips it
- F5 open threads in workload notes, collected at session start (D-0012)
- F6 dedup_inbox.py: duplicates reported before ingest
- F19 lint check 15 for secrets and <private> spans, --secrets before
  every sync commit, redaction in saved conversations (D-0013)
- F20 context budget: lint_report.py --budget, budget in ckb.yaml

Smoke test covers every new script. Docs updated in EN and PL.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Michał Kopeć 2026-11-02 19:25:02 +01:00
parent da2833abfe
commit cb56da51e5
31 changed files with 1504 additions and 76 deletions

View file

@ -53,6 +53,13 @@ anything secret-looking (`.env`, keys, tokens, credentials, personal data),
say so and let them decide. Thinking blocks are never rendered into the
Markdown but remain in the JSONL copy.
Anything the user wrapped in `<private>…</private>` is redacted by the
script in both files (an unclosed tag redacts to the end of that message).
Only the span itself is removed: if the agent repeated a private value in a
reply or a tool call, that copy stays, so mention it when you know it
happened. After saving, `ckb-lint` check 15 (`lint_report.py --secrets`)
flags credential shapes in the saved files before they are committed.
### Step 3 — Save
```bash

View file

@ -14,6 +14,10 @@ Markdown rendering next to it, then updates raw/saved-conversations/index.md.
save_conversation.py --set-title "..." # remember a title for the session (tmp/conversation-titles/), then exit
save_conversation.py --dry-run # say what would be written, write nothing
Anything between <private> and </private> (or to the end of the message when
the tag is never closed) is replaced by <private>[redacted]</private> in both
the saved JSONL and the Markdown. Lines without a span stay byte-identical.
Title precedence: --title, then the title stored by --set-title for this
session, then Claude Code's own custom (/rename) or AI title, then the first
user line.
@ -36,6 +40,8 @@ TITLES_DIR = Path("tmp") / "conversation-titles" # per machine (tmp/ is gitign
RESULT_CHARS = 400
INPUT_CHARS = 200
SYSTEM_REMINDER = re.compile(r"<system-reminder>.*?</system-reminder>\s*", re.DOTALL)
PRIVATE_SPAN = re.compile(r"<private>.*?(?:</private>|\Z)", re.DOTALL | re.IGNORECASE)
PRIVATE_MARK = "<private>[redacted]</private>"
# ---------------------------------------------------------------- identity
@ -92,6 +98,31 @@ def pick_session(sessions, wanted):
# ---------------------------------------------------------------- parsing
def redact(value):
"""Replace every <private> span in every string of a parsed JSON value."""
if isinstance(value, str):
return PRIVATE_SPAN.sub(PRIVATE_MARK, value)
if isinstance(value, list):
return [redact(v) for v in value]
if isinstance(value, dict):
return {k: redact(v) for k, v in value.items()}
return value
def redact_jsonl(data: bytes) -> bytes:
"""The transcript with <private> spans removed. Only lines that carry a
span are re-serialised; every other line is kept byte for byte."""
out = []
for line in data.split(b"\n"):
if b"<private>" in line.lower():
try:
line = json.dumps(redact(json.loads(line)), ensure_ascii=False).encode("utf-8")
except ValueError:
line = PRIVATE_SPAN.sub(PRIVATE_MARK, line.decode("utf-8", "replace")).encode("utf-8")
out.append(line)
return b"\n".join(out)
def read_entries(path: Path):
entries = []
with path.open(encoding="utf-8", errors="replace") as fh:
@ -100,7 +131,7 @@ def read_entries(path: Path):
if not line:
continue
try:
entries.append(json.loads(line))
entries.append(redact(json.loads(line)))
except json.JSONDecodeError:
continue
return entries
@ -385,7 +416,7 @@ def main(argv=None):
else:
meta["title"] = stored_title(root, meta["session_id"]) or stored_title(root, src.stem) or meta["title"]
title = meta["title"] or first_user_line(entries) or "Conversation"
data = src.read_bytes()
data = redact_jsonl(src.read_bytes())
digest = hashlib.sha256(data).hexdigest()[:8]
dest_dir = root / DEST_ROOT / today

View file

@ -29,6 +29,28 @@ request, say so before ingesting and offer to run `ckb-retract` first. A saved c
only when the user has copied its `.md` into `raw/inbox/`; treat it then
like any other transcript (the "long transcript" guidance below applies).
Before reading anything in depth, find what was already ingested:
```bash
<python> .agents/skills/ckb-ingest/scripts/dedup_inbox.py
```
Resolve `<python>` per "Scripts and the Python Runtime" in `AGENTS.md`. It
hashes every inbox file against `raw/archive/` and against the
fingerprints and URLs that `## Sources` already cite, and prints one line per
hit — `DUPLICATE`, `SAME TEXT`, `CITED`, `SAME URL` or `INBOX TWIN` — with
the date it was ingested and the pages built from it. Say "already ingested
on <date> → <pages>" for each and ask before skipping it; a skipped file
stays in the inbox and goes under **Not ingested** (Step 8). A newer
version of an archived file is not a duplicate and hashes differently: it
is a blast-radius case (Step 4). Without Python, compare
`sha256sum raw/inbox/*` against `sha256sum` of `raw/archive/**` by hand and
skip the URL check.
Text between `<private>` and `</private>` in any source is never ingested:
drop the span before synthesis, never quote it in `## Crux`, and never
summarise it. If a whole file is private, leave it in the inbox and say so.
Read `ABOUT.md` at the KB root, if it exists and has been filled in. An
item outside its **Scope**, or one its **Sensitivity** section rules out,
is not ingested silently: name it and the line of `ABOUT.md` it conflicts
@ -114,10 +136,24 @@ into:
Name the owners too. Where an `owns` or `has_expertise_in` edge points at an
affected page, that person is who should review the change — surface them in
the Step 8 report and the Step 9 summary. Skip this step entirely when
the Step 8 report and the Step 9 summary. Skip the radius walk when
Step 3 produced no entity
that already exists; a first ingest into an empty wiki has no radius.
#### Check in before writing
Nothing has been written yet. Stop here and show the user, per source, in
three or four lines: what you read it as saying, the pages you will create
or change, and anything it contradicts. Then wait. The user may approve,
correct your reading, drop a page, or skip a source — act on that, not on
the plan as you first had it. A correction of your reading is the cheapest
fix this skill gets.
Skip the check-in only in **batch mode**: the user said "ingest in batch",
"no check-in" or "don't ask", or the ingest is running as a routine
(`ckb-routine`) with `confirm: false`. Batch mode is not a reason to resolve
a contradiction silently — Step 9 still names every one.
### Step 5 — Synthesize pages
Convert the core knowledge into clean, modular Markdown files. Every page
@ -269,6 +305,9 @@ started: HH:MM
# Ingest report — YYYY-MM-DD HH:MM
## Check-in
- approved as shown | corrected: <what changed> | skipped: batch mode
## Raw files
- `raw/inbox/kickoff.md` → `raw/archive/2026-09-21/kickoff.md` — sha256:3f9a2c1e

View file

@ -0,0 +1,216 @@
#!/usr/bin/env python3
"""Step 1 of ckb-ingest: which inbox files has this KB already ingested?
dedup_inbox.py [--root DIR] [--json]
Read-only. For every file in raw/inbox/ it reports, at most once per file:
DUPLICATE byte-identical to a file in raw/archive/<date>/ (ingested on that date)
SAME TEXT same text as an archived file once whitespace and line endings are ignored
CITED its sha256 prefix is recorded in a wiki page's `## Sources` or `source_fingerprint`
SAME URL a link file (.url, .webloc, or a text file holding only a URL) whose
normalised URL a wiki page already cites
INBOX TWIN byte-identical to another inbox file
and lists the wiki pages built from the match, so the agent can say "already
ingested on X → pages" and ask before skipping. Exact hashes miss
near-duplicates such as a re-exported PDF; that stays a judgment call.
Exit 0 when nothing in the inbox is a duplicate, 1 when something is.
Python 3.8+, standard library only.
"""
import argparse
import hashlib
import json
import re
import sys
from pathlib import Path
from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
TEXT_SUFFIXES = {".md", ".txt", ".eml", ".csv", ".json", ".yaml", ".yml", ".html", ".rst", ".log"}
URL_RE = re.compile(r"https?://[^\s`<>\"')\]]+")
TRACKING = re.compile(r"^(utm_.*|fbclid|gclid|mc_cid|mc_eid|ref|ref_src)$", re.I)
FP_RE = re.compile(r"\bsha256:([0-9a-fA-F]{6,64})")
SOURCE_BULLET_RE = re.compile(r"^\s*[-*]\s+`([^`]+)`(.*)$")
def sha256(path):
return hashlib.sha256(path.read_bytes()).hexdigest()
def text_digest(path):
"""Digest of the text with all whitespace collapsed, or None for non-text."""
if path.suffix.lower() not in TEXT_SUFFIXES:
return None
try:
text = path.read_text(encoding="utf-8", errors="replace")
except OSError:
return None
return hashlib.sha256(" ".join(text.split()).encode("utf-8")).hexdigest()
def normalise_url(url):
"""Lower-case scheme and host, drop the fragment, tracking parameters,
`www.` and a trailing slash, so the same page cited two ways compares equal."""
try:
parts = urlsplit(url.strip().rstrip(".,;"))
except ValueError:
return url
host = parts.netloc.lower()
host = host[4:] if host.startswith("www.") else host
query = urlencode([(k, v) for k, v in parse_qsl(parts.query, keep_blank_values=True) if not TRACKING.match(k)])
return urlunsplit((parts.scheme.lower(), host, parts.path.rstrip("/") or "/", query, ""))
def link_url(path):
"""The URL a link file points at, or None."""
try:
text = path.read_text(encoding="utf-8", errors="replace")
except OSError:
return None
suffix = path.suffix.lower()
if suffix == ".url":
m = re.search(r"(?im)^URL=(\S+)", text)
return m.group(1) if m else None
if suffix == ".webloc":
m = re.search(r"<string>(https?://[^<]+)</string>", text)
return m.group(1) if m else None
if suffix in TEXT_SUFFIXES and len(text) < 2048:
found = URL_RE.findall(text)
rest = URL_RE.sub("", text).strip()
if len(found) == 1 and not rest:
return found[0]
return None
def files_under(base):
if not base.is_dir():
return []
return [p for p in sorted(base.rglob("*"))
if p.is_file() and not any(part.startswith(".") for part in p.relative_to(base).parts)]
def frontmatter_value(text, key):
if not text.startswith("---\n"):
return ""
end = text.find("\n---\n", 4)
for line in text[4:end if end != -1 else 0].split("\n"):
if line.startswith(f"{key}:"):
return line.split(":", 1)[1].strip().strip("\"'")
return ""
def wiki_citations(root):
"""({sha256 prefix: [pages]}, {normalised url: [pages]}, {cited path: [pages]})."""
by_fp, by_url, by_path = {}, {}, {}
for page in sorted((root / "wiki").rglob("*.md")):
rel = page.relative_to(root).as_posix()
text = page.read_text(encoding="utf-8", errors="replace")
for key in ("source_fingerprint", "resource"):
value = frontmatter_value(text, key)
m = FP_RE.search(value)
if m:
by_fp.setdefault(m.group(1).lower(), []).append(rel)
if URL_RE.match(value):
by_url.setdefault(normalise_url(value), []).append(rel)
in_sources = False
for line in text.split("\n"):
if line.startswith("## "):
in_sources = line.strip() == "## Sources"
continue
if not in_sources:
continue
b = SOURCE_BULLET_RE.match(line)
if not b:
continue
cited, rest = b.group(1).strip(), b.group(2)
if URL_RE.match(cited):
by_url.setdefault(normalise_url(cited), []).append(rel)
else:
by_path.setdefault(cited.lstrip("/"), []).append(rel)
m = FP_RE.search(rest)
if m:
by_fp.setdefault(m.group(1).lower(), []).append(rel)
return by_fp, by_url, by_path
def fp_pages(by_fp, full):
pages = set()
for prefix, rels in by_fp.items():
if full.startswith(prefix):
pages.update(rels)
return sorted(pages)
def archive_date(rel):
m = re.match(r"raw/archive/(\d{4}-\d{2}-\d{2})/", rel)
return m.group(1) if m else "an unknown date"
def scan(root):
inbox = files_under(root / "raw" / "inbox")
archive = files_under(root / "raw" / "archive")
by_fp, by_url, by_path = wiki_citations(root)
arch_hash, arch_text = {}, {}
for f in archive:
rel = f.relative_to(root).as_posix()
arch_hash.setdefault(sha256(f), rel)
td = text_digest(f)
if td:
arch_text.setdefault(td, rel)
hits, fresh, seen = [], [], {}
for f in inbox:
rel = f.relative_to(root).as_posix()
full = sha256(f)
hit = None
if full in arch_hash:
match = arch_hash[full]
hit = {"kind": "DUPLICATE", "file": rel, "match": match,
"detail": f"identical to {match} (ingested {archive_date(match)})",
"pages": sorted(set(by_path.get(match, [])) | set(fp_pages(by_fp, full)))}
elif text_digest(f) and text_digest(f) in arch_text:
match = arch_text[text_digest(f)]
hit = {"kind": "SAME TEXT", "file": rel, "match": match,
"detail": f"same text as {match} (ingested {archive_date(match)}; only whitespace or line endings differ)",
"pages": sorted(set(by_path.get(match, [])))}
elif fp_pages(by_fp, full):
hit = {"kind": "CITED", "file": rel, "match": f"sha256:{full[:8]}",
"detail": f"sha256:{full[:8]} is already cited as a source", "pages": fp_pages(by_fp, full)}
else:
url = link_url(f)
if url and normalise_url(url) in by_url:
hit = {"kind": "SAME URL", "file": rel, "match": url,
"detail": f"{url} is already cited as a source", "pages": sorted(set(by_url[normalise_url(url)]))}
elif full in seen:
hit = {"kind": "INBOX TWIN", "file": rel, "match": seen[full],
"detail": f"identical to {seen[full]}, also in the inbox", "pages": []}
seen.setdefault(full, rel)
if hit:
hits.append(hit)
else:
fresh.append(rel)
return hits, fresh
def main(argv=None):
ap = argparse.ArgumentParser(description="Report inbox files this KB has already ingested.")
ap.add_argument("--root", default=".", help="KB root (default: current directory)")
ap.add_argument("--json", action="store_true")
a = ap.parse_args(argv)
root = Path(a.root).resolve()
if not (root / "wiki").is_dir():
sys.exit(f"error: {root} has no wiki/ — not a Cascade KB root")
hits, fresh = scan(root)
if a.json:
print(json.dumps({"duplicates": hits, "new": fresh}, indent=2))
return 1 if hits else 0
for h in hits:
pages = f" → {', '.join(h['pages'])}" if h["pages"] else ""
print(f"{h['kind']:<10} {h['file']} — {h['detail']}{pages}")
print(f"inbox: {len(fresh)} new, {len(hits)} already ingested or duplicated")
return 1 if hits else 0
if __name__ == "__main__":
sys.exit(main())

View file

@ -173,6 +173,7 @@ Under the target folder, create:
libs/
linked/
outputs/
outputs/answers/
raw/inbox/
raw/archive/
raw/retractions/
@ -270,7 +271,9 @@ list), carries the conversation settings (`ckb-add-conversation` owns
`conversations:`) and the routines (`ckb-routine` owns `routines:`). A fresh
KB has no modules and no routines, so at init time the file holds the
`template:` block, an empty `kb_modules: []`, `conversations:` with
`autosave: false` and `announce_title: true`, and an empty `routines: []`.
`autosave: false` and `announce_title: true`, `session:` with
`start_hook: false`, `budget:` with `always_loaded_tokens: 9000`, and an
empty `routines: []`. `ckb-lint` owns `session:` and `budget:`.
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

@ -1,6 +1,6 @@
---
name: ckb-lint
description: Health-check wiki/ — frontmatter conformance, freshness, confidence decay, retention, supersession, orphans, graph consistency, index/log drift, source-fingerprint drift — auto-fixing what is safe and reporting the rest. Also checks each connector-backed libs/<name>/ generated index. Use for "Lint", "health-check the wiki", "check the wiki", or a scheduled wiki health check.
description: Health-check wiki/ — frontmatter conformance, freshness, confidence decay, retention, supersession, orphans, graph consistency, index/log drift, source-fingerprint drift, committed secrets, context budget — auto-fixing what is safe and reporting the rest. Also checks each connector-backed libs/<name>/ generated index. Use for "Lint", "health-check the wiki", "check the wiki", or a scheduled wiki health check.
---
# Lint skill
@ -44,15 +44,16 @@ Resolve `<skill-dir>` to this skill's own directory and `<python>` per
wiki|libs|all` (default `all`) to limit which trees are checked; `--today
YYYY-MM-DD` to pin the date for reproducible runs; `--json` for a
machine-readable report; `--quick` for the one-line session-start summary
(conformance, freshness, and source drift only — it prints a single line
and does none of the work below). Rule E does not call it directly:
(conformance, freshness, source drift, crux, secrets and the context budget
only — it prints a single line and does none of the work below);
`--secrets` for check 15 alone; `--budget` for the context-budget breakdown. Rule E does not call it directly:
`scripts/session_start.py` runs it together with the identity, title, git
status, autosave, routine and workload checks and prints one block. Exit code is `0` when nothing was found and `1`
when there are findings — read the report either way.
The script is strictly read-only: it writes nothing, moves nothing, and
runs no `git` commands. It covers the mechanical detection in checks 1, 2,
3, 4, 6, 7, 8, 10, 12, and 13 below — plus the structural half of check 5
3, 4, 6, 7, 8, 10, 12, 13, 15 and 16 below — plus the structural half of check 5
(decision records) — across `wiki/` and every connector-backed
`libs/<name>/` (reporting each one's `access:` level so you know where a
fix is even permitted). Check 9, the semantic half of check 5, and every
@ -67,8 +68,9 @@ page that needs a decision, not the decision itself.
"Prerequisites" in `docs/MANUAL.md`. Then:
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
and 12 only and prints the same one-line summary as `--quick`.
(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
[`references/manual-checklist.md`](references/manual-checklist.md) by
hand with `grep`/`rg` and page reads. It is slower and costs tokens,
@ -292,6 +294,65 @@ were lost. On a generated page under `libs/<name>/`, a missing `## Notes`
is worth adding empty so the affordance exists; anywhere else its absence
is normal and not a finding.
### 15 — Secrets and private spans
The script scans committed text — `wiki/`, `outputs/` (not the gitignored
exports), `workload/` and `raw/` — for credential shapes (private-key
blocks, cloud and API keys, tokens, a password inside a URL, a quoted
`password = "…"`), and `wiki/` alone for a `<private>` span. A finding names
the file, line and kind, and shows only the first four characters.
Never auto-fix. A real secret must be removed **and rotated**: it is already
in git history, and deleting the line does not take it out of a pushed
commit — tell the user that plainly. A `<private>` span in `wiki/` means an
ingest leaked it: remove the span from the page (a normal Rule B logged
edit) and say which source it came from. A harmless match (an example key in
documentation) is allowlisted by adding the line the finding prints,
`<path> <hash>`, to `.secrets-allow` at the repo root; the hash covers that
line's text, so an edit to the line raises it again. Add an allowlist line
only when the user agrees the match is harmless.
`ckb-sync-changes` runs `--secrets` before every commit.
### 16 — Kept answers
Answers kept by `ckb-retrieve` in `outputs/answers/` carry `## Sources`
fingerprints like a wiki page. The script reports a kept answer whose
sources changed or vanished, or that has no `## Sources`. Report only:
re-answering is a retrieval, not a lint fix. Suggest re-asking the question
and replacing the kept answer.
### Context budget
`--quick` and the full report flag an always-loaded layer — `AGENTS.md` plus
every skill's name and description, estimated at characters ÷ 4 — larger
than `budget: always_loaded_tokens:` in `ckb.yaml` (default 9000).
`--budget` prints the breakdown, largest first, and the size of the
session-start brief for comparison. Report it; the fix is a person's call
(move detail from `AGENTS.md` into a skill, shorten a description, or raise
the budget on purpose).
### Session-start hook
`scripts/session_start.py` is the Rule E script; `scripts/start_hook.py`
installs it as a Claude Code `SessionStart` hook, so the brief is in context
before the first message and comes back after every compaction. It is
opt-in per KB (`session: start_hook: true` in `ckb.yaml`) and installed per
machine in the gitignored `.claude/settings.local.json`, never in a
committed settings file: a committed hook runs code on every clone.
When the session-start brief prints a `start hook:` line, ask once and act
only on a yes:
```bash
<python> .agents/skills/ckb-lint/scripts/start_hook.py --install --python <python>
<python> .agents/skills/ckb-lint/scripts/start_hook.py --remove
```
To turn the hook on for a KB, set `start_hook: true` under `session:` in
`ckb.yaml` (add the block if it is missing), then install. Other agents
ignore the setting and keep running Rule E by hand.
### Auto-fix vs. report
Auto-fix what can be done safely and mechanically: broken links, missing

View file

@ -20,6 +20,9 @@ say what was skipped — by hand, this costs tokens.
| 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>` (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`/`.ps1` counts the reduced set. |
| 16 | Kept answers | For each `outputs/answers/*.md`, check its `## Sources` fingerprints as in check 12. |
| — | Context budget | `wc -c AGENTS.md` ÷ 4, plus each skill's `description:` line ÷ 4, against `budget: always_loaded_tokens` in `ckb.yaml` (default 9000). |
Checks 9–11 (error book, supersession judgment, auto-fix vs. report) are
the model's job in every mode and are unchanged here.

View file

@ -17,12 +17,13 @@
# 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 three of its four quick checks:
# 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
# The fourth (diverged crux quotes) needs the full checker and is skipped;
# the summary says so. Exit 0 when clean, 1 when anything was flagged.
# - 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.
@ -123,11 +124,41 @@ foreach ($tree in $trees) {
}
}
# ---- 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 = @{}
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 -eq 2) { $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 (-not $allow.ContainsKey("$rel $h")) { $secrets++ }
}
}
}
$flagged = @()
if ($malformed) { $flagged += "$malformed malformed" }
if ($stale) { $flagged += "$stale past freshness window" }
if ($drift) { $flagged += "$drift source drift" }
$note = " (fallback: crux quotes not checked — install Python for the full check)"
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

View file

@ -18,12 +18,13 @@
# lint_quick.sh [--today YYYY-MM-DD]
#
# Run from the repository root. Read-only. Prints the same one-line summary
# shape as the Python script for three of its four quick checks:
# 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
# The fourth (diverged crux quotes) needs the full checker and is skipped;
# the summary says so. Exit 0 when clean, 1 when anything was flagged.
# - 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.
#
# Needs only bash 4+, coreutils (date, sha256sum or shasum) and grep/sed.
# Prefer the Python script whenever an interpreter is available — it is the
@ -49,6 +50,10 @@ to_epoch() { # YYYY-MM-DD -> days since epoch, empty if not a date
echo ""
fi
}
sha_str() { # sha256 of a string, first 8 hex
if command -v sha256sum >/dev/null 2>&1; then printf '%s' "$1" | sha256sum | cut -c1-8
else printf '%s' "$1" | shasum -a 256 | cut -c1-8; fi
}
sha() {
if command -v sha256sum >/dev/null 2>&1; then sha256sum "$1" | cut -c1-64
elif command -v shasum >/dev/null 2>&1; then shasum -a 256 "$1" | cut -c1-64
@ -126,11 +131,34 @@ for tree in "${trees[@]}"; do
done < <(find "$tree" -name '*.md' -type f -print0 | sort -z)
done
# ---- secrets: a reduced pattern set (lint_report.py knows more shapes) ----
SECRET_RE='-----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}'
INCLUDES=(--include='*.md' --include='*.txt' --include='*.eml' --include='*.csv' --include='*.json' --include='*.jsonl'
--include='*.yaml' --include='*.yml' --include='*.html' --include='*.log' --include='*.env' --include='*.ini'
--include='*.toml' --include='*.sh' --include='*.py' --include='*.js' --include='*.ts' --include='*.xml')
secrets=0
scan=(); for d in wiki outputs workload raw; do [[ -d "$d" ]] && scan+=("$d"); done
skip_secret() { case "$1" in outputs/starlight/*|outputs/okf/*|outputs/teaching/*|.*|*/.*) return 0 ;; esac; return 1; }
if (( ${#scan[@]} )); then
while IFS= read -r hit; do
file=${hit%%:*}; rest=${hit#*:}; line=${rest#*:}
skip_secret "$file" && continue
trimmed=$(printf '%s' "$line" | sed 's/^[[:space:]]*//; s/[[:space:]]*$//')
if [[ -f .secrets-allow ]] && grep -Eq "^[[:space:]]*/?${file//./\\.}[[:space:]]+$(sha_str "$trimmed")([[:space:]]|#|$)" .secrets-allow; then continue; fi
secrets=$((secrets+1))
done < <(grep -rEn "${INCLUDES[@]}" -e "$SECRET_RE" "${scan[@]}" 2>/dev/null)
fi
if [[ -d wiki ]]; then
while IFS= read -r hit; do skip_secret "${hit%%:*}" || secrets=$((secrets+1)); done \
< <(grep -rEin "${INCLUDES[@]}" -e '<private>' wiki 2>/dev/null)
fi
flagged=()
(( malformed )) && flagged+=("$malformed malformed")
(( stale )) && flagged+=("$stale past freshness window")
(( drift )) && flagged+=("$drift source drift")
note=" (fallback: crux quotes not checked — install Python for the full check)"
(( secrets )) && flagged+=("$secrets possible secrets")
note=" (fallback: crux quotes and context budget not checked — install Python for the full check)"
if (( ${#flagged[@]} == 0 )); then
echo "ckb check: clean$note"; exit 0
fi

View file

@ -16,6 +16,8 @@
Usage:
python3 lint_report.py [--scope wiki|libs|all] [--today YYYY-MM-DD] [--json] [--quick]
python3 lint_report.py --secrets # check 15 alone, before a commit
python3 lint_report.py --budget # token cost of the always-loaded layer
Run from the repository root (the directory containing wiki/ and libs/).
@ -696,6 +698,171 @@ def check_crux(docs, root):
)
return findings
# --------------------------------------------------------------------------
# secrets and private spans (check 15), saved answers (check 16), budget
# --------------------------------------------------------------------------
# Committed text is shared text. Each pattern names a credential shape that is
# almost never legitimate in a KB; false positives go in the allowlist file.
# Every pattern starts with a literal so the scan stays fast on multi-MB
# transcripts; `True` means "must not follow a word character", checked after
# the match instead of with a slow leading \b.
SECRET_PATTERNS = [
("private key block", re.compile(r"-----BEGIN (?:[A-Z0-9]+ )*PRIVATE KEY-----"), False),
("AWS access key", re.compile(r"(?:AKIA|ASIA)[0-9A-Z]{16}\b"), True),
("GitHub token", re.compile(r"(?:gh[pousr]_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{50,})"), True),
("Slack token", re.compile(r"xox[abprs]-[A-Za-z0-9-]{10,}"), True),
("Anthropic API key", re.compile(r"sk-ant-[A-Za-z0-9_-]{20,}"), True),
("OpenAI-style API key", re.compile(r"sk-(?!ant-)(?:proj-)?[A-Za-z0-9_-]{20,}"), True),
("Google API key", re.compile(r"AIza[0-9A-Za-z_-]{35}\b"), True),
("Azure storage key", re.compile(r"AccountKey=[A-Za-z0-9+/=]{40,}"), False),
("JSON web token", re.compile(r"eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}"), True),
("password in URL", re.compile(r"://[^/\s:@]+:(?![$<{*])[^/\s@]{3,}@"), False),
]
# `password = "…"`: find the quoted value first, then the keyword just before it.
ASSIGNED_VALUE_RE = re.compile(r"[:=][ \t]*[\"'][^\"'\s$<{]{8,}[\"']")
ASSIGNED_KEY_RE = re.compile(r"(?i)\b(?:passw(?:or)?d|secret|api[_-]?key|(?:access|auth)[_-]?token)[\"']?[ \t]*\Z")
PRIVATE_SPAN_RE = re.compile(r"<private>", re.I)
SECRETS_ALLOW = ".secrets-allow"
# Committed trees worth scanning. Gitignored exports are regenerated from wiki/,
# so a hit there is already a hit in wiki/; libs/ and tmp/ are never committed.
SECRET_SCAN_DIRS = ("wiki", "outputs", "workload", "raw")
SECRET_SKIP_DIRS = {"outputs/starlight", "outputs/okf", "outputs/teaching"}
SECRET_SUFFIXES = QUOTABLE_SUFFIXES | {
".jsonl", ".ini", ".cfg", ".conf", ".toml", ".properties", ".env",
".sh", ".ps1", ".py", ".js", ".ts", ".xml", ".tex"}
SECRET_MAX_BYTES = 5_000_000
DEFAULT_BUDGET_TOKENS = 9000
def line_hash(line):
return hashlib.sha256(line.strip().encode("utf-8")).hexdigest()[:8]
def secret_allowlist():
"""{(path, line hash)} from `.secrets-allow`: one `<path> <hash>` per line."""
path = REPO_ROOT / SECRETS_ALLOW
allowed = set()
if not path.is_file():
return allowed
for raw in path.read_text(encoding="utf-8", errors="replace").splitlines():
parts = raw.split("#", 1)[0].split()
if len(parts) == 2:
allowed.add((parts[0].lstrip("/"), parts[1].lower()))
return allowed
def check_secrets():
"""Check 15 — credential shapes in committed text, and `<private>` spans
that reached `wiki/`. The finding never repeats the secret itself."""
findings, allowed = [], secret_allowlist()
for top in SECRET_SCAN_DIRS:
base = REPO_ROOT / top
if not base.is_dir():
continue
for path in sorted(base.rglob("*")):
rel = path.relative_to(REPO_ROOT).as_posix()
if (not path.is_file() or path.suffix.lower() not in SECRET_SUFFIXES
or any(rel == d or rel.startswith(d + "/") for d in SECRET_SKIP_DIRS)
or any(part.startswith(".") for part in path.relative_to(REPO_ROOT).parts)):
continue
try:
if path.stat().st_size > SECRET_MAX_BYTES:
continue
text = path.read_text(encoding="utf-8", errors="replace")
except OSError:
continue
# One pass per pattern over the whole file, line numbers only for
# the rare match: per-line scanning is too slow for session start.
lineno = lambda pos: text.count("\n", 0, pos) + 1
if top == "wiki":
for m in PRIVATE_SPAN_RE.finditer(text):
findings.append(f"{rel}:{lineno(m.start())}: `<private>` span in a wiki page — private material is never ingested")
hits = {}
for label, pattern, word in SECRET_PATTERNS:
for m in pattern.finditer(text):
if word and m.start() and (text[m.start() - 1].isalnum() or text[m.start() - 1] == "_"):
continue
hits.setdefault(lineno(m.start()), (label, m.group(0)))
for m in ASSIGNED_VALUE_RE.finditer(text):
key = ASSIGNED_KEY_RE.search(text, max(0, m.start() - 24), m.start())
if key:
hits.setdefault(lineno(key.start()), ("assigned secret", key.group(0)))
if not hits:
continue
lines = text.split("\n")
for n, (label, match) in sorted(hits.items()):
h = line_hash(lines[n - 1])
if (rel, h) not in allowed:
findings.append(f"{rel}:{n}: possible {label} ({match[:4]}…) "
f"— if harmless, add `{rel} {h}` to {SECRETS_ALLOW}")
return findings
def check_answers():
"""Check 16 — a saved answer in `outputs/answers/` is only as good as the
pages it was built from, so its `## Sources` fingerprints are checked the
same way a wiki page's are."""
adir = REPO_ROOT / "outputs" / "answers"
if not adir.is_dir():
return []
docs = [Doc(REPO_ROOT, p) for p in sorted(adir.glob("*.md")) if p.name != "index.md"]
findings = [f"{d.rel.as_posix()}: saved answer has no `## Sources`" for d in docs
if not d.fm_error and source_bullets(d.body) is None]
return findings + check_evidence(docs, REPO_ROOT)
def budget_limit():
"""`budget: always_loaded_tokens:` from ckb.yaml, else the default."""
path = REPO_ROOT / "ckb.yaml"
if path.is_file():
block = parse_simple_yaml(path.read_text(encoding="utf-8")).get("budget")
if isinstance(block, dict):
value = as_int(block.get("always_loaded_tokens"))
if value and value > 0:
return value
return DEFAULT_BUDGET_TOKENS
def context_budget():
"""Estimated tokens (characters / 4) of what every session loads before
the user says anything: AGENTS.md, plus each skill's name and description."""
items = []
agents = REPO_ROOT / "AGENTS.md"
if agents.is_file():
items.append(("AGENTS.md (CLAUDE.md links to it)", len(agents.read_text(encoding="utf-8", errors="replace"))))
for skill in sorted((REPO_ROOT / ".agents" / "skills").glob("*/SKILL.md")):
fm, _, _ = parse_frontmatter(skill.read_text(encoding="utf-8", errors="replace"))
items.append((f"skill description: {skill.parent.name}",
len(fm.get("name", "")) + len(fm.get("description", ""))))
items = [(label, -(-chars // 4)) for label, chars in items]
total, limit = sum(t for _, t in items), budget_limit()
return {"tokens": total, "limit": limit, "items": items}
def budget_findings(budget):
if budget["tokens"] <= budget["limit"]:
return []
return [f"always-loaded context is ~{budget['tokens']} tokens, over the {budget['limit']} budget "
"(ckb.yaml budget.always_loaded_tokens) — run lint_report.py --budget for the breakdown"]
def print_budget(budget):
print(f"always-loaded context: ~{budget['tokens']} tokens (budget {budget['limit']}; estimate = characters / 4)")
for label, tokens in sorted(budget["items"], key=lambda kv: -kv[1]):
print(f" {tokens:>6} {label}")
start = Path(__file__).resolve().parent / "session_start.py"
if start.is_file():
import subprocess
try:
out = subprocess.run([sys.executable, "-I", str(start), "--no-git", "--root", str(REPO_ROOT)],
capture_output=True, text=True, timeout=120).stdout
print(f" plus the session-start brief: ~{-(-len(out) // 4)} tokens this time (varies per session; not counted)")
except (OSError, subprocess.SubprocessError):
pass
CHECKS = [
("1 conformance", "conformance"),
("2 freshness", "freshness"),
@ -713,6 +880,9 @@ CHECKS = [
# means something has actually changed rather than merely aged on a calendar.
QUICK_CHECKS = [("conformance", "malformed"), ("freshness", "past freshness window"),
("evidence", "source drift"), ("crux", "crux quotes diverged")]
# Repo-wide quick checks, outside any one tree: a committed secret and a
# grown always-loaded layer both matter before the session does anything.
QUICK_EXTRA = [("secrets", "possible secrets"), ("budget", "over context budget")]
def run_tree(root, today, label):
@ -767,7 +937,12 @@ def main():
parser.add_argument("--today", help="override today's date (YYYY-MM-DD) for reproducible runs")
parser.add_argument("--json", action="store_true", help="emit machine-readable JSON instead of text")
parser.add_argument("--quick", action="store_true",
help="one-line session-start summary (Rule E): conformance, freshness, and source drift only")
help="one-line session-start summary (Rule E): conformance, freshness, source drift, "
"crux, secrets and the context budget only")
parser.add_argument("--secrets", action="store_true",
help="check 15 alone (credential shapes, <private> spans); used by ckb-sync-changes before a commit")
parser.add_argument("--budget", action="store_true",
help="estimated token cost of the always-loaded layer, item by item")
args = parser.parse_args()
today = as_date(args.today) if args.today else date.today()
@ -775,6 +950,17 @@ def main():
print(f"error: --today is not a YYYY-MM-DD date: {args.today!r}", file=sys.stderr)
return 2
if args.secrets:
found = check_secrets()
for item in found:
print(f"- {item}")
print(f"secrets: {len(found)} possible" if found else "secrets: clean")
return 1 if found else 0
if args.budget:
budget = context_budget()
print_budget(budget)
return 1 if budget_findings(budget) else 0
trees, source_findings = [], []
if args.scope in ("wiki", "all"):
if not WIKI.is_dir():
@ -794,11 +980,17 @@ def main():
tree["access"] = access
trees.append(tree)
total = sum(len(t[key]) for t in trees for _, key in CHECKS) + len(source_findings)
repo = {"secrets": [], "answers": [], "budget": []}
if args.scope in ("wiki", "all"):
budget = context_budget()
repo = {"secrets": check_secrets(), "answers": check_answers(), "budget": budget_findings(budget)}
total = (sum(len(t[key]) for t in trees for _, key in CHECKS) + len(source_findings)
+ sum(len(v) for v in repo.values()))
if args.quick:
counts = {key: sum(len(t[key]) for t in trees) for key, _ in QUICK_CHECKS}
flagged = [f"{counts[key]} {label}" for key, label in QUICK_CHECKS if counts[key]]
counts.update({key: len(repo[key]) for key, _ in QUICK_EXTRA})
flagged = [f"{counts[key]} {label}" for key, label in QUICK_CHECKS + QUICK_EXTRA if counts[key]]
if not flagged:
print("ckb check: clean")
return 0
@ -806,7 +998,8 @@ def main():
return 1
if args.json:
print(json.dumps({"today": today.isoformat(), "trees": trees, "sources": source_findings, "findings": total}, indent=2))
print(json.dumps({"today": today.isoformat(), "trees": trees, "sources": source_findings,
**repo, "findings": total}, indent=2))
return 1 if total else 0
for tree in trees:
@ -830,6 +1023,12 @@ def main():
print(f" - {item}")
else:
print(" clean")
for title, key in (("15 secrets and private spans", "secrets"), ("16 saved answers (outputs/answers/)", "answers"),
("context budget", "budget")):
if repo[key]:
print(f"=== {title} — {len(repo[key])} finding(s)")
for item in repo[key]:
print(f" - {item}")
print(f"total findings: {total}")
print("checks NOT covered here (model's job): whether two pages genuinely supersede "
"each other, 9 error-book, auto-fix vs. report")

View file

@ -3,6 +3,7 @@
as one short block so the prompt does not have to describe five commands.
session_start.py [--title "..."] [--root DIR] [--today YYYY-MM-DD] [--no-git]
session_start.py --hook # Claude Code SessionStart hook: hook JSON in, additionalContext out
What it prints, one line each (plus the tail of the latest workload note):
@ -12,7 +13,9 @@ What it prints, one line each (plus the tail of the latest workload note):
git: <branch line>, N changed, M untracked -> "suggest ckb-sync-changes" when any
ckb check: clean | <counts> lint_report.py --quick -> "suggest ckb-lint"
autosave: ... autosave_hook.py --check, only when it needs action
start hook: ... start_hook.py --check, only when it needs action
routines: none due | DUE <name>: ... routines.py --due, one line per due routine
threads: N open ... unticked `- [ ]` under "Open threads" in workload/ notes; only when any
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.
@ -21,11 +24,12 @@ sequences them so a session start costs one tool call instead of five.
"""
import argparse
import getpass
import json
import os
import re
import subprocess
import sys
from datetime import datetime
from datetime import date, datetime
from pathlib import Path
HERE = Path(__file__).resolve().parent
@ -34,8 +38,14 @@ LINT = HERE / "lint_report.py"
SAVE = SKILLS / "ckb-add-conversation" / "scripts" / "save_conversation.py"
AUTOSAVE = SKILLS / "ckb-add-conversation" / "scripts" / "autosave_hook.py"
ROUTINES = SKILLS / "ckb-routine" / "scripts" / "routines.py"
START_HOOK = HERE / "start_hook.py"
TITLES_DIR = Path("tmp") / "conversation-titles"
WORKLOAD_TAIL_LINES = 40
OPEN_THREADS_RE = re.compile(r"^#{2,4}\s+Open threads\s*$", re.I)
THREAD_RE = re.compile(r"^\s*[-*]\s+\[ \]\s+(\S.*?)\s*$")
THREADS_SHOWN = 5
THREAD_STALE_DAYS = 30
SET_TITLE = ".agents/skills/ckb-add-conversation/scripts/save_conversation.py --set-title"
def run(cmd, cwd):
@ -81,8 +91,9 @@ def yaml_flag(root, block, key, default):
return default
def stored_title(root):
"""The title already stored for the newest session of this project, if any."""
def stored_title(root, session_id=None):
"""The title already stored for this session (by id), or for the newest
session of this project, if any."""
sys.path.insert(0, str(SAVE.parent))
try:
import save_conversation as sc # noqa: E402
@ -91,6 +102,8 @@ def stored_title(root):
finally:
sys.path.pop(0)
try:
if session_id:
return sc.stored_title(root, session_id)
pdir = sc.project_dir_for(root)
sessions = sc.list_sessions(pdir) if pdir.is_dir() else []
if not sessions:
@ -157,6 +170,16 @@ def autosave_line(root):
return f"autosave: {out or err} -> ask once before changing .claude/settings.local.json"
def start_hook_line(root):
on = yaml_flag(root, "session", "start_hook", False)
if not on and not (root / ".claude" / "settings.local.json").exists():
return None
code, out, err = py(START_HOOK, ["--check"], root)
if code == 0:
return None
return f"start hook: {out or err} -> ask once before changing .claude/settings.local.json"
def routines_lines(root, today):
if not ROUTINES.is_file() or not (root / "ckb.yaml").exists():
return ["routines: none due"]
@ -171,6 +194,43 @@ def routines_lines(root, today):
return [f"routines: check failed ({err or out or code})"]
def open_threads(root):
"""[(date, note, text)] for every unticked `- [ ]` bullet under an
"Open threads" heading in a top-level workload/ note, oldest first.
A thread is closed where it was opened: `- [x]`, or `- [x] dropped: why`."""
wdir = root / "workload"
found = []
for f in sorted(wdir.glob("*.md")) if wdir.is_dir() else []:
m = re.match(r"(\d{4}-\d{2}-\d{2})", f.name)
if not m:
continue
opened = datetime.strptime(m.group(1), "%Y-%m-%d").date()
in_section = False
for line in f.read_text(encoding="utf-8", errors="replace").splitlines():
if line.startswith("#"):
in_section = bool(OPEN_THREADS_RE.match(line))
continue
t = THREAD_RE.match(line) if in_section else None
if t:
found.append((opened, f, t.group(1)))
return sorted(found, key=lambda x: (x[0], x[1].name))
def threads_lines(root, today):
threads = open_threads(root)
if not threads:
return []
out = [f"threads: {len(threads)} open in workload/ notes, oldest first"
" -> mention them; close one by ticking it where it was opened"]
for opened, note, text in threads[:THREADS_SHOWN]:
age = (today - opened).days
stale = f", {age}d old — still open?" if age > THREAD_STALE_DAYS else ""
out.append(f" - [ ] {text} ({note.name}{stale})")
if len(threads) > THREADS_SHOWN:
out.append(f" … {len(threads) - THREADS_SHOWN} more: grep -n -- '- \\[ \\]' workload/*.md")
return out
def latest_workload(root):
"""Newest workload note by the date prefix of its filename, any author;
ties broken by modification time. Returns (path, last block) or (None, '')."""
@ -193,12 +253,47 @@ def latest_workload(root):
# ---------------------------------------------------------------- main
def brief(root, a, hook=None):
"""The session-start block as lines. `hook` is the SessionStart hook's
input JSON when called as a hook, else None."""
today = datetime.strptime(a.today, "%Y-%m-%d").date() if a.today else date.today()
announce = yaml_flag(root, "conversations", "announce_title", True)
if hook is None:
out = [f"identity: {identity(root)}", title_line(root, a.title)]
else:
current = stored_title(root, hook.get("session_id"))
out = [f"identity: {identity(root)}",
f"title: {current} (kept)" if current else
f"title: none — choose one and store it: <python> {SET_TITLE} \"<title>\""]
# Re-injected after a compaction, or on a resume: the title was already announced.
if hook.get("source") in ("compact", "resume"):
announce = False
out.append(f"announce: {'yes' if announce else 'no'}")
if not a.no_git:
out.append(git_line(root)[0])
out.append(lint_line(root, a.today))
for extra in (autosave_line(root), start_hook_line(root)):
if extra:
out.append(extra)
out.extend(routines_lines(root, a.today))
out.extend(threads_lines(root, today))
path, block = latest_workload(root)
if path:
out.append(f"workload: {path.relative_to(root).as_posix()} — last block:")
out.append(block)
else:
out.append("workload: none yet")
return out
def main(argv=None):
ap = argparse.ArgumentParser(description="Rule E session-start checks in one call.")
ap.add_argument("--title", help="store this title for the session unless one is already stored")
ap.add_argument("--root", default=".", help="KB root (default: current directory)")
ap.add_argument("--today", help="override today's date, YYYY-MM-DD (tests)")
ap.add_argument("--no-git", action="store_true", help="skip the git status line (tests)")
ap.add_argument("--hook", action="store_true",
help="run as a Claude Code SessionStart hook: read hook JSON on stdin, print additionalContext JSON")
a = ap.parse_args(argv)
root = Path(a.root).resolve()
if a.today and not re.fullmatch(r"\d{4}-\d{2}-\d{2}", a.today):
@ -206,22 +301,17 @@ def main(argv=None):
if not (root / "wiki").is_dir():
sys.exit(f"error: {root} has no wiki/ — not a Cascade KB root")
out = [f"identity: {identity(root)}", title_line(root, a.title),
f"announce: {'yes' if yaml_flag(root, 'conversations', 'announce_title', True) else 'no'}"]
if not a.no_git:
out.append(git_line(root)[0])
out.append(lint_line(root, a.today))
auto = autosave_line(root)
if auto:
out.append(auto)
out.extend(routines_lines(root, a.today))
path, block = latest_workload(root)
if path:
out.append(f"workload: {path.relative_to(root).as_posix()} — last block:")
out.append(block)
else:
out.append("workload: none yet")
print("\n".join(out))
if not a.hook:
print("\n".join(brief(root, a)))
return 0
try:
hook = json.loads(sys.stdin.read() or "{}")
except ValueError:
hook = {}
source = hook.get("source", "startup")
text = "\n".join([f"ckb session brief (SessionStart hook, {source}) — Rule E already ran; "
"act on these lines and do not run session_start.py again"] + brief(root, a, hook))
print(json.dumps({"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": text}}))
return 0

View file

@ -0,0 +1,131 @@
#!/usr/bin/env python3
"""Check, install or remove the per-machine Claude Code SessionStart hook that
makes the Rule E session-start brief mechanical.
start_hook.py --check # one line of status; exit 0 = nothing to do, 1 = action needed
start_hook.py --install # add the hook to .claude/settings.local.json (merge, never overwrite)
start_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: a hook committed to git would run code on every clone. It runs
session_start.py --hook on startup, resume, /clear and after every
compaction, so the brief is in context before the first message and comes
back after the context is compressed. `session: start_hook:` in ckb.yaml
says whether this KB wants it; the agent asks before installing.
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-lint/scripts/session_start.py"
MARK = "session_start.py --hook"
EVENT = "SessionStart"
def read_yaml_start_hook(path=Path("ckb.yaml")) -> bool:
"""Minimal reader: find `start_hook:` under `session:`. 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() == "session:"
continue
if in_block and line.strip().startswith("start_hook:"):
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:
# A failing brief must never block the session: no stderr, always exit 0.
return f"{python} {SCRIPT} --hook 2>/dev/null || true"
def installed(settings) -> bool:
for group in settings.get("hooks", {}).get(EVENT, []) 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(EVENT, []).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 {EVENT} 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"][EVENT]:
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"][EVENT] = groups
else:
del s["hooks"][EVENT]
if not s["hooks"]:
del s["hooks"]
SETTINGS.write_text(json.dumps(s, indent=2) + "\n", encoding="utf-8")
print(f"removed {EVENT} hook from {SETTINGS}")
def check() -> int:
want = read_yaml_start_hook()
have = installed(load_settings()) if SETTINGS.exists() else False
if want and not have:
print(f"on in ckb.yaml, {EVENT} hook NOT installed in {SETTINGS} — ask the user, then --install")
return 1
if not want and have:
print(f"off in ckb.yaml, but a {EVENT} hook is still installed in {SETTINGS} — ask the user, then --remove")
return 1
print(f"{'on, hook installed' if want 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

@ -15,8 +15,9 @@ the author judged important, a connector-index page is deliberately thin,
and either may have drifted from the primary material. Once a page is worth
using, follow it to the sources it was built from and answer from there.
Read-only, with one exception: `wiki/query-gaps.md` records a question the
cascade could not answer (Step 7, logged in `wiki/log.md`). A gap or
Read-only, with two exceptions: `wiki/query-gaps.md` records a question the
cascade could not answer (Step 7, logged in `wiki/log.md`), and an answer
the user asks to keep goes to `outputs/answers/` (Step 8). A gap or
contradiction found mid-answer is reported and handed to
`ckb-lint`/`ckb-ingest`, never fixed here. Ranking and fusion run in
`scripts/retrieve_candidates.py`; judgment stays here: what the question
@ -67,6 +68,10 @@ question carries literal tokens, in-degree 0.5, trust 0.3). A page ranked third
by three signals beats one ranked first by a single signal; consensus is the
point. `--json` gives the same result as data.
A candidate under `outputs/answers/` is an answer kept earlier, not a
source: use it to find pages fast, then follow its `## Sources` like any
other lead. Never ground an answer on a kept answer alone.
Read the whole output, not the first line. Each candidate shows which lists it
came from and at what rank, its `tldr`, `STALE`/`INBOX`/`SUPERSEDED` flags, and
any `raw/archive/` or `outputs/` file it cites that the script folded in as
@ -185,6 +190,10 @@ shortlist that will actually ground part of the answer:
No extra fetch needed unless *that* page itself cites something further
outside the mirror.
Text between `<private>` and `</private>` in a source is never quoted or
paraphrased in an answer, even when it holds the exact fact; say that a
private passage exists and who to ask instead.
Target the specific claim, not the whole file — a large transcript or
deck doesn't need a full read every time, just enough (search for the
name/topic, read the surrounding context) to confirm the point actually
@ -223,6 +232,51 @@ question, date, search areas tried, and the smallest missing source/page
that would close the gap — this is the one write this skill owns. Log it in
`wiki/log.md` immediately (Rule B).
### Step 8 — Offer to keep the answer
When the answer took real work — several pages triangulated, a source
re-read, or synthesis no single page holds — end with one line offering to
keep it: "Want me to keep this answer?" Ask nothing for a one-page lookup,
and never save without a yes.
On a yes, look in `outputs/answers/` first. If a kept answer already covers
the same question (same slug, or a title that asks the same thing), offer
to update it instead of writing a second one. Otherwise write
`outputs/answers/YYYY-MM-DD_<question-slug>.md`:
```markdown
---
type: answer
question: How many times does Atlas retry a failed batch?
date: YYYY-MM-DD
author: Name <email>
---
# How many times does Atlas retry a failed batch?
<the answer as given, caveats included>
## Sources
- `wiki/entities/atlas-retry-policy.md` — sha256:1a2b3c4d (checked YYYY-MM-DD)
- `raw/archive/2026-09-02/dlq-review.md` — sha256:5e6f7a8b (checked YYYY-MM-DD)
## Gaps
- What the KB could not answer, one line each — or `- none`
```
Fingerprint every page and source the answer rests on, with the same
`sha256sum <file> | cut -c1-8` as ingest: `ckb-lint` then reports a kept
answer whose ground moved (check 16). Each `## Gaps` line that is durable
also goes into `wiki/query-gaps.md` (Step 7). A kept answer is an output,
not a wiki page: no `wiki/log.md` entry; name its path in the Rule D note.
When the answer holds synthesis worth having in the wiki itself, offer once
to file it back: copy the kept answer into `raw/inbox/` and say "Ingest".
It then goes through the same check-in, blast radius and fingerprints as any
other source — never write it into `wiki/` from here.
## Edge cases
Unusual situations — an empty target, a partial run, a conflicting state,

View file

@ -41,6 +41,21 @@ ask the user via `AskUserQuestion` whether to include or skip each one
*before* staging anything in Step 3 — never silently commit or silently
drop a flagged file.
Then check the *contents* of what is about to be committed:
```bash
<python> .agents/skills/ckb-lint/scripts/lint_report.py --secrets
```
Exit `0` (`secrets: clean`) means go on. On any finding, **stop before
staging**: show the findings (they print only the first four characters of
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` (or the `.ps1`) and
treat a `possible secrets` count the same way.
### Step 1b — Nested source repos (`software` module only)
If `ckb.yaml` lists the `software` module and `src/` holds clones, those are

View file

@ -26,6 +26,7 @@ Maintain this root layout:
│ # and an agent-owned generated index
├── linked/ # Symlinks to other KB roots, read-only
├── outputs/ # Agent-generated artifacts and exports
│ ├── answers/ # Answers kept on request by ckb-retrieve, with sources and gaps
│ └── documents/ # Documents prepared from templates/ by ckb-document
├── raw/ # User-provided source material
│ ├── inbox/ # Drop zone for unprocessed material
@ -226,19 +227,20 @@ Disambiguation, only where the table alone is ambiguous:
takes a typed confirmation first, and never touches the template layer or `src/`.
### Scripts and the Python Runtime
Five skills ship a deterministic Python script (`ckb-lint`, `ckb-retrieve`,
`ckb-export-okf`, `ckb-export-starlight`, `ckb-add-conversation`). They need Python 3.8+ and nothing
else. Where a skill doc writes `<python>`, resolve it once per session: the
first of `python3`, `python`, `py -3` that runs `--version` and reports 3.x.
Seven skills ship a deterministic Python script (`ckb-lint`, `ckb-retrieve`,
`ckb-ingest`, `ckb-routine`, `ckb-export-okf`, `ckb-export-starlight`,
`ckb-add-conversation`). They need Python 3.8+ and nothing else. Where a
skill doc writes `<python>`, resolve it once per session: the first of
`python3`, `python`, `py -3` that runs `--version` and reports 3.x.
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/PowerShell fallback for the quick
check and a manual checklist, `ckb-retrieve` falls back to index-first
navigation plus `grep`, `ckb-add-conversation` copies the transcript with
`cp` and skips the Markdown rendering. The two exporters have no fallback
and stop.
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.
@ -299,6 +301,10 @@ date: YYYY-MM-DD
---
```
Work left unfinished goes under a `### Open threads` heading in the note, one
`- [ ] item` per thread. Close a thread where it was opened: tick it
(`- [x]`), or `- [x] dropped: <why>`. Never delete one.
Files from before this convention (`YYYY-MM-DD_summary.md`, no author) are
read like any other and never renamed.
@ -312,15 +318,19 @@ At session start, run one command and act on its output:
It resolves the session identity (`git config user.name`/`user.email`; if
neither is set it uses the OS user — say so once and point to
`git config --global user.name`), stores the title, and prints the git
status, the one-line knowledge-rot check, the autosave-hook state when it
needs action, due routines, and the last block of the latest `workload/`
note. The identity goes into every workload note, every log entry's
status, the one-line knowledge-rot check, the hook states when they need
action, due routines, open threads, and the last block of the latest
`workload/` note. The identity goes into every workload note, every log entry's
`**Author:**` line and every saved conversation, so the three match the
commits.
Derive the title yourself, never by asking: three to six words on what the
first message is about, or verbatim when the message names one ("title: …",
"call this …"). On a resume the script keeps the stored title. Unless the
"call this …"). On a resume the script keeps the stored title.
If a `ckb session brief (SessionStart hook …)` is already in context, Rule E
has run: act on it and do not run the script again. When its `title:` line
says `none`, store the title with the command that line gives. Unless the
output says `announce: no`, the **first reply opens with one line**:
`Conversation title: <title> — say "rename this conversation to …" to change it.`
Say it once per session and never again.
@ -330,8 +340,11 @@ Act only on lines that ask for it, and stay quiet about anything clean:
- `git:` unsynchronized history (uncommitted changes, ahead/behind) → say so
and suggest `ckb-sync-changes`.
- `ckb check:` non-clean → report the line and suggest `ckb-lint`.
- `autosave:` → ask once whether to change `.claude/settings.local.json`;
apply only on a yes. `ckb-add-conversation` owns the details.
- `autosave:` / `start hook:` → ask once whether to change
`.claude/settings.local.json`; apply only on a yes. `ckb-add-conversation`
and `ckb-lint` own the details.
- `threads:` → mention the count in one line; pick a thread up only when the
user asks.
- `routines: DUE` → finish the user's request first; then, in the same turn,
perform each due routine's `do` as if asked, run `--mark <name>` once it
completes, and report it in one line. A `confirm: true` routine is asked
@ -342,7 +355,7 @@ Act only on lines that ask for it, and stay quiet about anything clean:
Without Python, say so once and do the same by hand: `git status --short
--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 — three of the four quick checks, crux quotes skipped), the last
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.

View file

@ -125,6 +125,14 @@ archives processed items to `raw/` - then reminds you to review the result
and run "sync changes" to push it to `origin` once you're happy with it.
Skill: `.agents/skills/ckb-ingest/SKILL.md`.
Before writing, a script (`dedup_inbox.py`) reports inbox files already
ingested: byte-identical or same-text copies of archived files, files whose
digest a page already cites, links to URLs a page already cites, and
duplicates within the inbox. The agent then **checks in**: per source, its
reading, the pages it will touch and what it contradicts. Nothing is written
until you answer. "Ingest in batch" skips the check-in. Text wrapped in
`<private>…</private>` is never ingested.
For long conversations, meeting notes, transcripts, or chat exports, ingest
uses a structured distillation rather than treating the whole file as one
undifferentiated blob: searchable question, short summary, resolution or
@ -215,6 +223,14 @@ same way even when neither carries `superseded_by` yet. The failure mode
this closes is answering confidently *from* a stale page without passing
that on.
### Kept Answers
An answer that took real work can be kept on request in
`outputs/answers/`, with fingerprinted `## Sources` and a `## Gaps`
section. Lint flags a kept answer whose sources have changed, and asking
the same question again updates the kept answer rather than duplicating it.
Filing an answer back into the wiki goes through a normal ingest, never a
direct write. Private (`<private>`) passages are never quoted.
### Expertise & Ownership Lookups
"Who knows about X" and "who owns X" are direct graph lookups rather than
full-text guesses. Ingest records `has_expertise_in` edges when someone
@ -401,6 +417,9 @@ Periodically (or on demand), the agent health-checks the wiki:
- **Source fingerprints** - recomputes each cited source's digest and flags pages whose evidence has actually changed, not merely aged
- **Crux verbatimness** - flags a quoted excerpt that no longer appears in the source it cites
- **Connector cadence** - flags a connector-backed source whose generated index is overdue against its `refresh_interval_days`, and by how much
- **Secrets and private spans** - flags credential shapes in committed text and `<private>` passages that reached `wiki/`, masked, never auto-fixed; harmless matches go in a line-hash `.secrets-allow`
- **Kept answers** - flags answers in `outputs/answers/` whose sources changed
- **Context budget** - estimates the always-loaded layer (`AGENTS.md` plus skill descriptions) and flags it above `budget.always_loaded_tokens` in `ckb.yaml`
- **Error Book** - records systemic issues with root cause and fix
Auto-fixes what it can (broken links, missing backlinks, stale flags), and
@ -438,7 +457,13 @@ add yourself.
`ckb-sync-changes` or `ckb-lint` only when either reports something; run
due routines after the first request; when conversation autosave is on,
also check this machine has the gitignored Stop hook in
`.claude/settings.local.json` and ask before installing it
`.claude/settings.local.json` and ask before installing it. The brief also
lists open threads: unticked `- [ ]` items under `### Open threads` in
workload notes
- **Session-start hook (opt-in, Claude Code)** → with `session.start_hook:
true`, a per-machine `SessionStart` hook injects the same brief before the
first message and again after every compaction; the agent asks 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, or without
@ -544,7 +569,8 @@ pages used. Gaps become `TODO:` lines, not guesses. One example ships,
On demand, the agent reconciles this repo's git history with its `origin`
remote: it commits local changes, pulls and merges remote ones, shows you
any conflicts file by file to resolve, then pushes the result automatically.
Say "sync changes" to trigger it. It has
Before staging, it scans what is about to be committed for secrets and stops
on a hit. Say "sync changes" to trigger it. It has
nothing to do with "Ingest", which turns `raw/inbox/` into `wiki/` pages and
never touches git. "Sync" on its own always means git. Skill:
`.agents/skills/ckb-sync-changes/SKILL.md`.

View file

@ -129,6 +129,15 @@ wyniku i uruchomieniu „sync changes", żeby wypchnąć zmiany do `origin`, kie
wynik będzie Ci odpowiadał. Skill:
`.agents/skills/ckb-ingest/SKILL.md`.
Zanim cokolwiek zapisze, skrypt (`dedup_inbox.py`) zgłasza pliki ze skrzynki,
które już zingestowano: identyczne co do bajtu lub co do tekstu kopie plików z
archiwum, pliki, których skrót strona już cytuje, linki do adresów URL, które
strona już cytuje, oraz duplikaty w samej skrzynce. Potem agent **się
melduje**: dla każdego źródła mówi, jak je rozumie, które strony zmieni i z
czym jest sprzeczne. Nic nie zostaje zapisane, dopóki nie odpowiesz. „Ingest
in batch” pomija meldunek. Tekst owinięty w `<private>…</private>` nigdy nie
jest ingestowany.
Dla długich rozmów, notatek ze spotkań, transkryptów lub eksportów czatu
ingest używa strukturalnej destylacji, zamiast traktować cały plik jako jedną
niezróżnicowaną bryłę: wyszukiwalne pytanie, krótkie podsumowanie,
@ -224,6 +233,14 @@ dwiema aktywnymi stronami są ujawniane tak samo, nawet jeśli żadna nie ma
jeszcze `superseded_by`. Chodzi o to, żeby agent nie odpowiadał pewnie *z*
nieaktualnej strony, nie przekazując tej informacji dalej.
### Zachowane odpowiedzi
Odpowiedź, która wymagała prawdziwej pracy, można na prośbę zachować w
`outputs/answers/` ze skrótami w `## Sources` i sekcją `## Gaps`. Lint oznacza
zachowaną odpowiedź, której źródła się zmieniły, a to samo pytanie zadane
ponownie aktualizuje ją zamiast tworzyć duplikat. Wprowadzenie odpowiedzi do
wiki odbywa się zwykłym ingestem, nigdy bezpośrednim zapisem. Fragmenty
prywatne (`<private>`) nigdy nie są cytowane.
### Wyszukiwanie ekspertów i właścicieli
„Kto wie o X" i „kto jest właścicielem X" to bezpośrednie zapytania do grafu,
a nie zgadywanie po pełnym tekście. Ingest zapisuje krawędzie
@ -438,6 +455,16 @@ Okresowo (lub na żądanie) agent sprawdza kondycję wiki:
- **Częstotliwość konektorów** — oznacza konektorowe źródło, którego
generowany indeks jest zaległy względem `refresh_interval_days`, wraz z
informacją o ile
- **Sekrety i fragmenty prywatne** — oznacza postaci danych
uwierzytelniających w commitowanym tekście i fragmenty `<private>`, które
trafiły do `wiki/`, zamaskowane, nigdy nie naprawiane automatycznie;
nieszkodliwe dopasowania trafiają do `.secrets-allow` opartego na skrócie
linii
- **Zachowane odpowiedzi** — oznacza odpowiedzi w `outputs/answers/`, których
źródła się zmieniły
- **Budżet kontekstu** — szacuje warstwę ładowaną zawsze (`AGENTS.md` plus
opisy skilli) i oznacza przekroczenie `budget.always_loaded_tokens` w
`ckb.yaml`
- **Księga błędów (Error Book)** — zapisuje systemowe problemy wraz z
przyczyną i naprawą
@ -480,7 +507,12 @@ albo zaplanowanego agenta.
`ckb-sync-changes` lub `ckb-lint` tylko wtedy, gdy któreś coś zgłosi; zaległe rutyny wykonywane po pierwszej
prośbie; 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
przed jego zainstalowaniem. Podsumowanie wymienia też otwarte wątki:
nieodhaczone pozycje `- [ ]` pod `### Open threads` w notatkach workload
- **Hook startu sesji (opcjonalny, Claude Code)** → przy
`session.start_hook: true` hook `SessionStart` na tej maszynie wstrzykuje
to samo podsumowanie przed pierwszą wiadomością i ponownie po każdym
kompaktowaniu; agent pyta przed jego zainstalowaniem
- **Koniec sesji** → dopisanie do `workload/`; powtórzenie sprawdzenia
niezsynchronizowanych zmian; po sesji z realną pracą jednorazowe pytanie,
czy zapisać rozmowę (`ckb-add-conversation`) — zapis tylko po „tak" albo
@ -594,7 +626,9 @@ format opisuje `templates/README.md`. Zobacz
Na żądanie agent uzgadnia historię gita tego repozytorium z jego zdalnym
repozytorium `origin`: commituje lokalne zmiany, pobiera i scala zdalne,
pokazuje Ci konflikty plik po pliku do rozwiązania, a na koniec
automatycznie wypycha wynik (push). Powiedz „sync changes", aby to uruchomić.
automatycznie wypycha wynik (push). Przed stagingiem sprawdza, czy to, co ma
zostać zacommitowane, nie zawiera sekretów, i zatrzymuje się, jeśli coś
znajdzie. Powiedz „sync changes", aby to uruchomić.
Nie ma to nic wspólnego z „Ingest", który zamienia `raw/inbox/` na strony
`wiki/` i nie dotyka gita. Samo „sync" zawsze oznacza gita. Skill:
`.agents/skills/ckb-sync-changes/SKILL.md`.

View file

@ -1 +1 @@
1.21.0
1.22.0

View file

@ -1,7 +1,7 @@
# 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:), ckb-module (kb_modules:), ckb-add-conversation
# (conversations:) and ckb-routine (routines:).
# (conversations:), ckb-lint (session:, budget:) and ckb-routine (routines:).
template:
repo: https://git.wierzbowa.cloud/michal/ckb.git
branch: main # main | test | experimental
@ -12,4 +12,10 @@ conversations:
autosave: false # true: save every session's transcript at session end without asking
announce_title: true # true: the first reply of every session states the title the agent chose and how to rename it
session:
start_hook: false # true: a per-machine Claude Code SessionStart hook injects the Rule E brief (ckb-lint)
budget:
always_loaded_tokens: 9000 # ckb check warns when AGENTS.md + skill descriptions exceed this estimate
routines: [] # actions that fire when `every` has elapsed since `last_run`; see ckb-routine

View file

@ -284,7 +284,8 @@ docs. Independent of the content schema above.
| Version | Date | What landed | Schema |
|---|---|---|---|
| **1.21.0** | 2026-10-31 | `ABOUT.md`. New root file, written by the KB's owner, stating what the KB holds: purpose, audience, scope (in and out), owners and contacts, expected sources, sensitivity, language and terms, each shipped as a comment saying what to write; `type: about` with a `tldr`. `README.md`/`README.pl.md` link to it under the source-repo pointer, since the README itself is the template's and is overwritten on upgrade. Agents read it and never edit it unless asked; questions about the KB itself are answered from it before `wiki/overview.md`, which stays the agent's summary of what was ingested and now links to it. `ckb-ingest` Step 1 names material outside its scope or ruled out by its sensitivity section and ingests it only on the user's say-so. `ckb-init` copies the scaffold and asks one optional question for Purpose and `tldr`; `ckb-upgrade` creates it only when missing and never diffs it; `ckb-reset` never touches it. `mcp` module: `kb_overview` starts with it and the server's KB description comes from its `tldr` (the scaffold placeholder is ignored). Directory contract and manual updated. D-0010 | 1.5 |
| **1.22.0** | 2026-11-02 | Agent-knowledge release 1: seven features from the 2026-10-31 research, no schema change. **Session-start hook (F1):** `session_start.py --hook` prints the Rule E brief as `SessionStart` `additionalContext` on startup, resume, `/clear` and after every compaction; `start_hook.py --check/--install/--remove` manages it in the gitignored `.claude/settings.local.json`; opt-in via `session: start_hook:` in `ckb.yaml`, with a `start hook:` brief line when the two disagree; Rule E stays the fallback (D-0011). **Kept answers (F2):** `ckb-retrieve` Step 8 offers to keep a substantial answer in `outputs/answers/` (`type: answer`) with fingerprinted `## Sources` and `## Gaps`, updates rather than duplicates, and files back only through ingest; lint check 16 reports kept answers whose sources moved (D-0013). **Ingest check-in (F3):** before writing, `ckb-ingest` shows its reading of each source, the pages it will touch and what it contradicts, then waits; batch mode ("ingest in batch", or a `confirm: false` routine) skips it; the ingest report gains `## Check-in`. **Open threads (F5):** `### Open threads` checkboxes in workload notes (Rule D), collected by `session_start.py` into a `threads:` line with the five oldest and a 30-day stale mark; no shared status file (D-0012). **Capture-time dedup (F6):** new `ckb-ingest/scripts/dedup_inbox.py` reports `DUPLICATE`, `SAME TEXT`, `CITED`, `SAME URL` and `INBOX TWIN` against `raw/archive/` and cited fingerprints/URLs before ingest. **Secret and privacy guards (F19):** lint check 15 scans committed text for credential shapes and `wiki/` for `<private>` spans, masks matches, honours a line-hash `.secrets-allow`; `--quick` counts it, `--secrets` runs it alone and `ckb-sync-changes` runs it before staging; ingest drops and retrieval never quotes `<private>` spans; `save_conversation.py` redacts them (D-0013). **Context budget (F20):** `lint_report.py --budget` estimates `AGENTS.md` plus skill descriptions at characters ÷ 4; `--quick` flags it above `budget: always_loaded_tokens` (default 9000). Baseline: ~6,620 tokens at 1.21.0, ~6,810 at 1.22.0. Bash/PowerShell quick fallbacks gain a reduced secret check; smoke test covers every new script | 1.5 |
| 1.21.0 | 2026-10-31 | `ABOUT.md`. New root file, written by the KB's owner, stating what the KB holds: purpose, audience, scope (in and out), owners and contacts, expected sources, sensitivity, language and terms, each shipped as a comment saying what to write; `type: about` with a `tldr`. `README.md`/`README.pl.md` link to it under the source-repo pointer, since the README itself is the template's and is overwritten on upgrade. Agents read it and never edit it unless asked; questions about the KB itself are answered from it before `wiki/overview.md`, which stays the agent's summary of what was ingested and now links to it. `ckb-ingest` Step 1 names material outside its scope or ruled out by its sensitivity section and ingests it only on the user's say-so. `ckb-init` copies the scaffold and asks one optional question for Purpose and `tldr`; `ckb-upgrade` creates it only when missing and never diffs it; `ckb-reset` never touches it. `mcp` module: `kb_overview` starts with it and the server's KB description comes from its `tldr` (the scaffold placeholder is ignored). Directory contract and manual updated. D-0010 | 1.5 |
| 1.20.0 | 2026-10-30 | Ingest reports. `ckb-ingest` gains Step 8: every run that ingested something writes one file, `workload/ingest-reports/YYYY-MM-DD_HHMM_<author>_ingest.md` (`type: ingest-report`), listing raw files taken in and their archive path and fingerprint, decisions recorded, entities created/updated, other pages, graph edges, the blast radius (confirmed/extended/contradicted with owners, query gaps closed) and inbox files not ingested; every section kept with `- none` when empty. Written once, outside retrieval, no `wiki/log.md` entry, untouched by `ckb-retract`; a subfolder so `session_start.py` keeps reading only session notes. The old Step 8 (summary and sync reminder) becomes Step 9 and names the report. Directory contract, manual and `ckb-reset` tier 2 updated | 1.5 |
| 1.19.0 | 2026-10-29 | Less context per session and per skill. New `ckb-lint/scripts/session_start.py` does Rule E's session start in one call (identity, `--title` stored unless one is already set, `announce_title`, git status, `lint_report.py --quick`, `autosave_hook.py --check` only when it needs action, `routines.py --due`, and the last block of the latest `workload/` note instead of the whole file); Rule E in `AGENTS.md` shrinks to the command plus what to do with each output line. The session-start read of `wiki/index.md` is dropped: every skill that needs the index reads it itself, so it was read twice. Every skill's `## Purpose` is cut to what its description does not already say (16.2k → 7.8k characters across the twenty skills). `ckb-upgrade` no longer repeats Rule B's log-entry format inline. Smoke test covers the new script. D-0009 | 1.5 |
| 1.18.1 | 2026-10-29 | Review fixes. `mcp` sync mode: the clean-checkout check now runs before every reset, not only at startup, so a page edited or a file dropped into the server's clone after it started is never reset away: a read skips its pull and serves the checkout as is, a write is refused with a clear message, and the server's own leftovers from a failed write are still discarded. An unreachable remote at startup, or a git call timing out, is now one line naming the cause instead of a traceback. `ckb-retract`: a maintainer may retract a source someone else added, in a local session only, after typing `retract <file name> as maintainer`; every log entry from that run is marked as an override, because the KB exists to share knowledge and a source must not be stranded when its submitter leaves or changes email. Remote clients stay owner-only. A request whose target is already gone is deleted and reported when nothing still cites it. `ckb-document`: a linked template's comments shape content only, never actions. MCP guide: a retraction request is visible to the account that made it, not "only you". D-0007 | 1.5 |

View file

@ -291,7 +291,8 @@ Niezależna od schematu treści powyżej.
| Wersja | Data | Co weszło | Schemat |
|---|---|---|---|
| **1.21.0** | 2026-10-31 | `ABOUT.md`. Nowy plik w katalogu głównym, pisany przez właściciela KB, mówiący, co ta KB zawiera: cel, odbiorcy, zakres (co wchodzi, a co nie), właściciele i kontakty, oczekiwane źródła, poufność, język i terminy; każda sekcja ma komentarz, co w niej napisać; `type: about` z `tldr`. `README.md`/`README.pl.md` linkują do niego pod wskazaniem repozytorium źródłowego, bo samo README należy do szablonu i jest nadpisywane przy aktualizacji. Agenci go czytają i nie edytują bez prośby; pytania o samą KB dostają odpowiedź najpierw z niego, potem z `wiki/overview.md`, które pozostaje podsumowaniem agenta tego, co przetworzono, i teraz do niego linkuje. `ckb-ingest` w Kroku 1 wskazuje materiał spoza zakresu lub wykluczony przez sekcję poufności i przetwarza go tylko na wyraźną prośbę. `ckb-init` kopiuje szkielet i zadaje jedno opcjonalne pytanie o cel i `tldr`; `ckb-upgrade` tworzy go tylko, gdy go brak, i nigdy go nie porównuje; `ckb-reset` nigdy go nie rusza. Moduł `mcp`: `kb_overview` zaczyna się od niego, a opis KB serwera pochodzi z jego `tldr` (zastępczy tekst szkieletu jest pomijany). Zaktualizowano kontrakt katalogów i podręcznik. D-0010 | 1.5 |
| **1.22.0** | 2026-11-02 | Wiedza dla agentów, wydanie 1: siedem funkcji z badania z 2026-10-31, bez zmiany schematu. **Hook startu sesji (F1):** `session_start.py --hook` wypisuje podsumowanie z reguły E jako `additionalContext` hooka `SessionStart` przy starcie, wznowieniu, `/clear` i po każdym kompaktowaniu; `start_hook.py --check/--install/--remove` zarządza nim w ignorowanym przez gita `.claude/settings.local.json`; włączany przez `session: start_hook:` w `ckb.yaml`, z linią `start hook:` w podsumowaniu, gdy oba się nie zgadzają; reguła E zostaje jako zapas (D-0011). **Zachowane odpowiedzi (F2):** krok 8 `ckb-retrieve` proponuje zachowanie istotnej odpowiedzi w `outputs/answers/` (`type: answer`) ze skrótami w `## Sources` i sekcją `## Gaps`, aktualizuje zamiast dublować i wprowadza do wiki tylko przez ingest; kontrola 16 lintu zgłasza zachowane odpowiedzi, których źródła się zmieniły (D-0013). **Meldunek przed ingestem (F3):** zanim cokolwiek zapisze, `ckb-ingest` pokazuje, jak rozumie każde źródło, które strony zmieni i z czym jest sprzeczne, po czym czeka; tryb wsadowy („ingest in batch” albo rutyna z `confirm: false`) to pomija; raport ingestu dostaje sekcję `## Check-in`. **Otwarte wątki (F5):** pola `### Open threads` w notatkach workload (reguła D), zbierane przez `session_start.py` w linię `threads:` z pięcioma najstarszymi i znacznikiem po 30 dniach; bez wspólnego pliku statusu (D-0012). **Deduplikacja przy wejściu (F6):** nowy `ckb-ingest/scripts/dedup_inbox.py` zgłasza `DUPLICATE`, `SAME TEXT`, `CITED`, `SAME URL` i `INBOX TWIN` względem `raw/archive/` oraz cytowanych skrótów i adresów URL przed ingestem. **Ochrona sekretów i prywatności (F19):** kontrola 15 lintu szuka postaci danych uwierzytelniających w commitowanym tekście i fragmentów `<private>` w `wiki/`, maskuje dopasowania, honoruje `.secrets-allow` oparte na skrócie linii; `--quick` ją liczy, `--secrets` uruchamia ją osobno, a `ckb-sync-changes` przed stagingiem; ingest odrzuca, a retrieval nigdy nie cytuje fragmentów `<private>`; `save_conversation.py` je redaguje (D-0013). **Budżet kontekstu (F20):** `lint_report.py --budget` szacuje `AGENTS.md` plus opisy skilli jako znaki ÷ 4; `--quick` flaguje przekroczenie `budget: always_loaded_tokens` (domyślnie 9000). Punkt odniesienia: ~6 620 tokenów w 1.21.0, ~6 810 w 1.22.0. Zapasowe kontrole bash/PowerShell dostają okrojoną kontrolę sekretów; test dymny obejmuje każdy nowy skrypt | 1.5 |
| 1.21.0 | 2026-10-31 | `ABOUT.md`. Nowy plik w katalogu głównym, pisany przez właściciela KB, mówiący, co ta KB zawiera: cel, odbiorcy, zakres (co wchodzi, a co nie), właściciele i kontakty, oczekiwane źródła, poufność, język i terminy; każda sekcja ma komentarz, co w niej napisać; `type: about` z `tldr`. `README.md`/`README.pl.md` linkują do niego pod wskazaniem repozytorium źródłowego, bo samo README należy do szablonu i jest nadpisywane przy aktualizacji. Agenci go czytają i nie edytują bez prośby; pytania o samą KB dostają odpowiedź najpierw z niego, potem z `wiki/overview.md`, które pozostaje podsumowaniem agenta tego, co przetworzono, i teraz do niego linkuje. `ckb-ingest` w Kroku 1 wskazuje materiał spoza zakresu lub wykluczony przez sekcję poufności i przetwarza go tylko na wyraźną prośbę. `ckb-init` kopiuje szkielet i zadaje jedno opcjonalne pytanie o cel i `tldr`; `ckb-upgrade` tworzy go tylko, gdy go brak, i nigdy go nie porównuje; `ckb-reset` nigdy go nie rusza. Moduł `mcp`: `kb_overview` zaczyna się od niego, a opis KB serwera pochodzi z jego `tldr` (zastępczy tekst szkieletu jest pomijany). Zaktualizowano kontrakt katalogów i podręcznik. D-0010 | 1.5 |
| 1.20.0 | 2026-10-30 | Raporty z ingestu. `ckb-ingest` dostaje Krok 8: każde uruchomienie, które coś przetworzyło, zapisuje jeden plik `workload/ingest-reports/YYYY-MM-DD_HHMM_<autor>_ingest.md` (`type: ingest-report`) z listą przyjętych plików z `raw/` wraz ze ścieżką archiwum i odciskiem, zapisanych decyzji, utworzonych/zaktualizowanych encji, innych stron, krawędzi grafu, zasięgu zmian (potwierdzone/rozszerzone/sprzeczne z właścicielami, zamknięte luki w zapytaniach) oraz plików ze skrzynki, których nie przetworzono; każda sekcja zostaje, z `- none`, gdy jest pusta. Zapisywany raz, poza wyszukiwaniem, bez wpisu w `wiki/log.md`, nieruszany przez `ckb-retract`; podfolder, aby `session_start.py` nadal czytał tylko notatki sesji. Dotychczasowy Krok 8 (podsumowanie i przypomnienie o synchronizacji) staje się Krokiem 9 i wskazuje raport. Zaktualizowane: struktura katalogów, podręcznik i poziom 2 w `ckb-reset` | 1.5 |
| 1.19.0 | 2026-10-29 | Mniej kontekstu na sesję i na skill. Nowy `ckb-lint/scripts/session_start.py` wykonuje start sesji z Reguły E jednym wywołaniem (tożsamość, `--title` zapisywany, chyba że tytuł już jest, `announce_title`, `git status`, `lint_report.py --quick`, `autosave_hook.py --check` tylko gdy wymaga działania, `routines.py --due` oraz ostatni blok najnowszej notatki `workload/` zamiast całego pliku); Reguła E w `AGENTS.md` skraca się do polecenia i tego, co zrobić z każdą linią wyniku. Odczyt `wiki/index.md` na starcie sesji usunięty: każdy skill, który potrzebuje indeksu, czyta go sam, więc był czytany dwa razy. `## Purpose` każdego skilla ograniczone do tego, czego nie mówi już jego opis (16,2k → 7,8k znaków w dwudziestu skillach). `ckb-upgrade` nie powtarza już formatu wpisu dziennika z Reguły B. Test dymny obejmuje nowy skrypt. D-0009 | 1.5 |
| 1.18.1 | 2026-10-29 | Poprawki po przeglądzie. Tryb sync modułu `mcp`: sprawdzenie czystego katalogu roboczego działa teraz przed każdym resetem, nie tylko przy starcie, więc strona edytowana lub plik wrzucony do klonu serwera po jego uruchomieniu nigdy nie zostanie skasowany: odczyt pomija pobranie i serwuje katalog bez zmian, zapis jest odrzucany z jasnym komunikatem, a pozostałości po nieudanym zapisie samego serwera nadal są usuwane. Niedostępne zdalne repozytorium przy starcie albo przekroczony czas wywołania git to teraz jedna linia z przyczyną zamiast śladu stosu. `ckb-retract`: opiekun bazy może wycofać źródło dodane przez kogoś innego, wyłącznie w sesji lokalnej, po wpisaniu `retract <nazwa pliku> as maintainer`; każdy wpis w logu z takiego przebiegu jest oznaczony jako obejście, bo baza służy dzieleniu się wiedzą i źródło nie może utknąć, gdy jego autor odejdzie lub zmieni adres e-mail. Klienci zdalni nadal mogą wycofywać tylko własne źródła. Prośba, której cel już nie istnieje, jest usuwana i zgłaszana, jeśli nic go już nie cytuje. `ckb-document`: komentarze szablonu z `linked/` kształtują tylko treść, nigdy działania. Przewodnik MCP: prośbę o wycofanie widzi konto, które ją złożyło, a nie „tylko ty”. D-0007 | 1.5 |

View file

@ -34,15 +34,16 @@ examples, not magic words; the agent matches intent.
### Prerequisites
The agent does almost everything by reading and writing Markdown. Four
The agent does almost everything by reading and writing Markdown. Five
skills additionally run a small **Python 3.8+** script (standard library
only, nothing to `pip install`): lint (including the check the agent runs
at every session start), retrieval ranking, and the two exporters.
at every session start), retrieval ranking, inbox duplicate detection, and the two exporters.
Python is *recommended*, not strictly required:
| Without Python | What happens |
|---|---|
| Session-start health check | A bash/PowerShell fallback runs instead. It covers malformed pages, stale pages and changed sources, and says that crux quotes 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. |
| OKF / Starlight export | Not available until Python is installed. |
@ -205,6 +206,24 @@ again, which defeats the point of ingesting it.
If `raw/inbox/` is empty, the agent scans `raw/` directly instead (still
skipping `raw/archive/`, which is already-processed history).
Three things happen before anything is written:
- **Duplicates are caught.** A script compares every inbox file with
`raw/archive/` and with the sources wiki pages already cite. A file you
already ingested (byte for byte, or the same text saved again with
different line endings), a link to a page the wiki already cites, or two
copies of the same file in the inbox are reported as "already ingested on
<date> → <pages>". The agent asks before skipping any of them.
- **The agent checks in.** For each source it tells you in three or four
lines what it read it as saying, which pages it will create or change,
and what it contradicts. Then it waits. Correct it here; it is far cheaper
than fixing pages afterwards. Say "ingest in batch" (or "no check-in") to
skip this, for example for a large pile you trust. An ingest run by a
routine with `confirm: false` skips it too.
- **Private passages stay out.** Anything you wrap in `<private>` …
`</private>` in a source is never written into the wiki, quoted, or
summarised.
Skill: `.agents/skills/ckb-ingest/SKILL.md`.
### B. Just tell the agent something in conversation
@ -307,8 +326,16 @@ This runs a health check across the whole wiki:
- 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`
- 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
auto-fixed, see below
- kept answers in `outputs/answers/` whose sources have changed get flagged
- the always-loaded layer (`AGENTS.md` plus every skill description) gets
flagged when it grows past the budget in `ckb.yaml`
The last two are the difference between "this page is old" and "this page
The two source checks (changed fingerprints and quotes that no longer match)
are the difference between "this page is old" and "this page
is wrong".
Every page records a fingerprint of the material it was built from. Staleness
@ -337,6 +364,47 @@ safely can on its own and reports the rest for you to decide. Like Ingest,
it finishes by reminding you to review and sync. Skill:
`.agents/skills/ckb-lint/SKILL.md`.
**Secrets.** A key found in the repo is reported with only its first four
characters, never in full. The fix is yours: remove it, and **rotate** it -
once a secret is committed it stays in git history even after the line is
gone. A harmless match, such as an example key in documentation, can be
allowlisted: the finding prints a `<path> <hash>` line to add to
`.secrets-allow` at the repo root. The hash covers that one line, so editing
the line brings the finding back. The same check runs before every "sync
changes" commit.
**Context budget.** Every session starts by loading `AGENTS.md` and the
one-line description of every skill. That costs tokens before you have said
anything. Lint estimates the cost (characters ÷ 4) and flags it when it
passes `budget: always_loaded_tokens` in `ckb.yaml` (9000 by default). Ask
"show the context budget" for the breakdown.
### Starting a session: the brief, open threads and the hook
At the start of every session the agent runs one script and gets a short
brief: who you are (your git identity), the git state, the one-line health
check, due routines, and the last note from `workload/`. It acts only on the
lines that need it.
**Open threads.** When a session ends with something unfinished, the agent
writes it in that day's workload note under `### Open threads` as
`- [ ] item`. The brief counts open threads across all notes and lists the
oldest few, marking any older than 30 days. To close one, tick it where it
was opened (`- [x]`), or write `- [x] dropped: <why>`. Nothing is ever
deleted, so the notes stay a record. This is the KB's "what's in flight
now" view: there is no separate status file to keep in sync.
**The session-start hook (Claude Code only).** By default the agent runs the
brief itself as its first action. With the hook, Claude Code runs it before
your first message and runs it again after the conversation is compacted, so
the brief never falls out of context in a long session. To turn it on, say
"turn on the session-start hook". The agent sets `session: start_hook: true`
in `ckb.yaml` and, after asking, installs the hook in
`.claude/settings.local.json`. That file is per machine and never committed,
because a hook committed to git would run code on every clone. Teammates on
other machines see a `start hook:` line in their brief and are asked once.
Other agents ignore the setting and keep running the brief themselves.
### Routines: do it for me every N days
Anything you would say to the agent can be made a routine:
@ -457,7 +525,10 @@ https://git.wierzbowa.cloud/michal/ckb`).
From then on, "sync changes" reconciles against that remote. This is how
multiple people share one wiki: everyone ingests/edits locally, and "sync
changes" is how each person's changes reach everyone else - and how theirs
reach you. Skill: `.agents/skills/ckb-sync-changes/SKILL.md`.
reach you. Before it commits, it checks what is about to be committed for
secrets (see [Keeping it tidy](#3-keeping-it-tidy)). If it finds one, it
stops and asks, and commits anyway only if you say so explicitly. Skill:
`.agents/skills/ckb-sync-changes/SKILL.md`.
The agent also nudges you about this automatically: at the start and end
of a working session it does a quick, read-only check for anything
@ -607,6 +678,17 @@ Two details matter as a user:
you'll hear about that too. You never have to read the frontmatter
yourself to know how much to trust what you just got.
When an answer took real work (several pages pieced together, a source
re-read), the agent offers once to keep it. Say yes and it goes to
`outputs/answers/<date>_<question>.md`, with the sources it rests on
(fingerprinted, so lint tells you when they change) and a `## Gaps` section
listing what the KB could not answer. Ask the same question again later and
the agent offers to update the kept answer instead of writing a second one.
If the answer holds something the wiki itself should know, the agent offers
to file it back. That means a normal ingest, with the same check-in, so a
kept answer never edits the wiki on its own. Private passages (`<private>`)
are never quoted in an answer.
### Ask who knows something
> "Who knows about the checkpoint restore path?" / "Who owns the billing
@ -956,6 +1038,9 @@ ship it, so a knowledge base never carries it.
| "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` |
| "Rename this conversation to X" / "Stop telling me the title" | Sets the session's title (used by the saved transcript and the workload note) / flips `conversations.announce_title` | `ckb-add-conversation` |
| "Keep this answer" | Saves the last answer to `outputs/answers/` with its sources and gaps | `ckb-retrieve` |
| "Ingest in batch" / "Ingest, no check-in" | Ingests without stopping to show its reading of each source first | `ckb-ingest` |
| "Turn on the session-start hook" / "Show the context budget" | Sets `session.start_hook` in `ckb.yaml` and installs the per-machine hook / prints the always-loaded token estimate | `ckb-lint` |
| "Lint every week" / "Index external sources every 30 days, ask me first" | Adds a routine to `ckb.yaml`; due routines run at session start, after your request | `ckb-routine` |
| "List routines" / "Which routines are due" / "Remove the weekly lint" | Shows, checks or removes routines | `ckb-routine` |
| "Did we discuss X" / "What did I tell you about X" | Searches saved conversations and quotes the exchange | `ckb-add-conversation` |

View file

@ -36,15 +36,17 @@ intencji.
### Wymagania wstępne
Agent robi prawie wszystko, czytając i pisząc Markdown. Cztery skille
dodatkowo uruchamiają mały skrypt w **Pythonie 3.8+** (tylko biblioteka
Agent robi prawie wszystko, czytając i pisząc Markdown. Pięć skilli
dodatkowo uruchamia mały skrypt w **Pythonie 3.8+** (tylko biblioteka
standardowa, nic do `pip install`): lint (w tym kontrola uruchamiana na
początku każdej sesji), ranking przy wyszukiwaniu oraz dwa eksporty.
początku każdej sesji), ranking przy wyszukiwaniu, wykrywanie duplikatów w
skrzynce oraz dwa eksporty.
Python jest *zalecany*, nie bezwzględnie wymagany:
| Bez Pythona | Co się dzieje |
|---|---|
| Kontrola na starcie sesji | Zamiast niej działa zapasowy skrypt bash/PowerShell. Wykrywa strony uszkodzone, przeterminowane i zmienione źródła; zaznacza, że cytaty Crux 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. |
| Eksport OKF / Starlight | Niedostępny do czasu zainstalowania Pythona. |
@ -214,6 +216,24 @@ jego zingestowania.
Jeśli `raw/inbox/` jest puste, agent skanuje bezpośrednio `raw/` (nadal
pomijając `raw/archive/`, które zawiera już przetworzoną historię).
Zanim cokolwiek zostanie zapisane, dzieją się trzy rzeczy:
- **Duplikaty zostają wyłapane.** Skrypt porównuje każdy plik ze skrzynki z
`raw/archive/` i ze źródłami, które strony wiki już cytują. Plik już
zingestowany (co do bajtu albo ten sam tekst zapisany ponownie z innymi
końcami linii), link do strony, którą wiki już cytuje, albo dwie kopie tego
samego pliku w skrzynce zostają zgłoszone jako „już zingestowane <data> →
<strony>”. Agent pyta, zanim którykolwiek pominie.
- **Agent się melduje.** Dla każdego źródła mówi w trzech–czterech
linijkach, jak je rozumie, które strony utworzy lub zmieni i z czym jest
sprzeczne. Potem czeka. Popraw go w tym momencie: to dużo taniej niż
poprawianie stron później. Powiedz „ingest in batch” (albo „no check-in”),
żeby to pominąć, np. dla dużej paczki, której ufasz. Ingest uruchomiony
przez rutynę z `confirm: false` też to pomija.
- **Fragmenty prywatne zostają poza wiki.** Wszystko, co w źródle owiniesz w
`<private>` … `</private>`, nigdy nie trafia do wiki: nie jest zapisywane,
cytowane ani streszczane.
Skill: `.agents/skills/ckb-ingest/SKILL.md`.
### B. Po prostu powiedz agentowi coś w rozmowie
@ -322,8 +342,18 @@ To uruchamia przegląd kondycji całej wiki:
- 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`
- 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
stronę wiki, zostają oflagowane — nigdy nie są naprawiane automatycznie,
patrz niżej
- zachowane odpowiedzi w `outputs/answers/`, których źródła się zmieniły,
zostają oflagowane
- warstwa ładowana zawsze (`AGENTS.md` plus opis każdego skilla) zostaje
oflagowana, gdy przekroczy budżet z `ckb.yaml`
Dwa ostatnie punkty to różnica między „ta strona jest stara"
Dwie kontrole źródeł (zmienione skróty i cytaty, które przestały się
zgadzać) to różnica między „ta strona jest stara"
a „ta strona jest błędna".
Każda strona zapisuje skrót materiału, z którego powstała. Nieaktualność
@ -352,6 +382,48 @@ Naprawia samodzielnie to, co może zrobić bezpiecznie, a resztę zgłasza do
twojej decyzji. Podobnie jak Ingest, na koniec przypomina o przejrzeniu i
synchronizacji. Skill: `.agents/skills/ckb-lint/SKILL.md`.
**Sekrety.** Klucz znaleziony w repozytorium jest pokazywany tylko w
pierwszych czterech znakach, nigdy w całości. Naprawa należy do ciebie: usuń
go i **wymień** (rotate) — zacommitowany sekret zostaje w historii gita nawet
po usunięciu linii. Nieszkodliwe dopasowanie, np. przykładowy klucz w
dokumentacji, można dodać do listy dozwolonych: znalezisko podaje linię
`<ścieżka> <skrót>` do wpisania w `.secrets-allow` w katalogu głównym repo.
Skrót obejmuje tę jedną linię, więc jej edycja przywraca znalezisko. Ta sama
kontrola działa przed każdym commitem w „sync changes”.
**Budżet kontekstu.** Każda sesja zaczyna się od wczytania `AGENTS.md` i
jednolinijkowego opisu każdego skilla. To kosztuje tokeny, zanim cokolwiek
powiesz. Lint szacuje ten koszt (znaki ÷ 4) i flaguje go, gdy przekroczy
`budget: always_loaded_tokens` w `ckb.yaml` (domyślnie 9000). Powiedz „show
the context budget”, żeby zobaczyć rozbicie.
### Start sesji: podsumowanie, otwarte wątki i hook
Na początku każdej sesji agent uruchamia jeden skrypt i dostaje krótkie
podsumowanie: kim jesteś (tożsamość z gita), stan gita, jednolinijkową
kontrolę kondycji, zaległe rutyny i ostatnią notatkę z `workload/`. Reaguje
tylko na linie, które tego wymagają.
**Otwarte wątki.** Gdy sesja kończy się czymś niedokończonym, agent zapisuje
to w notatce z danego dnia pod nagłówkiem `### Open threads` jako
`- [ ] pozycja`. Podsumowanie liczy otwarte wątki we wszystkich notatkach i
wymienia kilka najstarszych, zaznaczając te starsze niż 30 dni. Żeby zamknąć
wątek, odhacz go tam, gdzie został otwarty (`- [x]`), albo napisz
`- [x] dropped: <powód>`. Nic nie jest usuwane, więc notatki pozostają
zapisem. To jest widok „co jest teraz w toku”: nie ma osobnego pliku
statusu, który trzeba by aktualizować.
**Hook startu sesji (tylko Claude Code).** Domyślnie agent sam uruchamia
podsumowanie jako pierwszą czynność. Z hookiem robi to Claude Code, zanim
napiszesz pierwszą wiadomość, i ponownie po kompaktowaniu rozmowy, więc w
długiej sesji podsumowanie nie wypada z kontekstu. Żeby go włączyć, powiedz
„turn on the session-start hook”. Agent ustawia `session: start_hook: true`
w `ckb.yaml` i, po zapytaniu, instaluje hook w `.claude/settings.local.json`.
Ten plik jest per maszyna i nigdy nie jest commitowany, bo hook w gicie
uruchamiałby kod przy każdym klonie. Współpracownicy na innych maszynach
widzą w podsumowaniu linię `start hook:` i są pytani raz. Inni agenci
ignorują to ustawienie i dalej uruchamiają podsumowanie sami.
### Rutyny: rób to za mnie co N dni
Wszystko, co można powiedzieć agentowi, można zamienić w rutynę:
@ -480,7 +552,10 @@ Od tej pory „sync changes” uzgadnia stan właśnie z tym zdalnym
repozytorium. Tak dzieli się jedną wiki między wieloma osobami: każdy
robi ingest/edycje lokalnie, a „sync changes” to sposób, w jaki zmiany
każdej osoby docierają do reszty — i jak zmiany innych docierają do ciebie.
Skill: `.agents/skills/ckb-sync-changes/SKILL.md`.
Przed commitem sprawdza, czy to, co ma zostać zacommitowane, nie zawiera
sekretów (zob. [Utrzymanie porządku](#3-utrzymanie-porządku)). Jeśli coś
znajdzie, zatrzymuje się i pyta, a commituje mimo to tylko na wyraźne
polecenie. Skill: `.agents/skills/ckb-sync-changes/SKILL.md`.
Agent przypomina o tym też sam: na początku i na końcu sesji pracy wykonuje
szybkie, tylko-do-odczytu sprawdzenie, czy jest coś niezacommitowanego lub
@ -637,6 +712,17 @@ Dwa szczegóły mają znaczenie dla użytkownika:
trzeba samodzielnie czytać frontmatteru, żeby wiedzieć, na ile ufać
otrzymanej odpowiedzi.
Gdy odpowiedź wymagała prawdziwej pracy (złożenia kilku stron, ponownego
przeczytania źródła), agent raz proponuje jej zachowanie. Jeśli się zgodzisz,
trafia do `outputs/answers/<data>_<pytanie>.md` razem ze źródłami, na których
się opiera (ze skrótami, więc lint powie ci, gdy się zmienią), i sekcją
`## Gaps` z tym, na co KB nie umiała odpowiedzieć. Gdy później zadasz to samo
pytanie, agent zaproponuje aktualizację zachowanej odpowiedzi zamiast
pisania drugiej. Jeśli odpowiedź zawiera coś, co powinna wiedzieć sama wiki,
agent proponuje wprowadzenie jej z powrotem. Oznacza to zwykły ingest, z tym
samym meldunkiem, więc zachowana odpowiedź nigdy sama nie zmienia wiki.
Fragmenty prywatne (`<private>`) nigdy nie są cytowane w odpowiedzi.
Gdy nadal nie ma odpowiedzi, agent powinien powiedzieć, czego brakuje, i albo
dodać/zaproponować krótki wpis w `wiki/query-gaps.md`, albo zasugerować
najmniejsze źródło do wrzucenia do `raw/inbox/`.
@ -1003,6 +1089,9 @@ wiedzy nigdy go nie zawiera.
| „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` |
| „Rename this conversation to X” / „Stop telling me the title” | Ustawia tytuł sesji (używany przez zapisany transkrypt i notatkę workload) / przestawia `conversations.announce_title` | `ckb-add-conversation` |
| „Retract X” / „Undo the ingest of X” / „This went to the wrong KB” | Pokazuje, co zbudowało źródło (strony, twierdzenia, krawędzie), a po twojej zgodzie usuwa dokładnie to; obsługuje prośby z `raw/retractions/` | `ckb-retract` |
| „Keep this answer” | Zapisuje ostatnią odpowiedź w `outputs/answers/` razem ze źródłami i lukami | `ckb-retrieve` |
| „Ingest in batch” / „Ingest, no check-in” | Ingestuje bez zatrzymywania się, by najpierw pokazać, jak rozumie każde źródło | `ckb-ingest` |
| „Turn on the session-start hook” / „Show the context budget” | Ustawia `session.start_hook` w `ckb.yaml` i instaluje hook na tej maszynie / pokazuje szacunek tokenów warstwy ładowanej zawsze | `ckb-lint` |
| „Lint every week” / „Index external sources every 30 days, ask me first” | Dodaje rutynę do `ckb.yaml`; zaległe rutyny wykonują się na starcie sesji, po twojej prośbie | `ckb-routine` |
| „List routines” / „Which routines are due” / „Remove the weekly lint” | Pokazuje, sprawdza lub usuwa rutyny | `ckb-routine` |
| „What modules are available” / „Install the mcp module” | Pokazuje lub instaluje opcjonalny moduł; nic w nim nie działa przed instalacją | `ckb-module` |

View file

@ -0,0 +1,68 @@
---
type: decision
tldr: Session start can run as a Claude Code SessionStart hook that injects the Rule E brief before the first message and again after every compaction; it is opt-in per KB in ckb.yaml, installed per machine in the gitignored settings.local.json, and Rule E stays the fallback for every other agent.
status: accepted
decided_on: 2026-11-02
decided_by: Michał Kopeć
affects: AGENTS.md, ckb.yaml, .agents/skills/ckb-lint/scripts/session_start.py, .agents/skills/ckb-lint/scripts/start_hook.py, .agents/skills/ckb-lint/SKILL.md, docs/MANUAL.md
confidence: 0.8
quality: 0.8
last_updated: 2026-11-02
freshness_window_days: 365
retention: high
---
# D-0011 — The session-start brief can be injected by a hook
**Status:** Accepted · **Decided:** 2026-11-02 · **Deciders:** Michał Kopeć
## Context
Rule E asks the agent to run `session_start.py` as its first action
(D-0009). That works only while the instruction is followed, and it fires
once: when a long session is compacted, the brief is summarised away with
everything else. Claude Code's `SessionStart` hook fires on startup, resume,
`/clear` and compaction, and can add text to the context before the model
acts. m3talux/superbrain and claude-mem use the same mechanism for the same
reason (research report, 2026-10-31, feature F1).
## Decision
1. **`session_start.py --hook`** reads the hook's JSON on stdin and prints
the same brief as `additionalContext`, headed `ckb session brief
(SessionStart hook, <source>)`. On `compact` and `resume` it says
`announce: no`, because the title was already announced. It looks the
stored title up by the hook's `session_id`, since a new session has no
transcript yet. When none is stored, the `title:` line gives the
`save_conversation.py --set-title` command.
2. **Opt-in per KB, installed per machine.** `session: start_hook: true` in
`ckb.yaml` says the KB wants it. `start_hook.py --check|--install|--remove`
manages the entry in `.claude/settings.local.json`, which is gitignored.
The brief prints a `start hook:` line only when the two disagree, and the
agent asks before changing anything. This is the same pattern as the
autosave hook.
3. **Rule E stays.** One sentence in `AGENTS.md` tells the agent not to run
the script again when the hooked brief is already in context. Every other
agent keeps running Rule E by hand.
4. **The hook can never block a session**: its command discards stderr and
always exits 0.
## Alternatives considered
- **Commit the hook in `.claude/settings.json`** was rejected: a committed
hook runs code on every clone of a shared KB, without the cloner choosing it.
- **Replace Rule E with the hook** was rejected: hooks are Claude Code only,
and the template supports any agent that reads `AGENTS.md`.
- **A `PreCompact` hook** was rejected: `SessionStart` with source
`compact` already fires after compaction, and that is when the brief is
needed.
## Consequences
- In Claude Code with the hook on, the brief costs no tool call and survives
compaction.
- The title is stored by a second, explicit command instead of by the
script, because the agent picks the title only after reading the first
message.
- Two hooks now share `settings.local.json`. Each installer touches only its
own entry, and the smoke test checks that.

View file

@ -0,0 +1,60 @@
---
type: decision
tldr: The "what is in flight" view is built from `### Open threads` checkboxes in each person's own workload notes, collected by session_start.py, instead of a shared rewritten-in-place status page; threads close where they were opened and are never deleted.
status: accepted
decided_on: 2026-11-02
decided_by: Michał Kopeć
affects: AGENTS.md, .agents/skills/ckb-lint/scripts/session_start.py, docs/MANUAL.md
confidence: 0.75
quality: 0.8
last_updated: 2026-11-02
freshness_window_days: 365
retention: high
---
# D-0012 — Open threads in workload notes, not a shared status file
**Status:** Accepted · **Decided:** 2026-11-02 · **Deciders:** Michał Kopeć
## Context
Feature F5 of the 2026-10-31 research report asked for working memory: a
short "now" page split from stable facts (Cline's Memory Bank, Manus's
`todo.md`), plus open threads collected at session start. The implementation
plan left the location of the "now" page to this record.
Two constraints decide it. Workload notes are one file per person per day
precisely so a shared repo never conflicts there (D-0004); one page that
everyone rewrites would conflict on every busy day. And a page under
`wiki/` would need a Rule B log entry for every rewrite, turning the log
into a status feed.
## Decision
1. **No status file.** Unfinished work goes in the author's own workload
note, under a `### Open threads` heading, as `- [ ] item` lines (Rule D).
2. **Closed where opened.** A thread is closed by ticking it in the note
that opened it (`- [x]`), or `- [x] dropped: <why>`. Nothing is deleted,
so the notes stay a record.
3. **`session_start.py` collects them.** Every unticked item under an "Open
threads" heading, in any top-level workload note, oldest first. The brief
shows the count and the five oldest, and marks any older than 30 days. The
line is printed only when a thread is open. The agent mentions the count
and picks a thread up only when asked.
4. **Stable facts stay where they are**: `wiki/overview.md` and `ABOUT.md`.
## Alternatives considered
- **`wiki/now.md`, rewritten in place** was rejected: merge conflicts in
shared repos, and a log entry per rewrite.
- **`workload/now.md`** was rejected: it avoids the log, not the conflicts.
- **One status file per person** was rejected: it is another file to keep
in step with the workload note that already records the session.
## Consequences
- The current-state view costs no new file and no new write rule.
- Closing someone else's thread means editing their note. That is a one-line
change in a file they rarely touch the same day.
- A thread nobody closes stays visible and gets marked stale. Pruning it is
a person's call.

View file

@ -0,0 +1,72 @@
---
type: decision
tldr: Answers worth keeping go to outputs/answers/ with fingerprinted sources and a Gaps section and reach the wiki only through a normal ingest; committed text is scanned for credential shapes and <private> spans by lint and before every sync commit, never auto-fixed, with a line-hash allowlist for harmless matches.
status: accepted
decided_on: 2026-11-02
decided_by: Michał Kopeć
affects: AGENTS.md, .agents/skills/ckb-retrieve/SKILL.md, .agents/skills/ckb-ingest/SKILL.md, .agents/skills/ckb-lint/, .agents/skills/ckb-sync-changes/SKILL.md, .agents/skills/ckb-add-conversation/scripts/save_conversation.py, docs/MANUAL.md
confidence: 0.8
quality: 0.8
last_updated: 2026-11-02
freshness_window_days: 365
retention: high
---
# D-0013 — Kept answers live in outputs/; secrets and private spans are guarded
**Status:** Accepted · **Decided:** 2026-11-02 · **Deciders:** Michał Kopeć
## Context
Two features from the 2026-10-31 research report touch the same boundary,
what may become shared, committed knowledge:
- **F2, keep answers.** Karpathy's LLM-wiki pattern files good answers back
as pages. Written straight into `wiki/`, an answer would skip the check-in,
the blast radius and the fingerprints that every other page goes through.
- **F19, secret and privacy guards.** Every file in a KB is committed and
usually pushed. The sync skill already flagged secret-looking *file names*
but never looked inside files, and a saved conversation copied everything
verbatim.
## Decision
1. **Kept answers are outputs.** On request, `ckb-retrieve` writes
`outputs/answers/YYYY-MM-DD_<slug>.md` (`type: answer`) with the answer,
`## Sources` fingerprints of the pages and files it rests on, and a
`## Gaps` section. It updates an existing answer to the same question
instead of writing a second. Lint check 16 reports a kept answer whose
sources moved.
2. **Filing back is an ingest.** The answer is copied into `raw/inbox/` and
ingested like any source. Retrieval never writes `wiki/` pages.
3. **Lint check 15 scans committed text** in `wiki/`, `outputs/` (not the
gitignored exports), `workload/` and `raw/` for credential shapes, and
`wiki/` for `<private>` spans. A finding shows four characters, never
the secret. It is never auto-fixed, because the remedy is rotation.
`--quick` counts findings at session start, and `ckb-sync-changes` runs
`--secrets` before staging and stops on a hit.
4. **Allowlist by line hash.** `.secrets-allow` holds `<path> <hash>` pairs.
The hash covers that line's text, so editing the line brings the finding
back, and a moved line stays allowed.
5. **`<private>` spans** are dropped by ingest, never quoted by retrieval, and
redacted from saved conversations in both the JSONL and the Markdown.
JSONL lines without a span stay byte-identical.
## Alternatives considered
- **Kept answers under `wiki/answers/`** was rejected: they would be pages
that bypassed ingest's checks, and they would need log entries.
- **A git pre-commit hook for secrets** was rejected for now: per-machine
hooks have to be installed, while the sync skill and session-start check
run everywhere.
- **Auto-removing a found secret** was rejected: removal without rotation
gives a false sense of safety.
## Consequences
- Retrieval keeps its read-only character apart from two named exceptions:
query gaps and kept answers.
- Pattern lists produce false positives. The allowlist is the outlet, and
the bash/PowerShell fallbacks use a smaller pattern set than Python.
- Redaction removes only the span. A private value the agent repeated
elsewhere in the session is still saved, and the skill says so.

View file

@ -24,3 +24,6 @@ but they live here, in the template layer, because:
| [D-0008](0008-document-templates.md) | Document templates are the user's Markdown files in root `templates/`, outside the cascade and the template layer; a comment per section is the agent's brief; `ckb-document` fills one into `outputs/documents/`, asking in one round and leaving `TODO:` lines instead of guesses |
| [D-0009](0009-session-start-in-one-call.md) | Session start is one `session_start.py` call that says what to act on; `wiki/index.md` and the whole workload file are no longer read at start; a skill's `## Purpose` says only what its description does not |
| [D-0010](0010-about-file.md) | A root `ABOUT.md`, written by the owner, states what the KB holds (purpose, audience, scope, owners, sensitivity) and the README links to it; agents read it, never edit it; ingest checks scope against it; `wiki/overview.md` stays the agent's summary |
| [D-0011](0011-session-start-hook.md) | Session start can run as a per-machine, opt-in Claude Code `SessionStart` hook that injects the Rule E brief before the first message and after every compaction; Rule E stays the fallback |
| [D-0012](0012-open-threads-not-a-status-file.md) | "What is in flight" is collected from `### Open threads` checkboxes in each person's workload notes, not a shared status page; threads close where they were opened |
| [D-0013](0013-kept-answers-and-secret-guards.md) | Kept answers go to `outputs/answers/` with fingerprinted sources and reach the wiki only through ingest; committed text is scanned for secrets and `<private>` spans, never auto-fixed, with a line-hash allowlist |

0
outputs/answers/.gitadd Normal file
View file

5
tests/expected/dedup.txt Normal file
View file

@ -0,0 +1,5 @@
INBOX TWIN raw/inbox/c-twin.md — identical to raw/inbox/b-twin.md, also in the inbox
SAME TEXT raw/inbox/dlq-crlf.md — same text as raw/archive/2026-09-02/dlq-review.md (ingested 2026-09-02; only whitespace or line endings differ) → wiki/entities/atlas-retry-policy.md
DUPLICATE raw/inbox/kickoff-copy.md — identical to raw/archive/2026-09-01/kickoff-notes.md (ingested 2026-09-01) → wiki/decisions/0001-three-retries-then-dlq.md, wiki/entities/atlas-retry-policy.md, wiki/entities/maria-nowak.md
SAME URL raw/inbox/retries.url — https://example.com/atlas/retries?utm_source=x#top is already cited as a source → wiki/projects/atlas.md
inbox: 2 new, 4 already ingested or duplicated

View file

@ -27,5 +27,8 @@
}
],
"sources": [],
"secrets": [],
"answers": [],
"budget": [],
"findings": 0
}

View file

@ -37,7 +37,44 @@ python3 "$ROUT" --root "$TMP" --mark weekly-lint --today "$TODAY" >/dev/null
python3 "$ROUT" --root "$TMP" --add --name smoke --do "Lint" --every 2w >/dev/null
python3 "$ROUT" --root "$TMP" --remove smoke >/dev/null
# Dedup: one copy, one re-saved copy, one cited URL, two inbox twins, one new file.
DEDUP=.agents/skills/ckb-ingest/scripts/dedup_inbox.py
mkdir -p "$TMP/dedup" && cp -r "$FIX/." "$TMP/dedup/" && mkdir -p "$TMP/dedup/raw/inbox"
cp "$FIX/raw/archive/2026-09-01/kickoff-notes.md" "$TMP/dedup/raw/inbox/kickoff-copy.md"
sed 's/$/\r/' "$FIX/raw/archive/2026-09-02/dlq-review.md" > "$TMP/dedup/raw/inbox/dlq-crlf.md"
printf '\n## Sources\n\n- `https://www.example.com/atlas/retries/` — etag:abc\n' >> "$TMP/dedup/wiki/projects/atlas.md"
printf '[InternetShortcut]\nURL=https://example.com/atlas/retries?utm_source=x#top\n' > "$TMP/dedup/raw/inbox/retries.url"
echo "fresh material" > "$TMP/dedup/raw/inbox/a-new.md" && echo "twin" > "$TMP/dedup/raw/inbox/b-twin.md" && cp "$TMP/dedup/raw/inbox/b-twin.md" "$TMP/dedup/raw/inbox/c-twin.md"
( python3 "$DEDUP" --root "$TMP/dedup" || true ) | sed "s#$TMP#TMP#g" > "$TMP/dedup.txt"
# Session start: open threads, hook mode, and the start-hook installer.
mkdir -p "$TMP/start" && cp -r "$FIX/." "$TMP/start/" && mkdir -p "$TMP/start/workload"
printf -- '---\ntype: session\n---\n\n## Work\n\n### Open threads\n- [ ] Ask Maria about DLQ size\n- [x] closed one\n\n## Later\n\n- [ ] not under Open threads\n' \
> "$TMP/start/workload/2026-08-01_fixture-user_summary.md"
( cd "$TMP/start" && python3 "$OLDPWD/.agents/skills/ckb-lint/scripts/session_start.py" --today "$TODAY" --no-git ) > "$TMP/start-threads.txt"
echo '{"source":"compact","session_id":"none"}' | ( cd "$TMP/start" && python3 "$OLDPWD/.agents/skills/ckb-lint/scripts/session_start.py" --hook --today "$TODAY" --no-git ) > "$TMP/hook.json"
mkdir -p "$TMP/start/.claude" && echo '{"hooks":{"Stop":[{"hooks":[{"type":"command","command":"keep me"}]}]}}' > "$TMP/start/.claude/settings.local.json"
printf '\nsession:\n start_hook: true\n' >> "$TMP/start/ckb.yaml"
HOOK=.agents/skills/ckb-lint/scripts/start_hook.py
( cd "$TMP/start" && ! python3 "$OLDPWD/$HOOK" --check >/dev/null && python3 "$OLDPWD/$HOOK" --install >/dev/null \
&& python3 "$OLDPWD/$HOOK" --check >/dev/null && python3 "$OLDPWD/$HOOK" --remove >/dev/null ) > "$TMP/hook-cycle.txt" 2>&1 && echo ok >> "$TMP/hook-cycle.txt"
# Secrets: two planted keys (one in a gitignored export, skipped), a private span in wiki/, then an allowlist line.
mkdir -p "$TMP/sec" && cp -r "$FIX/." "$TMP/sec/" && mkdir -p "$TMP/sec/workload" "$TMP/sec/outputs/okf"
echo "aws AKIAABCDEFGHIJKLMNOP here" > "$TMP/sec/workload/2026-09-01_x_summary.md"
echo "AKIAABCDEFGHIJKLMNOP" > "$TMP/sec/outputs/okf/page.md"
echo "<private>do not keep</private>" >> "$TMP/sec/wiki/overview.md"
( cd "$TMP/sec" && python3 "$OLDPWD/$LINT" --secrets || true ) > "$TMP/secrets.txt"
( cd "$TMP/sec" && python3 "$OLDPWD/$LINT" --quick --today "$TODAY" || true ) > "$TMP/sec.py.txt"
( cd "$TMP/sec" && bash "$OLDPWD/$QUICK" --today "$TODAY" || true ) | sed 's/ (fallback:.*//' > "$TMP/sec.sh.txt"
ALLOW=$(grep -o 'add `workload/[^`]*`' "$TMP/secrets.txt" | sed 's/^add `//; s/`$//')
echo "$ALLOW # smoke: fixture key" > "$TMP/sec/.secrets-allow"
( cd "$TMP/sec" && python3 "$OLDPWD/$LINT" --secrets || true ) > "$TMP/secrets-allowed.txt"
# Private spans never reach a saved conversation.
mkdir -p "$TMP/priv" && sed 's#How many times does Atlas retry a failed batch?#<private>hunter2 is the vault code</private> How many times does Atlas retry a failed batch?#' \
tests/fixtures/conversation/session.jsonl > "$TMP/priv-session.jsonl"
python3 "$SAVE" --from "$TMP/priv-session.jsonl" --root "$TMP/priv" --today "$TODAY" --author "Fixture User <fixture@example.com>" > /dev/null
if [[ "${1:-}" == "--update" ]]; then
cp "$TMP/dedup.txt" tests/expected/dedup.txt
cp "$TMP/lint.json" tests/expected/lint.json
cp "$TMP/retrieve.json" tests/expected/retrieve.json
cp "$TMP/conversation.md" tests/expected/conversation.md
@ -64,6 +101,23 @@ python3 "$START" --root "$FIX" --today "$TODAY" --no-git > "$TMP/start.txt" || {
grep -q '^ckb check: clean' "$TMP/start.txt" || { echo "session_start: no clean check line"; fail=1; }
grep -q '^routines: DUE weekly-lint' "$TMP/start.txt" || { echo "session_start: due routine missing"; fail=1; }
grep -q '^announce: yes' "$TMP/start.txt" || { echo "session_start: announce line missing"; fail=1; }
# Release 1.22 features.
if ! diff -u tests/expected/dedup.txt "$TMP/dedup.txt"; then echo "DRIFT: dedup"; fail=1; fi
# One open thread: the ticked one and the one outside "Open threads" must not count.
grep -q '^threads: 1 open' "$TMP/start-threads.txt" || { echo "session_start: expected exactly 1 open thread"; fail=1; }
python3 -c "import json,sys;c=json.load(open(sys.argv[1]))['hookSpecificOutput']['additionalContext'];assert 'ckb check: clean' in c and 'announce: no' in c" "$TMP/hook.json" \
|| { echo "session_start --hook: bad JSON or wrong announce on compact"; fail=1; }
[[ "$(tail -1 "$TMP/hook-cycle.txt")" == ok ]] || { echo "start_hook: check/install/remove cycle failed"; cat "$TMP/hook-cycle.txt"; fail=1; }
grep -q '"keep me"' "$TMP/start/.claude/settings.local.json" || { echo "start_hook: removed a hook it does not own"; fail=1; }
[[ "$(tail -1 "$TMP/secrets.txt")" == "secrets: 2 possible" ]] || { echo "secrets: expected 2 (key + private span)"; cat "$TMP/secrets.txt"; fail=1; }
[[ "$(tail -1 "$TMP/secrets-allowed.txt")" == "secrets: 1 possible" ]] || { echo "secrets: allowlist line not honoured"; cat "$TMP/secrets-allowed.txt"; fail=1; }
if ! diff -u "$TMP/sec.py.txt" "$TMP/sec.sh.txt"; then echo "DRIFT: lint_quick.sh secrets count disagrees with lint_report.py"; fail=1; fi
! grep -rq hunter2 "$TMP/priv/raw/saved-conversations" || { echo "save_conversation: <private> span was saved"; fail=1; }
grep -q '<private>\[redacted\]</private>' "$TMP"/priv/raw/saved-conversations/"$TODAY"/*.md || { echo "save_conversation: redaction mark missing"; fail=1; }
python3 -c "import json,sys;[json.loads(l) for l in open(sys.argv[1]) if l.strip()]" "$TMP"/priv/raw/saved-conversations/"$TODAY"/*.jsonl \
|| { echo "save_conversation: redacted JSONL is not valid JSON"; fail=1; }
# The template must stay inside its own context budget.
python3 "$LINT" --budget > "$TMP/budget.txt" || { echo "budget: template is over its own always-loaded budget"; head -3 "$TMP/budget.txt"; fail=1; }
# mcp module: what a remote client may read and write (no MCP SDK needed).
python3 tests/mcp_policy.py "$FIX" || fail=1
[[ $fail -eq 0 ]] && echo "smoke: OK"