ckb/.agents/skills/ckb-lint/scripts/lint_report.py
Michał Kopeć 1d7a489323 Template 1.24.0: release 3 batch 1, retrieval
- F10 bm25 section search: stdlib SQLite FTS5 over page sections, with
  title/heading path/tldr in a separate context column; cached in
  tmp/ckb-fts.sqlite, refreshed by mtime then sha256; section anchors
  per candidate. New benchmark tests/bench_retrieval.py over
  tests/fixtures/bench-kb (20 questions): hit@1 14/20, hit@3 20/20 with
  and without bm25; weight kept at 1.0 (D-0015)
- F12 token estimate per candidate; layered reading in ckb-retrieve
- F16 --opened access log in tmp/access.log; lint_report.py --cold
  proposes demotion to an index `## Archive` section, never moves
- F17 ckb-retrieve offers a table/chart/deck/HTML once when it fits

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 20:25:26 +01:00

1203 lines
50 KiB
Python

#!/usr/bin/env python3
# Copyright 2026 Michał Kopeć
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""Deterministic half of the ckb-lint health check: detect, never fix.
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
python3 lint_report.py --cold [DAYS] # pages nobody has read for DAYS (default 90): demotion proposals
Run from the repository root (the directory containing wiki/ and libs/).
This script is strictly READ-ONLY. It writes no files, moves nothing, and runs
no git commands — it prints findings for the agent to act on. The mechanical
checks (conformance, freshness, retention/decay candidates, orphans, graph
consistency, index/log consistency, source.yaml validity, source fingerprints,
crux verbatimness) live here; the
judgment calls the ckb-lint skill owns (whether two pages genuinely supersede
one another, ambiguous orphans, error-book entries, auto-fix vs. report) stay
with the model. Decision records get their own structural checks here — status
vocabulary, required dates, two-sided supersession links — since those are
mechanical; deciding that a new decision *replaces* an old one is not.
Exit code is 0 when nothing was found and 1 when there are findings.
"""
import argparse
import fnmatch
import hashlib
import json
import re
import sys
from datetime import date, datetime
from pathlib import Path
REPO_ROOT = Path.cwd()
WIKI = REPO_ROOT / "wiki"
LIBS = REPO_ROOT / "libs"
RESERVED = {"index.md", "log.md"}
DEFAULT_REFRESH_DAYS = 30
DECISION_STATUSES = {"proposed", "accepted", "rejected", "superseded", "reversed"}
# --------------------------------------------------------------------------
# tiny YAML readers (stdlib only — this template ships without dependencies)
# --------------------------------------------------------------------------
def parse_frontmatter(text):
"""Return (dict, body, error). `error` is a string when the frontmatter is
present but unparseable, else None. Flat `key: value` pairs only."""
if not text.startswith("---\n"):
return {}, text, None
end = text.find("\n---\n", 4)
if end == -1:
return {}, text, "frontmatter opened with `---` but never closed"
raw, body = text[4:end], text[end + 5 :]
fm = {}
for lineno, line in enumerate(raw.split("\n"), start=2):
stripped = line.strip()
if not stripped or stripped.startswith("#"):
continue
if line[:1].isspace():
return {}, body, f"line {lineno}: nested/indented YAML is not supported in page frontmatter"
if ":" not in stripped:
return {}, body, f"line {lineno}: not a `key: value` pair: {stripped!r}"
key, _, value = stripped.partition(":")
fm[key.strip()] = unquote(value.strip())
return fm, body, None
def unquote(value):
if len(value) >= 2 and value[0] == value[-1] and value[0] in ("'", '"'):
return value[1:-1]
return value
def parse_simple_yaml(text):
"""Two-level `key: value` / `key:` + indented block YAML, enough for
source.yaml and source.local.yaml. Returns a dict; nested blocks become
nested dicts."""
out, current = {}, None
for line in text.split("\n"):
if not line.strip() or line.strip().startswith("#"):
continue
indented = line[:1].isspace()
stripped = line.strip()
if ":" not in stripped:
continue
key, _, value = stripped.partition(":")
key, value = key.strip(), unquote(value.split(" #", 1)[0].strip())
if indented:
if isinstance(current, dict):
current[key] = value
continue
if value == "":
current = {}
out[key] = current
else:
out[key] = value
current = None
# `key:` with nothing indented under it is an empty scalar, not a block.
return {k: ("" if v == {} else v) for k, v in out.items()}
def as_float(value):
try:
return float(value)
except (TypeError, ValueError):
return None
def as_int(value):
try:
return int(str(value).strip())
except (TypeError, ValueError):
return None
def as_date(value):
try:
return datetime.strptime(str(value).strip(), "%Y-%m-%d").date()
except (TypeError, ValueError):
return None
# --------------------------------------------------------------------------
# tree model
# --------------------------------------------------------------------------
LINK_RE = re.compile(r"\[[^\]]*\]\(([^)]+)\)")
WIKILINK_RE = re.compile(r"\[\[([^\]]+)\]\]")
SOURCE_BULLET_RE = re.compile(r"^\s*[-*]\s+`([^`]+)`(.*)$", re.M)
FINGERPRINT_RE = re.compile(r"\b(sha256|etag|mtime):([^\s,)]+)")
# A Crux block is attributed by an em-dash line under it. Two shapes matter:
# any attribution at all (a chat, a person, a meeting \u2014 correct but unverifiable),
# and a backticked local path, which is the only kind a quote can be checked against.
ATTRIBUTION_LINE_RE = re.compile(r"^\s*(?:\u2014|--)\s+(\S.*)$", re.M)
ATTRIBUTION_RE = re.compile(r"^\s*[\u2014-]\s*`([^`]+)`", re.M)
# Text-ish sources a quote can actually be checked against byte-for-byte.
# Anything else (pdf, docx, audio) is fingerprinted but never quote-verified.
QUOTABLE_SUFFIXES = {".md", ".txt", ".eml", ".csv", ".json", ".yaml", ".yml", ".html", ".rst", ".log"}
class Doc:
def __init__(self, root, path):
self.path = path
self.rel = path.relative_to(root)
text = path.read_text(encoding="utf-8", errors="replace")
self.fm, self.body, self.fm_error = parse_frontmatter(text)
self.reserved = path.name in RESERVED
def links(self):
"""Every intra-tree link target as a path relative to the tree root."""
out = set()
for target in LINK_RE.findall(self.body):
target = target.split("#", 1)[0].strip()
if not target or re.match(r"^[a-z][a-z0-9+.-]*:", target):
continue
if target.startswith("/wiki/"):
out.add(target[len("/wiki/") :])
elif target.startswith("/"):
out.add(target.lstrip("/"))
else:
try:
resolved = (self.rel.parent / target).as_posix()
except ValueError:
continue
parts = []
for part in resolved.split("/"):
if part == "..":
if parts:
parts.pop()
elif part not in (".", ""):
parts.append(part)
out.add("/".join(parts))
return out
def wikilinks(self):
return {w.split("|", 1)[-1].strip() for w in WIKILINK_RE.findall(self.body)}
def read_tree(root):
docs = []
for path in sorted(root.rglob("*.md")):
if any(part.startswith(".") for part in path.relative_to(root).parts):
continue
docs.append(Doc(root, path))
return docs
# --------------------------------------------------------------------------
# checks (each returns a list of finding strings)
# --------------------------------------------------------------------------
def check_conformance(docs):
findings = []
for doc in docs:
if doc.reserved:
continue
if doc.fm_error:
findings.append(f"{doc.rel}: unparseable frontmatter — {doc.fm_error}")
elif not doc.fm:
findings.append(f"{doc.rel}: no frontmatter")
elif not doc.fm.get("type", "").strip():
findings.append(f"{doc.rel}: missing or empty `type`")
return findings
def check_freshness(docs, today):
findings = []
for doc in docs:
if doc.reserved or doc.fm_error:
continue
window = as_int(doc.fm.get("freshness_window_days"))
updated = as_date(doc.fm.get("last_updated"))
if window is None or updated is None:
if doc.fm and doc.fm.get("last_updated") and updated is None:
findings.append(f"{doc.rel}: `last_updated` is not a YYYY-MM-DD date: {doc.fm['last_updated']!r}")
continue
age = (today - updated).days
if age > window:
findings.append(f"{doc.rel}: stale — {age}d since last_updated, window is {window}d ({age - window}d over)")
return findings
def check_confidence(docs):
findings = []
for doc in docs:
if doc.reserved or doc.fm_error or "confidence" not in doc.fm:
continue
value = as_float(doc.fm["confidence"])
if value is None:
findings.append(f"{doc.rel}: `confidence` is not a number: {doc.fm['confidence']!r}")
elif value < 0.3:
findings.append(f"{doc.rel}: confidence {value} is below 0.3 — flag for re-review")
return findings
def check_retention(docs, today):
findings = []
for doc in docs:
if doc.reserved or doc.fm_error:
continue
if doc.fm.get("retention", "").strip().lower() != "low":
continue
window = as_int(doc.fm.get("freshness_window_days"))
updated = as_date(doc.fm.get("last_updated"))
if window is None or updated is None:
continue
age = (today - updated).days
if age > 2 * window:
findings.append(
f"{doc.rel}: archive candidate — retention: low, {age}d old, 2x window is {2 * window}d"
)
return findings
def check_decisions(docs, root, today):
"""Decision-record specific rules (see the ckb-decide skill)."""
findings = []
decisions = [d for d in docs if not d.reserved and not d.fm_error
and d.fm.get("type", "").strip().lower() == "decision"]
by_path = {d.rel.as_posix(): d for d in decisions}
seen_numbers = {}
for doc in sorted(decisions, key=lambda d: d.rel.as_posix()):
rel = doc.rel.as_posix()
status = doc.fm.get("status", "").strip().lower()
if not status:
findings.append(f"{rel}: decision has no `status`")
elif status not in DECISION_STATUSES:
findings.append(
f"{rel}: `status: {status}` is not one of {', '.join(sorted(DECISION_STATUSES))}"
)
decided_on = as_date(doc.fm.get("decided_on"))
if status in ("accepted", "rejected", "reversed"):
if not doc.fm.get("decided_on"):
findings.append(f"{rel}: `status: {status}` but no `decided_on` date")
elif decided_on is None:
findings.append(f"{rel}: `decided_on` is not a YYYY-MM-DD date: {doc.fm['decided_on']!r}")
if decided_on and decided_on > today:
findings.append(f"{rel}: `decided_on` is in the future: {decided_on.isoformat()}")
if not doc.fm.get("decided_by", "").strip():
findings.append(f"{rel}: no `decided_by` — record `unknown` rather than omitting it")
review = doc.fm.get("review_on")
if review:
review_date = as_date(review)
if review_date is None:
findings.append(f"{rel}: `review_on` is not a YYYY-MM-DD date: {review!r}")
elif review_date <= today:
findings.append(
f"{rel}: due for review — `review_on: {review_date.isoformat()}` "
f"passed {(today - review_date).days}d ago"
)
# Supersession links must resolve and must be reciprocal.
for field, mirror in (("supersedes", "superseded_by"), ("superseded_by", "supersedes")):
target = doc.fm.get(field, "").strip()
if not target:
continue
key = target[len("/wiki/") :] if target.startswith("/wiki/") else target.lstrip("/")
other = by_path.get(key)
if other is None:
if not (root / key).is_file():
findings.append(f"{rel}: `{field}: {target}` does not resolve to a page")
continue
back = other.fm.get(mirror, "").strip()
back_key = back[len("/wiki/") :] if back.startswith("/wiki/") else back.lstrip("/")
if back_key != rel:
findings.append(
f"{rel}: `{field}` points at {key}, but that page's `{mirror}` "
f"does not point back ({back or 'unset'}) — supersession must be two-sided"
)
if status in ("superseded", "reversed") and not doc.fm.get("superseded_by", "").strip():
findings.append(f"{rel}: `status: {status}` but no `superseded_by` naming what replaced it")
if doc.fm.get("superseded_by", "").strip() and status not in ("superseded", "reversed"):
findings.append(
f"{rel}: has `superseded_by` but `status: {status or 'unset'}` — "
"expected `superseded` or `reversed`"
)
for target in [t.strip() for t in doc.fm.get("affects", "").split(",") if t.strip()]:
key = target[len("/wiki/") :] if target.startswith("/wiki/") else target.lstrip("/")
if not (root / key).is_file():
findings.append(f"{rel}: `affects` entry does not resolve to a page: {target}")
m = re.match(r"^(\d{4})-", doc.rel.name)
if m:
seen_numbers.setdefault(m.group(1), []).append(rel)
else:
findings.append(f"{rel}: decision filename does not start with a four-digit number")
for number, paths in sorted(seen_numbers.items()):
if len(paths) > 1:
findings.append(f"decision number {number} used by more than one page: {', '.join(sorted(paths))}")
return findings
def check_orphans(docs):
inbound = set()
titles = {}
for doc in docs:
rel = doc.rel.as_posix()
titles[rel] = rel
stem = doc.rel.with_suffix("").as_posix()
titles[stem] = rel
for doc in docs:
for target in doc.links():
if target in titles:
inbound.add(titles[target])
for wl in doc.wikilinks():
key = wl[:-3] if wl.endswith(".md") else wl
if key in titles:
inbound.add(titles[key])
findings = []
for doc in docs:
rel = doc.rel.as_posix()
if doc.reserved or rel in inbound:
continue
findings.append(f"{rel}: no inbound links from anywhere in the tree")
return findings
def check_graph(root, docs):
findings = []
edges_path = root / "graph" / "edges.json"
if not edges_path.is_file():
return findings
try:
data = json.loads(edges_path.read_text(encoding="utf-8"))
except json.JSONDecodeError as exc:
return [f"graph/edges.json: invalid JSON — {exc}"]
edges = data.get("edges", data) if isinstance(data, dict) else data
if not isinstance(edges, list):
return ["graph/edges.json: `edges` is not a list"]
known = {doc.rel.as_posix() for doc in docs}
known |= {doc.rel.with_suffix("").as_posix() for doc in docs}
for i, edge in enumerate(edges):
if not isinstance(edge, dict):
findings.append(f"graph/edges.json: edge {i} is not an object")
continue
for side in ("from", "to"):
value = str(edge.get(side, "")).strip()
if not value:
findings.append(f"graph/edges.json: edge {i} has no `{side}`")
continue
# Edge paths are project-root-absolute per Rule C
# (`/wiki/entities/foo.md`), while `known` holds paths relative to
# wiki/. Strip the prefix the same way the decision-record check
# above already does, or every conformant edge reads as broken.
stripped = value[len("/wiki/"):] if value.startswith("/wiki/") else value.lstrip("/")
candidates = {
value,
value.removesuffix(".md"),
stripped,
stripped.removesuffix(".md"),
f"entities/{value}",
f"entities/{value}".removesuffix(".md"),
}
if not candidates & known:
findings.append(f"graph/edges.json: edge {i} `{side}: {value}` does not resolve to a page")
return findings
def check_index_and_logs(root, docs):
findings = []
by_dir = {}
for doc in docs:
by_dir.setdefault(doc.rel.parent, []).append(doc)
for directory, entries in sorted(by_dir.items()):
pages = [d for d in entries if not d.reserved]
index = next((d for d in entries if d.path.name == "index.md"), None)
if not pages:
continue
if index is None:
findings.append(f"{(directory / 'index.md').as_posix()}: missing — directory holds {len(pages)} page(s)")
continue
listed = {Path(t).name for t in index.links()} | {
(w if w.endswith(".md") else w + ".md").split("/")[-1] for w in index.wikilinks()
}
for page in sorted(pages, key=lambda d: d.rel.as_posix()):
if page.path.name not in listed:
findings.append(f"{index.rel.as_posix()}: does not list {page.rel.as_posix()}")
# A change must have exactly one home log (Recursive Index & Log Convention).
logs = [d for d in docs if d.path.name == "log.md"]
root_log = next((d for d in logs if d.rel == Path("log.md")), None)
if root_log is not None and len(logs) > 1:
root_entries = log_entry_keys(root_log.body)
for sub in logs:
if sub is root_log:
continue
for key in sorted(log_entry_keys(sub.body) & root_entries):
findings.append(
f"log.md and {sub.rel.as_posix()}: same change recorded in both — {key}"
)
return findings
LOG_HEADER_RE = re.compile(
r"^##\s*\[?(\d{4}-\d{2}-\d{2}(?:[ T]\d{2}:\d{2})?)\]?(?:\s*-\s*\[?([A-Za-z ]+)\]?)?"
)
def log_entry_keys(body):
"""Timestamp + affected-files pairs, used to spot a change logged twice.
A `POINTER` is the Rule B shape for a change the decisions log absorbed, so
it is deliberately not a key: it is meant to coexist with the full entry.
"""
keys, stamp = set(), None
for line in body.split("\n"):
m = LOG_HEADER_RE.match(line.strip())
if m:
action = (m.group(2) or "").strip().upper()
stamp = None if action == "POINTER" else m.group(1)
continue
f = re.match(r"^-\s*\*\*File Affected:?\*\*:?\s*(.+)$", line.strip())
if f and stamp:
keys.add(f"{stamp} {f.group(1).strip()}")
return keys
def check_sources(today):
"""source.yaml validity plus overdue-index reporting for connector libs."""
findings, connectors = [], []
if not LIBS.is_dir():
return findings, connectors
for lib in sorted(p for p in LIBS.iterdir() if p.is_dir()):
source = lib / "source.yaml"
if not source.is_file():
continue # git-copy lib — never touched by lint
connectors.append(lib)
cfg = parse_simple_yaml(source.read_text(encoding="utf-8"))
name = lib.name
for key in ("connector", "location"):
if not str(cfg.get(key, "")).strip():
findings.append(f"libs/{name}/source.yaml: `{key}` is missing or empty")
index_block = cfg.get("index")
if isinstance(index_block, dict):
for key in ("store", "location"):
if not str(index_block.get(key, "")).strip():
findings.append(f"libs/{name}/source.yaml: `index.{key}` is missing or empty")
refresh = cfg.get("refresh_interval_days")
interval = DEFAULT_REFRESH_DAYS
if refresh is not None and not isinstance(refresh, dict):
parsed = as_int(refresh)
if parsed is None or parsed <= 0:
findings.append(f"libs/{name}/source.yaml: `refresh_interval_days` is not a positive integer: {refresh!r}")
else:
interval = parsed
generated = {"index.md", "log.md", "entities", "graph", "source.yaml", "source.local.yaml"}
stray = [
p.name
for p in sorted(lib.iterdir())
if p.name not in generated and not p.name.startswith(".")
]
if stray:
findings.append(
f"libs/{name}/: has both a source.yaml and non-index content ({', '.join(stray)}) — "
"ambiguous configuration for the user to resolve"
)
newest = None
for md in lib.rglob("*.md"):
fm, _, err = parse_frontmatter(md.read_text(encoding="utf-8", errors="replace"))
if err:
continue
updated = as_date(fm.get("last_updated"))
if updated and (newest is None or updated > newest):
newest = updated
if newest is None:
findings.append(f"libs/{name}/: no generated index yet — run 'index external sources'")
else:
age = (today - newest).days
if age > interval:
findings.append(
f"libs/{name}/: index is {age}d old against a {interval}d refresh interval "
f"({age - interval}d overdue) — suggest 'index external sources'"
)
return findings, connectors
# --------------------------------------------------------------------------
# driver
# --------------------------------------------------------------------------
def sections(body):
"""Split a page body into {heading: text} for `##`-level headings."""
out, current, buf = {}, None, []
for line in body.split("\n"):
match = re.match(r"^##\s+(.+?)\s*$", line)
if match:
if current is not None:
out[current] = "\n".join(buf)
current, buf = match.group(1).strip(), []
elif current is not None:
buf.append(line)
if current is not None:
out[current] = "\n".join(buf)
return out
def digest(path):
"""First 8 hex chars of the file's sha256, or None if unreadable."""
try:
return hashlib.sha256(path.read_bytes()).hexdigest()[:8]
except OSError:
return None
def source_bullets(body):
"""[(cited path, kind, value)] from a page's `## Sources` section."""
section = sections(body).get("Sources")
if section is None:
return None
out = []
for cited, rest in SOURCE_BULLET_RE.findall(section):
fp = FINGERPRINT_RE.search(rest)
out.append((cited.strip(), fp.group(1) if fp else None, fp.group(2) if fp else None))
return out
def check_evidence(docs, root):
"""Check 12 — `## Sources` fingerprints against the files they cite."""
findings = []
for doc in docs:
if doc.reserved or doc.fm_error:
continue
bullets = source_bullets(doc.body)
if bullets is None:
continue
if not bullets:
findings.append(f"{doc.rel}: `## Sources` section is empty")
continue
for cited, kind, value in bullets:
if re.match(r"^[a-z][a-z0-9+.-]*://", cited):
continue # a URL: nothing local to hash
target = (REPO_ROOT / cited.lstrip("/")).resolve()
if not target.exists():
target = (root / cited.lstrip("/")).resolve()
if target.is_dir():
continue # a subtree: legal to cite, but no single digest to recompute
if not target.is_file():
findings.append(f"{doc.rel}: cited source `{cited}` does not exist")
continue
if kind is None:
findings.append(f"{doc.rel}: cited source `{cited}` has no fingerprint recorded")
continue
if kind != "sha256":
continue # etag/mtime come from a connector; nothing local to recompute
actual = digest(target)
if actual is None:
findings.append(f"{doc.rel}: cited source `{cited}` could not be read")
elif not value.lower().startswith(actual):
findings.append(
f"{doc.rel}: source `{cited}` CHANGED since this page was built "
f"(recorded sha256:{value}, now sha256:{actual})"
)
return findings
def crux_blocks(crux):
"""Split a `## Crux` section into [(quote_text, ref)].
A block is one or more consecutive `>` lines. The attribution line that
follows a block attributes it (and any unattributed blocks before it),
so each quote is only ever checked against its own source. `ref` is:
a path — attributed to a backticked local path, so quote-verifiable
"" — attributed to something unverifiable here (a chat, a person,
a meeting). Correct and complete; nothing to check against.
None — no attribution line at all, which is the actual defect.
"""
blocks, pending, lines = [], [], []
def flush():
if lines:
pending.append(" ".join(l[1:].strip() for l in lines).strip())
lines.clear()
for line in crux.split("\n"):
if line.startswith(">"):
lines.append(line)
continue
flush()
attr = ATTRIBUTION_RE.match(line)
if attr is None and ATTRIBUTION_LINE_RE.match(line):
ref = "" # attributed, but not to anything checkable from here
elif attr:
ref = attr.group(1)
else:
continue
blocks.extend((q, ref) for q in pending if q)
pending.clear()
flush()
blocks.extend((q, None) for q in pending if q)
return blocks
def check_crux(docs, root):
"""Check 13 — `## Crux` quotes are verbatim, attributed, and non-empty."""
findings = []
for doc in docs:
if doc.reserved or doc.fm_error:
continue
secs = sections(doc.body)
crux = secs.get("Crux")
if crux is None:
continue
blocks = crux_blocks(crux)
if not blocks:
findings.append(f"{doc.rel}: `## Crux` has no quoted lines (evidence sections must quote, not paraphrase)")
continue
if "Sources" not in secs:
findings.append(f"{doc.rel}: `## Crux` present but the page has no `## Sources` to attribute it to")
for quote, ref in blocks:
needle = " ".join(quote.split())
if ref is None:
findings.append(
f"{doc.rel}: `## Crux` quote is not attributed to a source — {needle[:60]!r}..."
)
continue
ref = ref.strip().lstrip("/")
if not ref:
continue # attributed to a chat or a person: nothing local to verify
target = (REPO_ROOT / ref).resolve()
if not target.is_file():
target = (root / ref).resolve()
if not target.is_file() or target.suffix.lower() not in QUOTABLE_SUFFIXES:
continue
try:
haystack = " ".join(target.read_text(encoding="utf-8", errors="replace").split())
except OSError:
continue
if len(needle) < 24:
continue # too short to match meaningfully
if needle not in haystack:
findings.append(
f"{doc.rel}: `## Crux` quote not found verbatim in `{ref}` — "
f"{needle[:60]!r}..."
)
return findings
# --------------------------------------------------------------------------
# review (check 17), contradictions (check 18), tags (check 19) — schema 1.6
# --------------------------------------------------------------------------
REVIEW_STATES = {"draft", "reviewed", "needs_update"}
CONTRADICTION_RE = re.compile(r"^>\s*CONTRADICTION:\s*(.*)$", re.M)
TAG_ROW_RE = re.compile(r"^\|\s*`([^`]+)`\s*\|", re.M)
def check_review(docs):
"""Check 17 — the review fields are consistent. A draft is not a finding;
a reviewed page edited after its review is."""
findings = []
for doc in docs:
if doc.reserved or doc.fm_error or "review" not in doc.fm:
continue
rel, state = doc.rel.as_posix(), doc.fm.get("review", "").strip().lower()
if state not in REVIEW_STATES:
findings.append(f"{rel}: `review: {state}` is not one of {', '.join(sorted(REVIEW_STATES))}")
continue
if state != "reviewed":
continue
on = as_date(doc.fm.get("reviewed_on"))
if not doc.fm.get("reviewed_by", "").strip():
findings.append(f"{rel}: `review: reviewed` but no `reviewed_by`")
if on is None:
findings.append(f"{rel}: `review: reviewed` but no valid `reviewed_on` date")
continue
updated = as_date(doc.fm.get("last_updated"))
if updated and updated > on:
findings.append(f"{rel}: changed since its review (last_updated {updated.isoformat()}, "
f"reviewed_on {on.isoformat()}) — set `review: needs_update`, or review it again")
return findings
def review_queue(docs):
"""Pages awaiting a person: not findings, a to-do list."""
return [f"{d.rel.as_posix()} ({d.fm['review'].strip().lower()})" for d in docs
if not d.reserved and not d.fm_error
and d.fm.get("review", "").strip().lower() in ("draft", "needs_update")]
def check_contradictions(docs):
"""Check 18 — every open `> CONTRADICTION:` marker, until a person resolves it."""
findings = []
for doc in docs:
if doc.reserved:
continue
for m in CONTRADICTION_RE.finditer(doc.body):
findings.append(f"{doc.rel.as_posix()}: open contradiction — {m.group(1).strip()[:120]}")
return findings
def tag_vocabulary(root):
"""Tags listed in `tags.md` (a table whose first cell is a backticked tag), or None."""
path = root / "tags.md"
if not path.is_file():
return None
return {t.strip().lower() for t in TAG_ROW_RE.findall(path.read_text(encoding="utf-8", errors="replace"))}
def page_tags(doc):
return [t.strip().lower() for t in doc.fm.get("tags", "").strip("[]").split(",") if t.strip()]
def check_tags(root, docs):
"""Check 19 — every `tags:` value is in the tree's vocabulary (`tags.md`)."""
findings, vocab = [], tag_vocabulary(root)
for doc in docs:
if doc.reserved or doc.fm_error:
continue
tags = page_tags(doc)
if not tags:
continue
if vocab is None:
findings.append(f"{doc.rel.as_posix()}: has `tags` but the tree has no tags.md vocabulary")
continue
for tag in tags:
if tag not in vocab:
findings.append(f"{doc.rel.as_posix()}: tag `{tag}` is not in tags.md — add it there or drop it")
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():
"""`.secrets-allow`, one entry per line, two shapes:
<path> <line hash> this one line, while its text is unchanged
<path glob> match:<hash> every occurrence of one matched string in the
matching files — for a transcript that grows
Returns ({(path, line hash)}, [(glob, match hash)])."""
path = REPO_ROOT / SECRETS_ALLOW
lines, matches = set(), []
if not path.is_file():
return lines, matches
for raw in path.read_text(encoding="utf-8", errors="replace").splitlines():
parts = raw.split("#", 1)[0].split()
if len(parts) != 2:
continue
where, h = parts[0].lstrip("/"), parts[1].lower()
if h.startswith("match:"):
matches.append((where, h[len("match:"):]))
else:
lines.add((where, h))
return lines, matches
def match_hash(text):
return hashlib.sha256(text.encode("utf-8")).hexdigest()[:8]
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, allowed_matches) = [], 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", text[key.start():m.end()]))
if not hits:
continue
lines = text.split("\n")
for n, (label, match) in sorted(hits.items()):
h, mh = line_hash(lines[n - 1]), match_hash(match)
if (rel, h) in allowed or any(mh == want and fnmatch.fnmatch(rel, glob)
for glob, want in allowed_matches):
continue
findings.append(f"{rel}:{n}: possible {label} ({match[:4]}…) "
f"— if harmless, add `{rel} {h}` (this line) or `{rel} match:{mh}` "
f"(this string, every line) 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
ACCESS_LOG = Path("tmp") / "access.log"
DEFAULT_COLD_DAYS = 90
COLD_EXEMPT = {"overview.md", "error-book.md", "query-gaps.md", "tags.md", "lessons.md"}
def cold_pages(today, days):
"""Proposals, never moves: wiki pages absent from tmp/access.log for `days`.
The log is per machine (tmp/ is gitignored), so this is one person's view."""
log = REPO_ROOT / ACCESS_LOG
if not log.is_file():
return None, "no access log yet — ckb-retrieve writes tmp/access.log as pages are read"
last, first = {}, None
for line in log.read_text(encoding="utf-8", errors="replace").splitlines():
d, _, path = line.partition("\t")
when = as_date(d)
if when is None or not path:
continue
first = when if first is None or when < first else first
key = path.strip().lstrip("/").removeprefix("wiki/")
last[key] = max(last.get(key, when), when)
if first is None or (today - first).days < days:
covered = (today - first).days if first else 0
return None, f"access log covers {covered}d; a {days}d cold check needs at least that much history"
out = []
for doc in read_tree(WIKI):
rel = doc.rel.as_posix()
if (doc.reserved or doc.fm_error or rel in COLD_EXEMPT
or doc.fm.get("type", "").strip().lower() in ("decision", "vocabulary", "lessons")
or doc.fm.get("retention", "").strip().lower() == "high"):
continue # infrastructure, history, rules in force, and pages marked worth keeping
seen = last.get(rel)
if seen is None or (today - seen).days > days:
when = f"last read {seen.isoformat()}" if seen else "never read on this machine"
out.append(f"{rel} ({when}, retention: {doc.fm.get('retention', 'unset')}) — "
f"propose moving its row to a `## Archive` section of {(doc.rel.parent / 'index.md').as_posix()}")
return out, None
CHECKS = [
("1 conformance", "conformance"),
("2 freshness", "freshness"),
("3 confidence", "confidence"),
("4 retention", "retention"),
("5 decisions", "decisions"),
("6 orphans", "orphans"),
("7 graph", "graph"),
("8 index/log", "index_log"),
("12 source fingerprints", "evidence"),
("13 crux", "crux"),
("17 review", "review"),
("18 contradictions", "contradictions"),
("19 tags", "tags"),
]
# The subset worth running at session start (Rule E): cheap, and each finding
# 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):
docs = read_tree(root)
return {
"label": label,
"documents": len(docs),
"conformance": check_conformance(docs),
"freshness": check_freshness(docs, today),
"confidence": check_confidence(docs),
"retention": check_retention(docs, today),
"decisions": check_decisions(docs, root, today),
"orphans": check_orphans(docs),
"graph": check_graph(root, docs),
"index_log": check_index_and_logs(root, docs),
"evidence": check_evidence(docs, root),
"crux": check_crux(docs, root),
"review": check_review(docs),
"contradictions": check_contradictions(docs),
"tags": check_tags(root, docs),
"review_queue": review_queue(docs),
"hubs": in_degree(root, docs),
}
def in_degree(root, docs):
"""Top pages by inbound edge count — not a finding, a retrieval signal.
`ckb-retrieve` fuses in-degree as one ranked list among several; surfacing
it here means the same number comes from one place rather than being
recomputed by eye at query time.
"""
edges_path = root / "graph" / "edges.json"
if not edges_path.is_file():
return []
try:
data = json.loads(edges_path.read_text(encoding="utf-8"))
except json.JSONDecodeError:
return []
edges = data.get("edges", data) if isinstance(data, dict) else data
if not isinstance(edges, list):
return []
counts = {}
for edge in edges:
if not isinstance(edge, dict):
continue
target = str(edge.get("to", "")).strip()
if target:
counts[target] = counts.get(target, 0) + 1
return sorted(counts.items(), key=lambda kv: (-kv[1], kv[0]))[:10]
def main():
parser = argparse.ArgumentParser(description="Read-only mechanical checks for ckb-lint.")
parser.add_argument("--scope", choices=("wiki", "libs", "all"), default="all")
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, 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")
parser.add_argument("--cold", nargs="?", type=int, const=DEFAULT_COLD_DAYS, metavar="DAYS",
help="propose demoting pages nobody read for DAYS (default 90), from tmp/access.log")
args = parser.parse_args()
today = as_date(args.today) if args.today else date.today()
if today is None:
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.cold is not None:
found, why = cold_pages(today, args.cold)
if found is None:
print(f"cold: {why}")
return 0
for item in found:
print(f"- {item}")
print(f"cold: {len(found)} page(s) unread for over {args.cold}d — proposals only; never rename or delete")
return 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():
print(f"error: no wiki/ directory under {REPO_ROOT} — run from the repository root", file=sys.stderr)
return 2
trees.append(run_tree(WIKI, today, "wiki/"))
if args.scope in ("libs", "all"):
source_findings, connectors = check_sources(today)
for lib in connectors:
access = "read-only"
local = lib / "source.local.yaml"
if local.is_file():
cfg = parse_simple_yaml(local.read_text(encoding="utf-8"))
if str(cfg.get("access", "")).strip().lower() == "write":
access = "write"
tree = run_tree(lib, today, f"libs/{lib.name}/ (access: {access})")
tree["access"] = access
trees.append(tree)
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}
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
print("ckb check: " + ", ".join(flagged) + " — run \"lint\" for detail")
return 1
if args.json:
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:
print(f"=== {tree['label']} — {tree['documents']} markdown file(s)")
for title, key in CHECKS:
items = tree[key]
if not items:
continue
print(f" [{title}] {len(items)} finding(s)")
for item in items:
print(f" - {item}")
if not any(tree[key] for _, key in CHECKS):
print(" clean")
if tree["hubs"]:
top = ", ".join(f"{name} ({n})" for name, n in tree["hubs"][:5])
print(f" [in-degree] most-referenced pages: {top}")
if tree["review_queue"]:
shown = ", ".join(tree["review_queue"][:8]) + (" …" if len(tree["review_queue"]) > 8 else "")
print(f" [review queue] {len(tree['review_queue'])} page(s) await a person: {shown}")
if args.scope in ("libs", "all"):
print("=== external sources (libs/*/source.yaml)")
if source_findings:
for item in source_findings:
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")
print("note: a changed source fingerprint (check 12) or a diverged crux quote (check 13) "
"means the evidence moved, not that a page merely aged — read those first")
return 1 if total else 0
if __name__ == "__main__":
sys.exit(main())