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:
parent
da2833abfe
commit
cb56da51e5
31 changed files with 1504 additions and 76 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
216
.agents/skills/ckb-ingest/scripts/dedup_inbox.py
Normal file
216
.agents/skills/ckb-ingest/scripts/dedup_inbox.py
Normal 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())
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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")
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
||||
|
|
|
|||
131
.agents/skills/ckb-lint/scripts/start_hook.py
Normal file
131
.agents/skills/ckb-lint/scripts/start_hook.py
Normal 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())
|
||||
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
41
AGENTS.md
41
AGENTS.md
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
30
README.md
30
README.md
|
|
@ -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`.
|
||||
|
|
|
|||
38
README.pl.md
38
README.pl.md
|
|
@ -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`.
|
||||
|
|
|
|||
2
VERSION
2
VERSION
|
|
@ -1 +1 @@
|
|||
1.21.0
|
||||
1.22.0
|
||||
|
|
|
|||
8
ckb.yaml
8
ckb.yaml
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|
|
|
|||
|
|
@ -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` |
|
||||
|
|
|
|||
|
|
@ -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` |
|
||||
|
|
|
|||
68
docs/decisions/0011-session-start-hook.md
Normal file
68
docs/decisions/0011-session-start-hook.md
Normal 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.
|
||||
60
docs/decisions/0012-open-threads-not-a-status-file.md
Normal file
60
docs/decisions/0012-open-threads-not-a-status-file.md
Normal 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.
|
||||
72
docs/decisions/0013-kept-answers-and-secret-guards.md
Normal file
72
docs/decisions/0013-kept-answers-and-secret-guards.md
Normal 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.
|
||||
|
|
@ -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
0
outputs/answers/.gitadd
Normal file
5
tests/expected/dedup.txt
Normal file
5
tests/expected/dedup.txt
Normal 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
|
||||
|
|
@ -27,5 +27,8 @@
|
|||
}
|
||||
],
|
||||
"sources": [],
|
||||
"secrets": [],
|
||||
"answers": [],
|
||||
"budget": [],
|
||||
"findings": 0
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue