- 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>
1203 lines
50 KiB
Python
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())
|