Template 1.23.0: agent-knowledge release 2, schema 1.6

Schema 1.6, all fields optional (D-0014):
- F7 review: `review: draft|reviewed|needs_update`, `reviewed_by`,
  `reviewed_on`; lint check 17 and a review queue; ckb-lint marks reviews
- F4 `> CONTRADICTION:` marker, lint check 18; validity dates deferred
- F21 `tags` against the new `wiki/tags.md`, lint check 19,
  retrieve_candidates.py --tag, DRAFT/NEEDS_UPDATE flags
- F9 profiles in workload/profiles/, protected `## Rules` on project
  scope pages, precedence AGENTS.md > Rules > profile
- F8 explicit lessons (profile or wiki/lessons.md); new ckb-profile skill

Carry-over: `.secrets-allow` `<glob> match:<hash>` entries (also in the
bash/PowerShell fallbacks); open threads no longer print twice.
ckb-upgrade migrates 1.5 -> 1.6; init/reset know tags.md; Starlight
shows review and tags. Smoke test covers a 1.6 KB. Docs in EN and PL.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Michał Kopeć 2026-11-02 20:06:02 +01:00
parent aaeabf3071
commit bf2cc8e8aa
32 changed files with 901 additions and 50 deletions

View file

@ -181,6 +181,11 @@ entity page, write the name as plain text and mention the gap in your report
in `affects`), and `supersedes` (new decision → old decision) where
applicable. Skip any edge whose target page doesn't exist rather than
pointing at a page you'd have to invent.
- **An open contradiction it settles** — when the decision resolves a
`> CONTRADICTION:` marker (lint check 18), update the claim on that page
to match the decision, replace the marker with a link to the decision,
and leave the page at `review: needs_update`. That edit is a `wiki/` page
change, so it gets its own `wiki/log.md` entry.
### Step 5 — Log it, then report

View file

@ -80,7 +80,7 @@ The script prints, and you should summarize back to the user:
| `tldr` | `description` | rename |
| `resource` | `resource` | passthrough |
| `last_updated` | `timestamp` | passthrough as-is (bare `YYYY-MM-DD` is valid ISO 8601 — no time-of-day is fabricated) |
| `confidence`, `quality`, `retention`, `supersedes`, `superseded_by`, `freshness_window_days`, `source_fingerprint`, `source_checked` | same keys | passthrough as OKF extension fields, which consumers must tolerate |
| `confidence`, `quality`, `retention`, `supersedes`, `superseded_by`, `freshness_window_days`, `source_fingerprint`, `source_checked`, and from schema 1.6 `review`, `reviewed_by`, `reviewed_on`, `tags` | same keys | passthrough as OKF extension fields, which consumers must tolerate |
| `kb_schema_version` | *(dropped)* | the root `index.md`'s frontmatter is spec-limited to `okf_version`; this key has no valid home in the bundle |
| *(none)* | `tags` | omitted — no source field to derive it from |

View file

@ -85,13 +85,14 @@ The script prints, and you should summarize back to the user:
becomes Starlight's required `title` (and is removed from the body, since
Starlight renders `title` as the page heading itself — leaving the H1 in
would duplicate it). `type`/`confidence`/`quality`/`retention`/
`last_updated`/`resource` have no native Starlight field, so they're
`last_updated`/`review`/`tags`/`resource` have no native Starlight field, so they're
rendered as a `:::note[Knowledge base metadata]` aside at the top of the
page body instead of being dropped.
- **Badges:** a page gets a `sidebar.badge` — "Superseded" (if
`superseded_by` is set), else "Stale" (if `last_updated` +
`freshness_window_days` has elapsed), else "Low confidence" (if
`confidence` < 0.5) — priority in that order, one badge max.
`freshness_window_days` has elapsed), else "Needs update" (if
`review: needs_update`), else "Low confidence" (if `confidence` < 0.5) —
priority in that order, one badge max.
- **Links:** dual-linked cross-references (`[text](path) ([[Wikilink]])`,
or the older `[[Wikilink]] / [text](path)` ordering) collapse to just the
markdown link, since Starlight has no wikilink concept. Bare `[[Wikilinks]]`

View file

@ -229,7 +229,7 @@ def build_metadata_block(fm, today):
meta_bits = []
for label, key in (("Type", "type"), ("Confidence", "confidence"),
("Quality", "quality"), ("Last updated", "last_updated"),
("Retention", "retention")):
("Retention", "retention"), ("Review", "review"), ("Tags", "tags")):
if fm.get(key):
meta_bits.append(f"**{label}:** {fm[key]}")
if meta_bits:
@ -269,6 +269,8 @@ def compute_badge(fm, today):
return {"text": "Stale", "variant": "caution"}
except ValueError:
pass
if fm.get("review", "").strip().lower() == "needs_update":
return {"text": "Needs update", "variant": "caution"}
try:
if fm.get("confidence") and float(fm["confidence"]) < 0.5:
return {"text": "Low confidence", "variant": "note"}

View file

@ -104,6 +104,10 @@ the notes. If the material only *references* a decision without recording
it ("as agreed last quarter, we use Postgres"), that's a query-gap candidate,
not a decision record — you don't have the rationale or the date.
When the material falls inside a project scope, read that scope page's
`## Rules` before writing and follow them; they are the team's, and this
skill never edits them.
For recurring teams, clients, systems, or initiatives, consider whether a
plain project scope page under `wiki/projects/<name>.md` would make future
queries easier to route. A scope page should list when to use it, included
@ -129,9 +133,17 @@ into:
- **Extends** — the new material adds detail the page doesn't have. Update
the page in Step 5.
- **Contradicts** — the new material and the page can't both be right. This
is the case worth catching: handle it as supersession (see Edge cases), and
say so explicitly in the report rather than letting the newer page silently
win.
is the case worth catching. When the new material clearly replaces the old
(a later version of the same document, a recorded decision), handle it as
supersession (see Edge cases). When it is not clear which is right, write a
marker into the affected page instead of choosing:
```markdown
> CONTRADICTION: retries 3 times (`raw/archive/2026-09-01/kickoff-notes.md`) vs retries 5 times (`raw/archive/2026-11-02/runbook.md`) — found 2026-11-02
```
and set the page to `review: needs_update`. Either way, say so explicitly
in the report rather than letting the newer page silently win.
- **Untouched** — most of the radius. Drop it and move on.
Name the owners too. Where an `owns` or `has_expertise_in` edge points at an
@ -164,6 +176,13 @@ gets frontmatter with:
- A `last_updated:` timestamp.
- A `freshness_window_days:` appropriate to the topic.
- A `retention:` level.
- `review: draft` on a page this run creates. On a page that is already
`review: reviewed`, a change to what it claims (prose, tables, `tldr`,
`## Sources`, `## Crux`) sets `review: needs_update`; leave `reviewed_by`
and `reviewed_on` as the record of the last review. New links, index rows
and formatting are not substance and leave `review` alone.
- `tags:` only when a tag in `wiki/tags.md` fits. Never invent one here: a
new tag is a row in the vocabulary first, and that is the user's call.
`type` is also required (per the page frontmatter schema in
`CLAUDE.md`/`AGENTS.md` page schema) — set it once, based on the entity/content
@ -328,7 +347,7 @@ started: HH:MM
## Blast radius
- **Confirmed:** …
- **Extended:** …
- **Contradicted:** `/wiki/entities/x.md` — superseded by … — review: Owner Name
- **Contradicted:** `/wiki/entities/x.md` — superseded by … / CONTRADICTION marker written — review: Owner Name
- **Query gaps closed:** …
## Not ingested

View file

@ -293,8 +293,8 @@ generic structure:
- **`wiki/index.md`** - frontmatter with `kb_schema_version` only, set to
whatever value the template source's own `wiki/index.md` carries (do not
hard-code it here - it moves with the schema).
Body: the routing table with just its four fixed infrastructure rows
(Overview, Log, Error Book, Entities, Graph) and no entity rows, plus the
Body: the routing table with just its fixed infrastructure rows
(Overview, Log, Error Book, Entities, Graph, Tags) and no entity rows, plus the
"## Entity Pages" section with its placeholder note. Use today's date
where the template needs one.
- **`wiki/overview.md`** - copy verbatim from this repo (it's already
@ -317,6 +317,10 @@ generic structure:
`ckb-decide` and `ckb-lint` both validate against it.
- **`wiki/decisions/log.md`** - header and explanation only, no entries.
- **`wiki/query-gaps.md`** - header + explanation only, no recorded gaps.
- **`wiki/tags.md`** - copy verbatim from this repo (frontmatter, the
explanation and an empty tag table). It is the KB's own vocabulary from
then on; `wiki/lessons.md` and `workload/profiles/` are created on first
use by `ckb-profile`, not here.
If the template source's `wiki/` holds scaffold files beyond this list,
carry them over the same way - empty, structure only. The list above is

View file

@ -1,6 +1,6 @@
---
name: ckb-lint
description: Health-check wiki/ — frontmatter conformance, freshness, confidence decay, retention, supersession, orphans, graph consistency, index/log drift, source-fingerprint drift, 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.
description: Health-check wiki/ — frontmatter conformance, freshness, confidence decay, retention, supersession, orphans, graph consistency, index/log drift, source-fingerprint drift, review status, open contradictions, tags, committed secrets, context budget — auto-fixing what is safe and reporting the rest. Also checks each connector-backed libs/<name>/ generated index, and marks pages reviewed. Use for "Lint", "health-check the wiki", "check the wiki", "what needs review", "mark X as reviewed", or a scheduled wiki health check.
---
# Lint skill
@ -53,7 +53,7 @@ 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, 13, 15 and 16 below — plus the structural half of check 5
3, 4, 6, 7, 8, 10, 12, 13 and 15–19 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
@ -322,6 +322,47 @@ 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.
### 17 — Review status (schema 1.6)
A page may carry `review: draft | reviewed | needs_update`, with
`reviewed_by` and `reviewed_on`. No `review` field means "not tracked".
Drafts are expected, so they are not findings. The script reports only
inconsistencies: an unknown value, a `reviewed` page without
`reviewed_by`/`reviewed_on`, and a `reviewed` page whose `last_updated` is
later than `reviewed_on`. For the last one, compare the page with its
previous version (`git log -p`); if what it claims changed, set
`review: needs_update`. If only links or formatting changed, say so and ask
the user to re-review.
The report also prints a **review queue**: every `draft` and `needs_update`
page. "What needs review?" is answered from it, `needs_update` first,
because those pages were reviewed once and have moved since.
**Marking a review** ("mark X as reviewed", "I've checked X"): only on the
person's say-so, and only for the pages they name. Set `review: reviewed`,
`reviewed_by` to the session identity's name and `reviewed_on` to today.
Leave `last_updated` alone, because the page itself did not change. Log it
under Rule B as `REVIEW`. Never mark a page reviewed that the person has
not said they read, and never mark a whole directory on a general "looks
fine".
### 18 — Open contradictions
Every `> CONTRADICTION:` line in a page body is listed until someone resolves
it. Never resolve one by picking a side yourself. Show both claims with their
sources and offer three routes: supersede one page (two-sided
`supersedes`/`superseded_by`), record a decision with `ckb-decide`, or edit
the claim the way the person decides. Then remove the marker, keep
`review: needs_update` until someone reviews the result, and log it.
### 19 — Tags
`tags:` values must appear in `wiki/tags.md`, a table whose first column
holds each tag in backticks. A page with an unknown tag is reported, never
auto-fixed: either the vocabulary gains a row (the user's call) or the page
drops the tag. A connector-backed lib is checked against its own `tags.md`
when it has one.
### Context budget
`--quick` and the full report flag an always-loaded layer — `AGENTS.md` plus

View file

@ -22,6 +22,9 @@ say what was skipped — by hand, this costs tokens.
| 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. |
| 17 | Review status | `rg -n '^review:' wiki` — values must be draft/reviewed/needs_update; for each `reviewed` page compare `last_updated` with `reviewed_on`. `rg -l '^review: (draft|needs_update)' wiki` is the review queue. |
| 18 | Contradictions | `rg -n '^> *CONTRADICTION:' wiki` — every hit is open until resolved. |
| 19 | Tags | `rg -n '^tags:' wiki` against the backticked first column of `wiki/tags.md`. |
| — | 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

View file

@ -128,10 +128,13 @@ foreach ($tree in $trees) {
$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 = @{}
$allowMatch = @() # `<glob> match:<hash>`: one matched string, every matching file
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 }
if ($parts.Count -ne 2) { continue }
if ($parts[1] -like 'match:*') { $allowMatch += ,@($parts[0].TrimStart('/'), $parts[1].Substring(6).ToLowerInvariant()); continue }
$allow["$($parts[0].TrimStart('/')) $($parts[1].ToLowerInvariant())"] = $true
}
}
$sha = [Security.Cryptography.SHA256]::Create()
@ -148,7 +151,11 @@ foreach ($top in @("wiki", "outputs", "workload", "raw")) {
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++ }
if ($allow.ContainsKey("$rel $h")) { continue }
$m = [regex]::Match($line, $secretRe).Value
$mh = (-join ($sha.ComputeHash([Text.Encoding]::UTF8.GetBytes($m)) | ForEach-Object { $_.ToString("x2") })).Substring(0, 8)
if ($allowMatch | Where-Object { $_[1] -eq $mh -and $rel -like $_[0] }) { continue }
$secrets++
}
}
}

View file

@ -145,6 +145,12 @@ if (( ${#scan[@]} )); then
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
# `<glob> match:<hash>` allows one matched string in every matching file.
m=$(printf '%s' "$line" | grep -oE -e "$SECRET_RE" | head -n1); mh=$(sha_str "$m"); allowed=0
while read -r glob want _; do
[[ "$want" == "match:$mh" && "$file" == ${glob#/} ]] && { allowed=1; break; }
done < <(sed 's/#.*//' .secrets-allow 2>/dev/null | grep 'match:' || true)
(( allowed )) && continue
secrets=$((secrets+1))
done < <(grep -rEn "${INCLUDES[@]}" -e "$SECRET_RE" "${scan[@]}" 2>/dev/null)
fi

View file

@ -35,6 +35,7 @@ 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
@ -698,6 +699,89 @@ def check_crux(docs, root):
)
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
# --------------------------------------------------------------------------
@ -741,22 +825,37 @@ def line_hash(line):
def secret_allowlist():
"""{(path, line hash)} from `.secrets-allow`: one `<path> <hash>` per line."""
"""`.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
allowed = set()
lines, matches = set(), []
if not path.is_file():
return allowed
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:
allowed.add((parts[0].lstrip("/"), parts[1].lower()))
return allowed
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 = [], secret_allowlist()
findings, (allowed, allowed_matches) = [], secret_allowlist()
for top in SECRET_SCAN_DIRS:
base = REPO_ROOT / top
if not base.is_dir():
@ -788,15 +887,18 @@ def check_secrets():
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)))
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 = 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}")
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
@ -874,6 +976,9 @@ CHECKS = [
("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
@ -900,6 +1005,10 @@ def run_tree(root, today, label):
"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),
}
@ -1016,6 +1125,9 @@ def main():
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:

View file

@ -16,6 +16,8 @@ What it prints, one line each (plus the tail of the latest workload note):
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
profile: workload/profiles/<slug>.md the session identity's own profile, printed; only when it exists
lessons: N new in wiki/lessons.md KB lessons dated after your previous workload note; 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.
@ -29,6 +31,7 @@ import os
import re
import subprocess
import sys
import unicodedata
from datetime import date, datetime
from pathlib import Path
@ -46,6 +49,11 @@ 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"
PROFILE_LINES = 40
LESSON_RE = re.compile(r"^###\s+(\d{4}-\d{2}-\d{2})\s+[—-]\s+(.+?)\s*$", re.M)
# Letters NFKD does not split into base + accent (Rule D: `Michał Kopeć` -> `michal-kopec`).
SLUG_MAP = str.maketrans({"ł": "l", "Ł": "L", "ø": "o", "Ø": "O", "đ": "d", "Đ": "D",
"ß": "ss", "æ": "ae", "Æ": "AE", "œ": "oe", "Œ": "OE"})
def run(cmd, cwd):
@ -73,6 +81,13 @@ def identity(root):
return f"{user} (OS user; git identity unset — set git config --global user.name / user.email)"
def author_slug(root):
"""The Rule D slug of the session identity's name, or None."""
name = run(["git", "config", "user.name"], root)[1] or os.environ.get("USER") or os.environ.get("USERNAME") or ""
ascii_name = unicodedata.normalize("NFKD", name.translate(SLUG_MAP)).encode("ascii", "ignore").decode()
return re.sub(r"[^a-z0-9]+", "-", ascii_name.lower()).strip("-") or None
def yaml_flag(root, block, key, default):
"""Minimal reader for `block:\\n key: value` in ckb.yaml; no YAML parser."""
path = root / "ckb.yaml"
@ -231,6 +246,46 @@ def threads_lines(root, today):
return out
def strip_frontmatter(text):
if text.startswith("---\n"):
end = text.find("\n---\n", 4)
if end != -1:
return text[end + 5:]
return text
def profile_lines(root, slug):
"""The session identity's profile, printed so it is in context; nothing when absent."""
path = root / "workload" / "profiles" / f"{slug}.md" if slug else None
if not path or not path.is_file():
return []
body = [l for l in strip_frontmatter(path.read_text(encoding="utf-8", errors="replace")).strip().splitlines()]
if len(body) > PROFILE_LINES:
body = body[:PROFILE_LINES] + [f"… (rest in {path.relative_to(root).as_posix()})"]
return [f"profile: {path.relative_to(root).as_posix()} — yours; follow it where AGENTS.md and "
"project rules leave room"] + [" " + l if l else "" for l in body]
def lessons_lines(root, slug, today):
"""KB lessons dated after this person's previous workload note (all of them
on a first session), so a lesson someone else recorded is not missed."""
path = root / "wiki" / "lessons.md"
if not path.is_file():
return []
lessons = LESSON_RE.findall(path.read_text(encoding="utf-8", errors="replace"))
prev = None
if slug and (root / "workload").is_dir():
dates = [f.name[:10] for f in (root / "workload").glob(f"*_{slug}_summary.md") if f.name[:10] < today.isoformat()]
prev = max(dates) if dates else None
new = [(d, t) for d, t in lessons if prev is None or d > prev]
if not new:
return []
since = f"since your note of {prev}" if prev else "— first session here"
out = [f"lessons: {len(new)} in wiki/lessons.md {since} -> read the ones that bear on this session"]
out += [f" - {d} — {t}" for d, t in new[-THREADS_SHOWN:]]
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, '')."""
@ -245,6 +300,8 @@ def latest_workload(root):
text = latest.read_text(encoding="utf-8", errors="replace")
blocks = re.split(r"(?m)^(?=## )", text)
block = blocks[-1].rstrip() if len(blocks) > 1 else text.rstrip()
# Open threads already print on the `threads:` line; don't show them twice.
block = re.sub(r"(?ms)^#{2,4}\s+Open threads\s*$.*?(?=^#|\Z)", "", block).rstrip()
lines = block.splitlines()
if len(lines) > WORKLOAD_TAIL_LINES:
lines = lines[:WORKLOAD_TAIL_LINES] + ["…"]
@ -277,6 +334,9 @@ def brief(root, a, hook=None):
out.append(extra)
out.extend(routines_lines(root, a.today))
out.extend(threads_lines(root, today))
slug = author_slug(root)
out.extend(profile_lines(root, slug))
out.extend(lessons_lines(root, slug, today))
path, block = latest_workload(root)
if path:
out.append(f"workload: {path.relative_to(root).as_posix()} — last block:")

View file

@ -0,0 +1,107 @@
---
name: ckb-profile
description: Keep a person's profile (role, how to work with them, personal lessons) in workload/profiles/ and record lessons on an explicit request — personal ones in the profile, KB-wide ones in wiki/lessons.md. Use for "set up my profile", "update my profile", "what do you know about me", "remember this", "lesson: …", "from now on always …", "list the lessons", "forget that lesson".
---
# Profile skill
## Purpose
Two things a session should not have to relearn: who it is working with, and
what a correction taught it. Both are written only when someone asks, never
from a guess about tone or preference.
## Scopes, and which wins
1. **`AGENTS.md`** — the KB's rules. Always win.
2. **A project scope's `## Rules`** — the team's agreements for that project,
in `wiki/projects/<name>.md`. Win while working inside that scope.
3. **A person's profile** — how to work with that person. Applies where
neither of the above says otherwise.
A profile can never relax a rule from 1 or 2. When it conflicts with one,
follow the rule and say so once.
## Profiles
One file per person: `workload/profiles/<author-slug>.md`, with the same slug
as Rule D (`Michał Kopeć` → `michal-kopec`). It sits outside `wiki/`, so
retrieval never reads it and it needs no `wiki/log.md` entry. The
session-start brief prints the profile of the session identity, and only
that one.
```markdown
---
type: profile
author: Name
author_email: name@example.com
last_updated: YYYY-MM-DD
---
# Name
## Role
<!-- What they do, and what they use this KB for. -->
## How to work with me
<!-- Short bullets: language, level of detail, what to ask before doing. -->
## Lessons
<!-- Personal lessons, newest last, in the lesson format below. -->
```
**Set up** ("set up my profile"): ask at most three questions in one message
— role, how they want to be worked with, anything to always or never do —
and write their answers in their words. Never fill a section by guessing.
**Update**: change only what they named, and set `last_updated`. **"What do
you know about me"**: show the profile, then say where it lives.
**Privacy.** A profile is committed and shared with everyone who clones the
KB. Say so when creating one. Keep it to working preferences: no health,
family, contact details beyond the git identity, or anything the person
would not post in a team channel. Text in `<private>…</private>` is never
written into a profile.
## Lessons
Record a lesson only on an explicit trigger: "remember this", "lesson: …",
"from now on always/never …". A correction on its own is not a trigger; at
most, offer once: "Want me to keep that as a lesson?"
```markdown
### YYYY-MM-DD — <the rule, one line>
- **Why:** <what went wrong or what the person said>
- **Applies when:** <the situations it covers>
- **Scope:** person | KB
- **Recorded by:** Name
```
Ask which scope when it is not obvious:
- **Person** — how this person likes to work. Append to `## Lessons` in
their profile.
- **KB** — true for anyone working in this KB (a naming rule, a source not
to trust, a step that keeps getting missed). Append to `wiki/lessons.md`.
Create the page if it is missing (`type: lessons`, a `tldr`, a routing row
in `wiki/index.md`). Set `review: needs_update`, or `draft` on a new page,
so a second person checks the lesson before everyone relies on it. Log it
under Rule B.
A lesson that should bind everyone, always, belongs in `AGENTS.md` instead.
Suggest that once; do not edit `AGENTS.md` from here.
The session-start brief lists KB lessons dated after the person's previous
workload note. Read the ones that bear on the task.
**Forgetting**: a lesson is never deleted silently. Strike it through
(`~~rule~~ — dropped YYYY-MM-DD: why`) so the record survives. A KB lesson
change is logged under Rule B.
## Edge cases
- **No git identity** — use the OS-user slug the brief prints, and suggest
setting `git config user.name` so the profile follows the person.
- **Two people share one git identity** — one profile per identity. Say so
and suggest separate identities.
- **A profile asks for something a skill forbids** (skip the ingest
check-in, push without asking) — follow the skill and say why once.

View file

@ -57,8 +57,9 @@ just said "reset the wiki" — the narrowest reading that satisfies the request.
| Tier | Contents | Default |
|---|---|---|
| **1 — Wiki knowledge** | Every page under `wiki/entities/`, `wiki/projects/`, `wiki/decisions/` (the `NNNN-*.md` records), `wiki/graph/edges.json` entries, and all log/overview/query-gap/error-book *entries* | **Yes** |
| **1 — Wiki knowledge** | Every page under `wiki/entities/`, `wiki/projects/`, `wiki/decisions/` (the `NNNN-*.md` records), `wiki/graph/edges.json` entries, `wiki/lessons.md`, the rows of `wiki/tags.md`, and all log/overview/query-gap/error-book *entries* | **Yes** |
| **2 — Workload history** | Every `workload/*_summary.md` and `workload/ingest-reports/*` | Ask |
| **2b — Profiles** | `workload/profiles/*` — people's own preferences and personal lessons | Ask — **default no**; they describe people, not the KB's subject |
| **3 — Source material** | `raw/inbox/*`, `raw/archive/*`, `raw/retractions/*`, `raw/saved-conversations/*` | Ask — this is the user's original material and may exist nowhere else |
| **4 — Generated artifacts** | `outputs/*` | Ask — cheap to regenerate, usually safe |
| **5 — External sources** | `libs/*`, `linked/*` | Ask — **default no.** `linked/` holds symlinks to *other people's* KBs, and deleting a symlink target by accident is a real risk |
@ -131,6 +132,7 @@ Step 8 defines it** — that skill is the single source of truth for what a clea
- `wiki/decisions/index.md` — header, placeholder, and the status-vocabulary
table **verbatim** (`ckb-decide` and `ckb-lint` both validate against it).
- `wiki/graph/edges.json` — `{"version": 1, "last_updated": "<today>", "edges": []}`.
- `wiki/tags.md` — frontmatter, explanation and an empty tag table.
- `.gitadd` placeholder files in any directory that would otherwise be empty, so
the structure survives in git.

View file

@ -32,7 +32,7 @@ Same cascade order as CLAUDE.md/AGENTS.md, first match wins:
2. `wiki/projects/index.md` — if a project scope matches the question,
use that project's listed pages, entity pages, raw/archive sources,
connector-backed libs, outputs, and graph areas as the first search
boundary. A project scope narrows the first pass only; it never hides
boundary, and follow its `## Rules` in how you answer. A project scope narrows the first pass only; it never hides
the rest of the cascade.
3. `wiki/entities/index.md` — match against entity titles/`tldr`.
4. `wiki/decisions/index.md` — for any "why is it like this", "who decided",
@ -66,14 +66,17 @@ a confidence×quality×freshness "trust" list — then fuses them with reciproca
rank fusion (`weight / (k + rank)`, `k = 10`, exact-match weighted 2.0 when the
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.
point. `--json` gives the same result as data. `--tag <tag>` (repeatable)
keeps only pages carrying those tags, for a question that names a tagged
area.
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
came from and at what rank, its `tldr`, `STALE`/`INBOX`/`SUPERSEDED`/`DRAFT`/
`NEEDS_UPDATE` flags, and
any `raw/archive/` or `outputs/` file it cites that the script folded in as
corroboration rather than counting as a second source.
@ -216,9 +219,11 @@ mid-answer unless the user asks for that separately.
State caveats in the answer itself, not only in the metadata you read to
build it. When a page grounding the answer is past its
`freshness_window_days`, carries a low `confidence` or `quality`, rests on
un-ingested `raw/inbox/` material, or was checked against a cached
connector index rather than a live re-fetch, say so in a short clause next
to the claim it qualifies. Surface a conflict between two live pages the
un-ingested `raw/inbox/` material, was checked against a cached
connector index rather than a live re-fetch, is `review: draft` (no person
has checked it) or `needs_update`, or carries an open `> CONTRADICTION:`
marker on the claim, say so in a short clause next to the claim it
qualifies. Surface a conflict between two live pages the
same way, even when neither is marked `superseded_by` yet. The metadata
already exists and the script's flags already put it in front of you; the failure mode
is answering confidently *from* a stale or contested page without passing

View file

@ -3,7 +3,7 @@
local signals and fuse them with reciprocal rank fusion.
python3 retrieve_candidates.py "question text" [--root DIR] [--k 10]
[--top 12] [--scope SLUG] [--json]
[--top 12] [--scope SLUG] [--tag TAG ...] [--json]
Signals, each its own ranked list (weight in brackets):
exact rg/grep hits on literal tokens, across wiki/, raw/archive/, raw/inbox/,
@ -15,6 +15,8 @@ Signals, each its own ranked list (weight in brackets):
indegree how many edges point at a shortlisted page [0.5]
trust confidence x quality x freshness, over the shortlist [0.3]
--tag keeps only wiki pages carrying every named tag (schema 1.6 `tags:`).
Fused score = sum(weight / (k + rank)) over the lists a candidate appears in.
`k` defaults to 10: a local wiki yields a dozen candidates, not hundreds, and
k=60 flattens them into near-identical scores.
@ -263,6 +265,7 @@ def main():
ap.add_argument("--top", type=int, default=12)
ap.add_argument("--scope", help="force a wiki/projects/<slug> scope instead of matching one")
ap.add_argument("--today", help="YYYY-MM-DD, for reproducible freshness")
ap.add_argument("--tag", action="append", default=[], help="keep only pages with this tag (repeatable)")
ap.add_argument("--json", action="store_true")
a = ap.parse_args()
@ -305,10 +308,14 @@ def main():
absorbed[o].append(item)
continue
results.append((item, sc))
if a.tag:
want = {t.strip().lower() for t in a.tag}
tagged = lambda pg: {t.strip().lower() for t in pg["fm"].get("tags", "").strip("[]").split(",") if t.strip()}
results = [(i, sc) for i, sc in results if i in pages and want <= tagged(pages[i])]
results = results[:a.top]
out = {
"query": a.query, "k": a.k, "literal_tokens": lits, "scope_page": scope_page,
"query": a.query, "k": a.k, "literal_tokens": lits, "scope_page": scope_page, "tags": a.tag,
"inbox_hits": sorted(inbox_hits), "empty_graph": not edges,
"candidates": [],
}
@ -320,7 +327,7 @@ def main():
"title": pg["title"] if pg else None, "type": fm.get("type"), "tldr": fm.get("tldr"),
"last_updated": fm.get("last_updated"), "stale": (is_fresh(fm, today) is False) if pg else None,
"confidence": fm.get("confidence"), "quality": fm.get("quality"),
"superseded_by": fm.get("superseded_by"),
"superseded_by": fm.get("superseded_by"), "review": fm.get("review"),
"sources": pg["sources"] if pg else [], "corroborated_by": absorbed.get(item, []),
"from_inbox": item.startswith("raw/inbox/"),
})
@ -334,13 +341,16 @@ def main():
print(f"literal tokens (exact list weighted 2.0): {', '.join(lits)}")
if scope_page:
print(f"scope: {scope_page}")
if a.tag:
print(f"tags: only pages tagged {', '.join(a.tag)}")
if out["empty_graph"]:
print("graph: empty — graph/indegree lists skipped")
if inbox_hits:
print(f"raw/inbox/ hits ({len(inbox_hits)}): un-ingested material — an ingest is overdue")
print()
for i, c in enumerate(out["candidates"], 1):
flags = [f for f, on in [("STALE", c["stale"]), ("INBOX", c["from_inbox"]), ("SUPERSEDED", c["superseded_by"])] if on]
flags = [f for f, on in [("STALE", c["stale"]), ("INBOX", c["from_inbox"]), ("SUPERSEDED", c["superseded_by"]),
("DRAFT", c["review"] == "draft"), ("NEEDS_UPDATE", c["review"] == "needs_update")] if on]
rk = " ".join(f"{n}:{r}" for n, r in sorted(c["ranks"].items()))
print(f"{i:2}. {c['score']:.4f} {c['path']} [{rk}]" + (f" {' '.join(flags)}" if flags else ""))
if c["tldr"]:

View file

@ -388,6 +388,21 @@ never blocks the version bump. Backfilling fingerprints is worth doing in
the same pass anyway, since it is mechanical and it is what makes `ckb-lint`
check 12 meaningful from that point on.
**b3. Schema 1.5 → 1.6: review, contradictions, tags, project rules.**
Every 1.6 addition is optional (D-0014), so a 1.5 page is already a valid
1.6 page. Migrating a 1.5 wiki:
- **`wiki/tags.md`** — create it from the template's scaffold (empty table)
if it is missing, and add its routing row to `wiki/index.md`. Never
overwrite an existing one: the vocabulary is the KB's own.
- **`review` fields** — do **not** backfill by default. An absent `review`
means "not tracked", which is the honest state for pages nobody has
checked under the new scheme. Offer it once: "Mark every existing page
`review: draft`, so they all enter the review queue?" Apply only on a yes,
and never set `reviewed`: that is a person's statement, not a migration's.
- **`## Rules`, `> CONTRADICTION:`, `wiki/lessons.md`,
`workload/profiles/`** — nothing to migrate; they appear when first used.
**c. Bump `wiki/index.md`'s `kb_schema_version`** to the template's
current value, once every page has been checked.

View file

@ -41,13 +41,16 @@ Maintain this root layout:
│ ├── log.md
│ ├── error-book.md
│ ├── query-gaps.md
│ ├── tags.md # Closed vocabulary for the optional `tags:` field
│ ├── lessons.md # KB-wide lessons, recorded on request (ckb-profile)
│ ├── projects/
│ ├── decisions/ # Numbered, append-only decision records
│ ├── entities/
│ └── graph/
└── workload/ # Session summaries and decisions
├── YYYY-MM-DD_<author>_summary.md # one file per person per day
└── ingest-reports/ # One change report per ckb-ingest run
├── ingest-reports/ # One change report per ckb-ingest run
└── profiles/ # One profile per person (ckb-profile); outside retrieval
```
### Optional Modules
@ -125,9 +128,16 @@ freshness_window_days: 90
retention: high|medium|low
source_fingerprint: sha256:3f9a2c1e # digest of the source this page was built from
source_checked: YYYY-MM-DD # when that digest was last verified
review: draft|reviewed|needs_update # absent = not tracked; ckb-lint marks reviews
reviewed_by: Name
reviewed_on: YYYY-MM-DD
tags: tag-one, tag-two # only tags listed in wiki/tags.md
---
```
`ckb-ingest` writes `review: draft` on a page it creates and
`needs_update` when it changes what a `reviewed` page claims.
### Page Body Sections
Three body sections are reserved across the whole KB. All are optional, but
where present they mean exactly this and nothing else:
@ -157,9 +167,17 @@ where present they mean exactly this and nothing else:
rewrite, reflow, summarize, or drop this section; regeneration
preserves it byte-for-byte. It is the only place a person can annotate
an agent-regenerated page and expect it to survive.
- **`## Rules`** — on a `wiki/projects/` scope page only: the team's rules
for that project. Human-authored and protected like `## Notes`; they apply
while working in that scope and yield only to this file.
- **`## Evidence`** / other sections are ordinary content with no special
handling.
Two sources that disagree get a marker in the page, never a silent winner:
`` > CONTRADICTION: <claim> (`<source>`) vs <claim> (`<source>`) — found YYYY-MM-DD ``.
It stays until a person resolves it (supersession, a decision, or an edit),
and lint lists every open one.
Pages with `type: decision` live in `wiki/decisions/` as `NNNN-slug.md` and
add `status` (`proposed`/`accepted`/`rejected`/`superseded`/`reversed`),
`decided_on`, `decided_by`, and optionally `affects` and `review_on`. They are
@ -167,7 +185,7 @@ append-only: never rewrite a decision's substance to match a later change of
mind — record a new decision that supersedes it, and set both
`supersedes` and `superseded_by`. `ckb-decide` owns the format.
`wiki/index.md` alone also carries `kb_schema_version`, currently `"1.5"`
`wiki/index.md` alone also carries `kb_schema_version`, currently `"1.6"`
for the base contract. An installed module may raise it additively by
declaring `requires_kb_schema` and contributing optional types and fields;
`ckb-module` applies that bump at install time. Detailed schema migration
@ -198,6 +216,7 @@ file.
| Generate a project overview | `ckb-project-summary` |
| Prepare a document from a template in `templates/`, list templates, or write a new one | `ckb-document` |
| Teach, quiz, or onboard from the wiki | `ckb-teach-me`, `ckb-quiz`, `ckb-onboard-me` |
| Set up a person's profile, or record a lesson ("remember this") | `ckb-profile` |
Disambiguation, only where the table alone is ambiguous:
@ -345,6 +364,8 @@ Act only on lines that ask for it, and stay quiet about anything clean:
and `ckb-lint` own the details.
- `threads:` → mention the count in one line; pick a thread up only when the
user asks.
- `profile:` → follow it where this file and project rules leave room.
- `lessons:` → read the ones that bear on the request.
- `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

View file

@ -223,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.
### Profiles and Lessons
Each person can keep a profile in `workload/profiles/` (role, how to work
with them), printed into their own session-start brief and nobody else's.
"Remember this" or "lesson: …" records a lesson: a personal one in the
profile, a KB-wide one in `wiki/lessons.md`, which waits for a second
person's review. Precedence is `AGENTS.md`, then a project's `## Rules`, then
the profile. Skill: `.agents/skills/ckb-profile/SKILL.md`.
### Kept Answers
An answer that took real work can be kept on request in
`outputs/answers/`, with fingerprinted `## Sources` and a `## Gaps`
@ -282,6 +290,8 @@ freshness_window_days: 90 # Days before considered stale
retention: high|medium|low
source_fingerprint: sha256:3f9a2c1e # digest of the source this page was built from
source_checked: YYYY-MM-DD # when that digest was last verified
review: draft|reviewed|needs_update # with reviewed_by / reviewed_on (1.6)
tags: retries, billing # only tags listed in wiki/tags.md (1.6)
---
```
@ -296,6 +306,11 @@ source_checked: YYYY-MM-DD # when that digest was last verified
was synthesized from, plus when it was last confirmed. A freshness window is
a guess that a source *might* have moved; a fingerprint is a fact about
whether it *did*, and lint checks it mechanically.
- **review / reviewed_by / reviewed_on** - whether a person has checked the
page: ingest writes `draft`, a person's "mark X as reviewed" sets
`reviewed`, and a later change to what the page claims sets `needs_update`
- **tags** - a flat list checked against the KB's own vocabulary in
`wiki/tags.md`; retrieval can filter on it
#### Reserved body sections
Three `##` headings mean something specific everywhere in the KB:
@ -305,6 +320,11 @@ Three `##` headings mean something specific everywhere in the KB:
| `## Sources` | one bullet per source, each with a fingerprint |
| `## Crux` | verbatim quotes from those sources - evidence, never paraphrase |
| `## Notes` | human-authored and **protected**: no skill rewrites it, ever |
| `## Rules` | on project scope pages only: the team's rules for that project, protected like `## Notes` |
Where two sources disagree and nobody has decided which is right, ingest
writes a `> CONTRADICTION: …` marker into the page instead of picking a
winner; lint lists it until a person settles it.
`## Crux` is what lets a question be answered from the page instead of from
the archive: a summary can drift silently, a quote either still matches its
@ -312,7 +332,7 @@ source or it doesn't. `## Notes` is the inverse guarantee - on pages the agent
regenerates (connector indexes, code maps), it is the one place an annotation
survives the next rebuild.
`wiki/index.md` alone also carries `kb_schema_version` (currently `"1.5"`), declaring
`wiki/index.md` alone also carries `kb_schema_version` (currently `"1.6"`), declaring
which revision of this schema the wiki was authored against - bump minor for
additive optional fields, major for breaking changes.

View file

@ -233,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.
### Profile i lekcje
Każda osoba może mieć profil w `workload/profiles/` (rola, jak z nią
pracować), wypisywany w podsumowaniu startu jej własnej sesji i niczyjej
innej. „Remember this” albo „lesson: …” zapisuje lekcję: osobistą w profilu,
dla całej KB w `wiki/lessons.md`, gdzie czeka na przegląd drugiej osoby.
Pierwszeństwo: `AGENTS.md`, potem `## Rules` projektu, potem profil. Skill:
`.agents/skills/ckb-profile/SKILL.md`.
### 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
@ -297,6 +305,8 @@ freshness_window_days: 90 # Liczba dni, po których treść uznaje się za nieak
retention: high|medium|low
source_fingerprint: sha256:3f9a2c1e # skrót źródła, z którego zbudowano tę stronę
source_checked: YYYY-MM-DD # kiedy ten skrót był ostatnio zweryfikowany
review: draft|reviewed|needs_update # z reviewed_by / reviewed_on (1.6)
tags: retries, billing # tylko tagi z wiki/tags.md (1.6)
---
```
@ -318,6 +328,12 @@ source_checked: YYYY-MM-DD # kiedy ten skrót był ostatnio zweryfiko
zsyntetyzowano stronę, oraz data ostatniego potwierdzenia. Okno świeżości to
przypuszczenie, że źródło *mogło* się zmienić; skrót to fakt, czy *się
zmieniło*, a lint sprawdza go mechanicznie.
- **review / reviewed_by / reviewed_on** *(1.6)* — czy stronę sprawdził
człowiek: ingest zapisuje `draft`, polecenie „mark X as reviewed” ustawia
`reviewed`, a późniejsza zmiana tego, co strona twierdzi, ustawia
`needs_update`
- **tags** *(1.6)* — płaska lista sprawdzana względem własnego słownika KB
w `wiki/tags.md`; wyszukiwanie może po niej filtrować
#### Zastrzeżone sekcje treści
Trzy nagłówki `##` mają w całej KB ściśle określone znaczenie:
@ -327,6 +343,11 @@ Trzy nagłówki `##` mają w całej KB ściśle określone znaczenie:
| `## Sources` | po jednym punkcie na źródło, każdy ze skrótem |
| `## Crux` | dosłowne cytaty z tych źródeł — dowód, nigdy parafraza |
| `## Notes` | pisane przez człowieka i **chronione**: żaden skill ich nie nadpisuje |
| `## Rules` | tylko na stronach zakresu projektu: zasady zespołu dla tego projektu, chronione jak `## Notes` |
Gdy dwa źródła się nie zgadzają, a nikt nie zdecydował, które ma rację,
ingest wpisuje na stronę znacznik `> CONTRADICTION: …` zamiast wybierać
zwycięzcę; lint wypisuje go, dopóki człowiek go nie rozstrzygnie.
`## Crux` pozwala odpowiedzieć na pytanie ze strony zamiast z archiwum:
streszczenie może po cichu odpłynąć od źródła, cytat albo wciąż się z nim
@ -334,7 +355,7 @@ zgadza, albo nie. `## Notes` daje odwrotną gwarancję — na stronach
regenerowanych przez agenta (indeksy konektorów, mapy kodu) to jedyne miejsce,
w którym adnotacja przetrwa kolejną przebudowę.
Sam `wiki/index.md` dodatkowo zawiera `kb_schema_version` (obecnie `"1.5"`),
Sam `wiki/index.md` dodatkowo zawiera `kb_schema_version` (obecnie `"1.6"`),
deklarujący, według której wersji tego schematu wiki została napisana —
zwiększaj wersję pomniejszą dla dodatkowych opcjonalnych pól, główną dla
zmian łamiących kompatybilność.

View file

@ -1 +1 @@
1.22.1
1.23.0

View file

@ -28,14 +28,14 @@ so any page written since 2026-07-13 is still valid today.
## Contents
1. [Current page schema (1.5)](#current-page-schema-kb_schema_version-15)
1. [Current page schema (1.6)](#current-page-schema-kb_schema_version-16)
2. [KB schema version history](#kb-schema-version-history)
3. [Template version history](#template-version-history)
4. [Migrating between versions](#migrating-between-versions)
---
## Current page schema (`kb_schema_version: "1.5"`)
## Current page schema (`kb_schema_version: "1.6"`)
### Frontmatter — every non-reserved page
@ -58,6 +58,10 @@ flat `key: value` pairs only, no nesting.
| `retention` | no | `high` / `medium` / `low`. A `low` page is archived (never deleted) after 2× its freshness window. |
| `source_fingerprint` | no | *(1.5)* Digest of the source this page was built from - `sha256:<8 hex>` for a local file, or `etag:<value>` / `mtime:<iso8601>` for a connector item. |
| `source_checked` | no | *(1.5)* `YYYY-MM-DD` - when that digest was last verified. Distinct from `last_updated`: a re-check that finds nothing changed advances this and leaves `last_updated` alone. |
| `review` | no | *(1.6)* `draft` / `reviewed` / `needs_update`. Absent means "not tracked". `ckb-ingest` writes `draft` on new pages and `needs_update` when it changes what a `reviewed` page claims; only a person's say-so sets `reviewed` (via `ckb-lint`). |
| `reviewed_by` | no | *(1.6)* Who last reviewed the page. Kept when the page moves to `needs_update`, as the record of the last review. |
| `reviewed_on` | no | *(1.6)* `YYYY-MM-DD` of that review. Lint flags a `reviewed` page whose `last_updated` is later. |
| `tags` | no | *(1.6)* Flat comma list, e.g. `tags: retries, billing`. Every tag must be a row in `wiki/tags.md`. |
`wiki/index.md` alone carries `kb_schema_version`. It is a bundle-level
declaration, not a per-page one - individual pages never carry it.
@ -141,6 +145,25 @@ the only place an annotation survives. Decision pages deliberately have no
editable annotation block invites exactly the retroactive revision the
append-only rule exists to prevent.
#### `## Rules`
*(1.6.)* On a `wiki/projects/` scope page only: the team's rules for that
project, which apply while working inside the scope. Human-authored and
protected exactly like `## Notes`. They yield only to `AGENTS.md`; a person's
profile yields to them.
#### The contradiction marker
*(1.6.)* Not a section but a body line, written where two sources disagree
and nobody has decided which is right:
```markdown
> CONTRADICTION: three retries (`raw/archive/2026-09-01/kickoff-notes.md`) vs five retries (`raw/archive/2026-11-02/runbook.md`) — found 2026-11-02
```
It stays until a person resolves it (supersession, a decision, or an edit),
and lint lists every open one (check 18).
### Edge vocabulary
Relationships live in `wiki/graph/edges.json` (and each connector index's own
@ -185,6 +208,8 @@ improving it (in-degree is used as a ranking signal).
| `wiki/query-gaps.md` | 1.2 | Questions the wiki could not answer, driving demand-driven ingest |
| `wiki/projects/` | 1.2 | Optional local query scopes |
| `wiki/decisions/` | 1.4 | Numbered, append-only decision records, with their own `log.md` |
| `wiki/tags.md` | 1.6 | The KB's own closed tag vocabulary (`type: vocabulary`); lint checks `tags:` against it |
| `wiki/lessons.md` | 1.6 | KB-wide lessons, created on first use by `ckb-profile` (`type: lessons`) |
Every subdirectory that groups pages carries its own `index.md`, so
navigation stays lazy.
@ -193,6 +218,27 @@ navigation stays lazy.
## KB schema version history
### 1.6 — 2026-11-02 · review, contradictions, tags, project rules
From the 2026-10-31 agent-knowledge research (features F7, F4, F21, F9, F8),
decided in [D-0014](decisions/0014-schema-1-6-review-contradictions-tags-profiles.md).
Additive: a 1.5 page is a valid 1.6 page.
- **Review fields** `review`/`reviewed_by`/`reviewed_on`. The plan's name was
`status`, which decision pages already use with a different vocabulary.
- **Contradiction marker** `> CONTRADICTION: …` instead of a silent winner.
Claim-level `valid_from`/`valid_to` are deferred.
- **`tags`** checked against the new scaffold file `wiki/tags.md`.
- **`## Rules`**, a protected section on project scope pages.
- **`wiki/lessons.md`**, created on first use.
Outside `wiki/` and so outside the schema, but shipped together: per-person
profiles in `workload/profiles/` and the `ckb-profile` skill.
**Migration** (`ckb-upgrade` Step 7 b3): add `wiki/tags.md` and its index
row, bump the version. `review` is backfilled only on request, and only to
`draft`.
### 1.5 — 2026-09-21 · evidence, fingerprints, and a completed edge vocabulary
Adopted from an analysis of [trailhq/Graft](https://github.com/trailhq/Graft),
@ -284,7 +330,8 @@ docs. Independent of the content schema above.
| Version | Date | What landed | Schema |
|---|---|---|---|
| **1.22.1** | 2026-11-02 | Hooks start from the project root. Claude Code runs a hook in the session's current directory, so the autosave Stop hook's relative `save_conversation.py` path resolved against whatever folder the shell had moved into: a session working inside a nested repo saved its transcript there, and in a folder without the script the save failed silently. `autosave_hook.py` and `start_hook.py` now write `cd "${CLAUDE_PROJECT_DIR:-.}" && …`; `--check` reports an entry installed before this fix as outdated (the session-start brief asks once), and `--install` replaces it without touching other hooks. Smoke test runs both installed hooks from a subfolder | 1.5 |
| **1.23.0** | 2026-11-02 | Agent-knowledge release 2, **schema 1.6** (D-0014). **Review (F7):** optional `review: draft|reviewed|needs_update` with `reviewed_by`/`reviewed_on` (the plan's `status` clashed with decision pages); `ckb-ingest` writes `draft` on new pages and `needs_update` when it changes what a reviewed page claims; lint check 17 flags only inconsistencies and prints a review queue; `ckb-lint` marks reviews on the person's say-so. **Contradictions (F4):** a `> CONTRADICTION:` body marker instead of a silent winner, listed by lint check 18 until resolved by supersession, a decision or an edit; claim-level validity dates deferred. **Tags (F21):** `tags:` checked against the new scaffold `wiki/tags.md` (check 19); `retrieve_candidates.py --tag`; `DRAFT`/`NEEDS_UPDATE` retrieval flags. **Scopes and profiles (F9):** `AGENTS.md` > a project scope's protected `## Rules` > a person's profile in `workload/profiles/`, printed by the session-start brief for the session identity only. **Lessons (F8):** on an explicit trigger only; personal in the profile, KB-wide in `wiki/lessons.md` (reviewed before relied on); the brief lists lessons new since the person's previous note. New skill `ckb-profile`. **Carry-over:** `.secrets-allow` accepts `<glob> match:<hash>` entries that cover one string on every line of growing transcripts (bash/PowerShell fallbacks too); open threads no longer print twice. Starlight shows review and tags and a "Needs update" badge; OKF passes the new fields through. `ckb-upgrade` Step 7 b3 migrates 1.5 → 1.6; `ckb-init`/`ckb-reset` know `tags.md`. Always-loaded ~7,245 tokens | 1.6 |
| 1.22.1 | 2026-11-02 | Hooks start from the project root. Claude Code runs a hook in the session's current directory, so the autosave Stop hook's relative `save_conversation.py` path resolved against whatever folder the shell had moved into: a session working inside a nested repo saved its transcript there, and in a folder without the script the save failed silently. `autosave_hook.py` and `start_hook.py` now write `cd "${CLAUDE_PROJECT_DIR:-.}" && …`; `--check` reports an entry installed before this fix as outdated (the session-start brief asks once), and `--install` replaces it without touching other hooks. Smoke test runs both installed hooks from a subfolder | 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 |

View file

@ -29,14 +29,14 @@ strona napisana od 2026-07-13 jest dziś nadal poprawna.
## Spis treści
1. [Aktualny schemat strony (1.5)](#aktualny-schemat-strony-kb_schema_version-15)
1. [Aktualny schemat strony (1.6)](#aktualny-schemat-strony-kb_schema_version-16)
2. [Historia wersji schematu KB](#historia-wersji-schematu-kb)
3. [Historia wersji szablonu](#historia-wersji-szablonu)
4. [Migracja między wersjami](#migracja-między-wersjami)
---
## Aktualny schemat strony (`kb_schema_version: "1.5"`)
## Aktualny schemat strony (`kb_schema_version: "1.6"`)
### Frontmatter — każda strona niezastrzeżona
@ -59,6 +59,10 @@ pary `klucz: wartość`, bez zagnieżdżeń.
| `retention` | nie | `high` / `medium` / `low`. Strona `low` jest archiwizowana (nigdy usuwana) po 2× swoim oknie świeżości. |
| `source_fingerprint` | nie | *(1.5)* Skrót źródła, z którego zbudowano stronę — `sha256:<8 hex>` dla pliku lokalnego albo `etag:<wartość>` / `mtime:<iso8601>` dla elementu z konektora. |
| `source_checked` | nie | *(1.5)* `YYYY-MM-DD` — kiedy ten skrót był ostatnio zweryfikowany. To co innego niż `last_updated`: ponowne sprawdzenie, które nie wykryło zmiany, przesuwa to pole i zostawia `last_updated` w spokoju. |
| `review` | nie | *(1.6)* `draft` / `reviewed` / `needs_update`. Brak pola oznacza „nieśledzone”. `ckb-ingest` zapisuje `draft` na nowych stronach i `needs_update`, gdy zmienia to, co twierdzi strona `reviewed`; `reviewed` ustawia tylko decyzja człowieka (przez `ckb-lint`). |
| `reviewed_by` | nie | *(1.6)* Kto ostatnio przejrzał stronę. Zostaje, gdy strona przechodzi w `needs_update`, jako zapis ostatniego przeglądu. |
| `reviewed_on` | nie | *(1.6)* `YYYY-MM-DD` tego przeglądu. Lint flaguje stronę `reviewed`, której `last_updated` jest późniejsze. |
| `tags` | nie | *(1.6)* Płaska lista po przecinku, np. `tags: retries, billing`. Każdy tag musi być wierszem w `wiki/tags.md`. |
Wyłącznie `wiki/index.md` niesie `kb_schema_version`. To deklaracja na
poziomie całego zbioru, nie pojedynczej strony — same strony nigdy jej nie
@ -144,6 +148,25 @@ Strony decyzji celowo nie mają `## Notes`: nic ich nie regeneruje, a rekord
tylko-do-dopisywania ze swobodnie edytowalnym blokiem adnotacji zaprasza
dokładnie do tej wstecznej korekty, której zasada append-only ma zapobiegać.
#### `## Rules`
*(1.6.)* Tylko na stronie zakresu w `wiki/projects/`: zasady zespołu dla tego
projektu, obowiązujące podczas pracy w tym zakresie. Pisane przez człowieka i
chronione dokładnie jak `## Notes`. Ustępują tylko `AGENTS.md`; profil osoby
ustępuje im.
#### Znacznik sprzeczności
*(1.6.)* Nie sekcja, lecz linia w treści, zapisywana tam, gdzie dwa źródła się
nie zgadzają, a nikt nie zdecydował, które ma rację:
```markdown
> CONTRADICTION: three retries (`raw/archive/2026-09-01/kickoff-notes.md`) vs five retries (`raw/archive/2026-11-02/runbook.md`) — found 2026-11-02
```
Zostaje, dopóki człowiek jej nie rozstrzygnie (supersesja, decyzja albo
edycja), a lint wypisuje każdą otwartą (kontrola 18).
### Słownik krawędzi
Relacje mieszkają w `wiki/graph/edges.json` (oraz we własnym
@ -189,6 +212,8 @@ rankingowym).
| `wiki/query-gaps.md` | 1.2 | Pytania, na które wiki nie umiało odpowiedzieć, napędzające ingest sterowany popytem |
| `wiki/projects/` | 1.2 | Opcjonalne lokalne zakresy zapytań |
| `wiki/decisions/` | 1.4 | Numerowane rekordy decyzji tylko-do-dopisywania, z własnym `log.md` |
| `wiki/tags.md` | 1.6 | Własny zamknięty słownik tagów KB (`type: vocabulary`); lint sprawdza względem niego `tags:` |
| `wiki/lessons.md` | 1.6 | Lekcje dla całej KB, tworzone przy pierwszym użyciu przez `ckb-profile` (`type: lessons`) |
Każdy podkatalog grupujący strony niesie własny `index.md`, dzięki czemu
nawigacja pozostaje leniwa.
@ -197,6 +222,27 @@ nawigacja pozostaje leniwa.
## Historia wersji schematu KB
### 1.6 — 2026-11-02 · przegląd, sprzeczności, tagi, zasady projektu
Z badania wiedzy dla agentów z 2026-10-31 (funkcje F7, F4, F21, F9, F8),
decyzja [D-0014](decisions/0014-schema-1-6-review-contradictions-tags-profiles.md).
Addytywnie: strona 1.5 jest poprawną stroną 1.6.
- **Pola przeglądu** `review`/`reviewed_by`/`reviewed_on`. Plan nazywał je
`status`, ale strony decyzji używają już `status` z innym słownikiem.
- **Znacznik sprzeczności** `> CONTRADICTION: …` zamiast cichego zwycięzcy.
Daty ważności na poziomie twierdzeń (`valid_from`/`valid_to`) odłożone.
- **`tags`** sprawdzane względem nowego pliku szkieletu `wiki/tags.md`.
- **`## Rules`**, chroniona sekcja na stronach zakresu projektu.
- **`wiki/lessons.md`**, tworzony przy pierwszym użyciu.
Poza `wiki/`, a więc poza schematem, ale w tym samym wydaniu: profile osób w
`workload/profiles/` i skill `ckb-profile`.
**Migracja** (`ckb-upgrade`, krok 7 b3): dodać `wiki/tags.md` i jego wiersz
w indeksie, podnieść wersję. `review` uzupełniane tylko na prośbę i tylko do
`draft`.
### 1.5 — 2026-09-21 · dowody, skróty źródeł i dokończony słownik krawędzi
Zaadaptowane z analizy [trailhq/Graft](https://github.com/trailhq/Graft),
@ -291,7 +337,8 @@ Niezależna od schematu treści powyżej.
| Wersja | Data | Co weszło | Schemat |
|---|---|---|---|
| **1.22.1** | 2026-11-02 | Hooki startują z katalogu głównego projektu. Claude Code uruchamia hook w bieżącym katalogu sesji, więc względna ścieżka `save_conversation.py` w hooku autozapisu `Stop` rozwiązywała się względem folderu, do którego przeszła powłoka: sesja pracująca w zagnieżdżonym repozytorium zapisywała tam swój transkrypt, a w folderze bez skryptu zapis cicho się nie udawał. `autosave_hook.py` i `start_hook.py` zapisują teraz `cd "${CLAUDE_PROJECT_DIR:-.}" && …`; `--check` zgłasza wpis zainstalowany przed tą poprawką jako nieaktualny (podsumowanie startu sesji pyta raz), a `--install` podmienia go, nie ruszając innych hooków. Test dymny uruchamia oba zainstalowane hooki z podfolderu | 1.5 |
| **1.23.0** | 2026-11-02 | Wiedza dla agentów, wydanie 2, **schemat 1.6** (D-0014). **Przegląd (F7):** opcjonalne `review: draft|reviewed|needs_update` z `reviewed_by`/`reviewed_on` (planowane `status` kolidowało ze stronami decyzji); `ckb-ingest` zapisuje `draft` na nowych stronach i `needs_update`, gdy zmienia to, co twierdzi strona przejrzana; kontrola 17 lintu flaguje tylko niespójności i wypisuje kolejkę przeglądu; `ckb-lint` oznacza przegląd na słowo człowieka. **Sprzeczności (F4):** znacznik `> CONTRADICTION:` w treści zamiast cichego zwycięzcy, wypisywany przez kontrolę 18 do rozstrzygnięcia supersesją, decyzją lub edycją; daty ważności twierdzeń odłożone. **Tagi (F21):** `tags:` sprawdzane względem nowego pliku szkieletu `wiki/tags.md` (kontrola 19); `retrieve_candidates.py --tag`; flagi wyszukiwania `DRAFT`/`NEEDS_UPDATE`. **Zakresy i profile (F9):** `AGENTS.md` > chroniona sekcja `## Rules` zakresu projektu > profil osoby w `workload/profiles/`, wypisywany przez podsumowanie startu sesji tylko dla tożsamości sesji. **Lekcje (F8):** tylko na wyraźne polecenie; osobiste w profilu, dla całej KB w `wiki/lessons.md` (przeglądane, zanim się na nich polega); podsumowanie wymienia lekcje nowe od poprzedniej notatki osoby. Nowy skill `ckb-profile`. **Pozostałości:** `.secrets-allow` przyjmuje wpisy `<glob> match:<skrót>`, które obejmują jeden ciąg w każdej linii rosnących transkryptów (także zapasowe bash/PowerShell); otwarte wątki nie drukują się już dwa razy. Starlight pokazuje przegląd i tagi oraz odznakę „Needs update”; OKF przepuszcza nowe pola. `ckb-upgrade` krok 7 b3 migruje 1.5 → 1.6; `ckb-init`/`ckb-reset` znają `tags.md`. Warstwa ładowana zawsze ~7 245 tokenów | 1.6 |
| 1.22.1 | 2026-11-02 | Hooki startują z katalogu głównego projektu. Claude Code uruchamia hook w bieżącym katalogu sesji, więc względna ścieżka `save_conversation.py` w hooku autozapisu `Stop` rozwiązywała się względem folderu, do którego przeszła powłoka: sesja pracująca w zagnieżdżonym repozytorium zapisywała tam swój transkrypt, a w folderze bez skryptu zapis cicho się nie udawał. `autosave_hook.py` i `start_hook.py` zapisują teraz `cd "${CLAUDE_PROJECT_DIR:-.}" && …`; `--check` zgłasza wpis zainstalowany przed tą poprawką jako nieaktualny (podsumowanie startu sesji pyta raz), a `--install` podmienia go, nie ruszając innych hooków. Test dymny uruchamia oba zainstalowane hooki z podfolderu | 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 |

View file

@ -224,6 +224,18 @@ Three things happen before anything is written:
`</private>` in a source is never written into the wiki, quoted, or
summarised.
Pages the agent creates start as `review: draft`, meaning no person has
checked them yet. When new material disagrees with a page and it isn't clear
which is right, the agent doesn't pick a winner. It writes a marker into the
page and tells you:
```markdown
> CONTRADICTION: three retries (`raw/archive/2026-09-01/kickoff-notes.md`) vs five retries (`raw/archive/2026-11-02/runbook.md`) — found 2026-11-02
```
The marker stays until you settle it (see "Review, contradictions and tags"
under [Keeping it tidy](#3-keeping-it-tidy)).
Skill: `.agents/skills/ckb-ingest/SKILL.md`.
### B. Just tell the agent something in conversation
@ -301,6 +313,12 @@ listing the pages, entities, raw/archive files, connector indexes, and graph
areas that should be searched first for that scope. You still keep one
local wiki; this just gives repeated questions a better starting area.
A scope page can also carry your team's rules for that project, in a
`## Rules` section you write yourself: "name environments `prod`/`stage`,
never `production`", "decisions here need the client's sign-off". The agent
follows them whenever it works inside that scope, and no skill ever rewrites
them. Only `AGENTS.md` overrides them.
---
## 3. Keeping it tidy
@ -373,6 +391,26 @@ allowlisted: the finding prints a `<path> <hash>` line to add to
the line brings the finding back. The same check runs before every "sync
changes" commit.
### Review, contradictions and tags
**Review.** A page can say whether a person has checked it:
`review: draft` (the agent wrote it, nobody checked), `reviewed` (with
`reviewed_by` and `reviewed_on`), or `needs_update` (it was reviewed, then
changed or was contradicted). Ask "what needs review?" for the queue,
`needs_update` first. Say "mark X as reviewed" once you have read a page; the
agent records your name and today's date and never marks a page you did not
name. If a reviewed page later changes, lint notices. Answers built on draft
pages say so.
**Contradictions.** Lint lists every open `> CONTRADICTION:` marker. Settle
one by saying which side is right. The agent then either supersedes the
wrong page, records a decision ("record a decision: we retry five times"),
or edits the claim, and removes the marker.
**Tags.** A page may carry `tags: retries, billing`, but only tags listed in
`wiki/tags.md`. Add a row there before using a new tag; lint flags any tag
that isn't listed. Questions can then be narrowed by tag.
**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
@ -800,6 +838,30 @@ Covered in full in [§2](#2-adding-knowledge) - the short version: drop it
in `raw/inbox/` and say "Ingest," or tell the agent in chat if it's
small enough to state directly.
### Your profile and lessons
Say "set up my profile" and the agent asks up to three questions: your role,
how you want it to work with you, and anything to always or never do. Your
answers go into `workload/profiles/<your-name>.md`. From then on, every
session you start prints your profile into the agent's brief. Other people's
profiles are not loaded for you. The file is committed, so keep it to
working preferences you'd share with the team.
Your preferences never override the KB's rules. `AGENTS.md` comes first, a
project's `## Rules` next, and your profile fills in the rest.
When the agent gets something wrong, you can make the correction stick:
"remember this: always cite the runbook for retry numbers", or
"lesson: …". It asks whether the lesson is yours or for everyone:
- **Yours** goes into your profile.
- **Everyone's** goes into `wiki/lessons.md` and waits for a second person
to review it. Everyone else's next session lists it as new.
Nothing becomes a lesson unless you ask. A lesson that should bind everyone
always belongs in `AGENTS.md`; the agent will suggest that rather than edit
it. Skill: `.agents/skills/ckb-profile/SKILL.md`.
### Save a conversation
Every new session gets a title the agent picks from your first message
@ -1038,6 +1100,8 @@ 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` |
| "Set up my profile" / "Remember this: …" / "Lesson: …" | Writes your profile, or records a personal or KB-wide lesson | `ckb-profile` |
| "What needs review?" / "Mark X as reviewed" | Lists draft and needs_update pages / records your review on the pages you name | `ckb-lint` |
| "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` |

View file

@ -234,6 +234,18 @@ Zanim cokolwiek zostanie zapisane, dzieją się trzy rzeczy:
`<private>` … `</private>`, nigdy nie trafia do wiki: nie jest zapisywane,
cytowane ani streszczane.
Strony tworzone przez agenta zaczynają jako `review: draft`, czyli nikt ich
jeszcze nie sprawdził. Gdy nowy materiał nie zgadza się ze stroną i nie
wiadomo, co jest prawdą, agent nie wybiera zwycięzcy. Wpisuje na stronę
znacznik i mówi ci o tym:
```markdown
> CONTRADICTION: three retries (`raw/archive/2026-09-01/kickoff-notes.md`) vs five retries (`raw/archive/2026-11-02/runbook.md`) — found 2026-11-02
```
Znacznik zostaje, dopóki go nie rozstrzygniesz (zob. „Przegląd, sprzeczności
i tagi” w [Utrzymaniu porządku](#3-utrzymanie-porządku)).
Skill: `.agents/skills/ckb-ingest/SKILL.md`.
### B. Po prostu powiedz agentowi coś w rozmowie
@ -312,6 +324,12 @@ wymieniającą strony, encje, pliki z `raw/archive/`, indeksy konektorów i
obszary grafu, które należy przeszukać najpierw dla tego zakresu. Nadal masz
jedną lokalną wiki; to tylko daje powracającym pytaniom lepszy punkt startowy.
Strona zakresu może też zawierać zasady zespołu dla tego projektu, w sekcji
`## Rules`, którą piszesz sam: „środowiska nazywamy `prod`/`stage`, nigdy
`production`”, „decyzje tutaj wymagają zgody klienta”. Agent stosuje je
zawsze, gdy pracuje w tym zakresie, a żaden skill ich nie przepisuje. Nadrzędny
jest tylko `AGENTS.md`.
---
## 3. Utrzymanie porządku
@ -391,6 +409,26 @@ dokumentacji, można dodać do listy dozwolonych: znalezisko podaje linię
Skrót obejmuje tę jedną linię, więc jej edycja przywraca znalezisko. Ta sama
kontrola działa przed każdym commitem w „sync changes”.
### Przegląd, sprzeczności i tagi
**Przegląd.** Strona może mówić, czy sprawdził ją człowiek: `review: draft`
(napisał ją agent, nikt nie sprawdził), `reviewed` (z `reviewed_by` i
`reviewed_on`) albo `needs_update` (była przejrzana, potem się zmieniła lub
pojawiła się sprzeczność). Zapytaj „what needs review?”, żeby zobaczyć
kolejkę, najpierw `needs_update`. Powiedz „mark X as reviewed”, gdy
przeczytasz stronę; agent zapisze twoje nazwisko i dzisiejszą datę i nigdy nie
oznaczy strony, której nie wskazałeś. Jeśli przejrzana strona później się
zmieni, lint to zauważy. Odpowiedzi oparte na stronach `draft` mówią o tym.
**Sprzeczności.** Lint wypisuje każdy otwarty znacznik `> CONTRADICTION:`.
Rozstrzygasz go, mówiąc, która strona ma rację. Agent wtedy zastępuje błędną
stronę (supersesja), zapisuje decyzję („record a decision: we retry five
times”) albo poprawia twierdzenie, i usuwa znacznik.
**Tagi.** Strona może mieć `tags: retries, billing`, ale tylko z tagami
wymienionymi w `wiki/tags.md`. Zanim użyjesz nowego tagu, dodaj tam wiersz;
lint flaguje każdy tag spoza listy. Pytania można wtedy zawęzić do tagu.
**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
@ -841,6 +879,30 @@ W pełni opisane w [§2](#2-dodawanie-wiedzy) — w skrócie: wrzuć materiał d
`raw/inbox/` i powiedz „Ingest”, albo powiedz agentowi w
rozmowie, jeśli to wystarczająco krótkie, żeby podać wprost.
### Twój profil i lekcje
Powiedz „set up my profile”, a agent zada do trzech pytań: o twoją rolę, o to,
jak ma z tobą pracować, i o to, czego zawsze lub nigdy nie robić. Odpowiedzi
trafiają do `workload/profiles/<twoje-imię>.md`. Od tej pory każda sesja, którą
zaczynasz, wypisuje twój profil w podsumowaniu agenta. Profile innych osób nie
są dla ciebie wczytywane. Plik jest commitowany, więc trzymaj w nim tylko
preferencje robocze, którymi podzieliłbyś się z zespołem.
Twoje preferencje nigdy nie są ważniejsze od zasad KB. Najpierw `AGENTS.md`,
potem `## Rules` projektu, a resztę uzupełnia twój profil.
Gdy agent się pomyli, możesz utrwalić poprawkę: „remember this: always cite
the runbook for retry numbers” albo „lesson: …”. Agent pyta, czy lekcja jest
twoja, czy dla wszystkich:
- **Twoja** trafia do twojego profilu.
- **Dla wszystkich** trafia do `wiki/lessons.md` i czeka na przegląd drugiej
osoby. Najbliższa sesja każdej innej osoby wymieni ją jako nową.
Nic nie staje się lekcją, jeśli o to nie poprosisz. Lekcja, która ma zawsze
obowiązywać wszystkich, należy do `AGENTS.md`; agent to zasugeruje, zamiast go
edytować. Skill: `.agents/skills/ckb-profile/SKILL.md`.
### Zapisywanie rozmowy
Każda nowa sesja dostaje tytuł, który agent sam wybiera na podstawie
@ -1089,6 +1151,8 @@ 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` |
| „Set up my profile” / „Remember this: …” / „Lesson: …” | Zapisuje twój profil albo lekcję osobistą lub dla całej KB | `ckb-profile` |
| „What needs review?” / „Mark X as reviewed” | Wypisuje strony draft i needs_update / zapisuje twój przegląd wskazanych stron | `ckb-lint` |
| „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` |

View file

@ -0,0 +1,91 @@
---
type: decision
tldr: Schema 1.6 adds optional review fields (review, reviewed_by, reviewed_on), a tags field checked against wiki/tags.md, an in-page `> CONTRADICTION:` marker, a protected `## Rules` section on project scope pages, per-person profiles in workload/profiles/, and explicit lessons; ckb-lint owns review marking, a new ckb-profile skill owns profiles and lessons, and claim-level validity dates are deferred.
status: accepted
decided_on: 2026-11-02
decided_by: Michał Kopeć
affects: AGENTS.md, wiki/index.md, wiki/tags.md, .agents/skills/ckb-ingest/, .agents/skills/ckb-lint/, .agents/skills/ckb-retrieve/, .agents/skills/ckb-profile/, .agents/skills/ckb-upgrade/, .agents/skills/ckb-init/, .agents/skills/ckb-reset/, .agents/skills/ckb-export-starlight/, docs/CHANGELOG.md, docs/MANUAL.md
confidence: 0.75
quality: 0.8
last_updated: 2026-11-02
freshness_window_days: 365
retention: high
---
# D-0014 — Schema 1.6: review, contradictions, tags, profiles and lessons
**Status:** Accepted · **Decided:** 2026-11-02 · **Deciders:** Michał Kopeć
## Context
Release 2 of the agent-knowledge plan (research report of 2026-10-31,
features F7, F4, F21, F9, F8) needs new page fields and conventions. The
plan named the review field `status`, but decision pages already use
`status` for `proposed`/`accepted`/…. One field with two vocabularies would
make every reader branch on `type`.
## Decision
Schema 1.6 is additive: every addition is optional, and a 1.5 page is a valid
1.6 page.
1. **Review (F7).** `review: draft | reviewed | needs_update`, plus
`reviewed_by` and `reviewed_on`. An absent `review` means "not tracked", not
"draft". `ckb-ingest` writes `review: draft` on pages it creates, and sets
`needs_update` when it changes the substance of a `reviewed` page.
Substance is what a page claims: prose, tables, `tldr`, `## Sources`,
`## Crux`. Links, index rows, formatting and metadata scores are not.
`reviewed_by`/`reviewed_on` keep naming the last review. `ckb-lint` owns
the review queue and "mark X as reviewed"; no new skill.
2. **Contradictions (F4, phase 1).** A line
`` > CONTRADICTION: <claim> (`<source>`) vs <claim> (`<source>`) — found YYYY-MM-DD ``
in the page body, written by `ckb-ingest` instead of silently picking a
winner. The page goes to `needs_update`. Lint lists every open marker; one
is closed by supersession, a `ckb-decide` record, or an edit the user
chose, and the marker is then removed with a log entry.
Claim-level `valid_from`/`valid_to` are **deferred**: prototype them on one
page type first.
3. **Tags (F21).** `tags: a, b` — a flat comma list, because page
frontmatter is flat. Every tag must be listed in `wiki/tags.md`
(`type: vocabulary`), a new scaffold file that the KB owns, the way the
graph has a closed verb list. `retrieve_candidates.py --tag` filters on
them.
4. **Scopes and profiles (F9).** Three scopes, in this order of precedence:
the rules in `AGENTS.md` always win; inside a project scope, the scope
page's `## Rules` section (new, reserved, human-owned and protected like
`## Notes`) wins next; a person's profile shapes how the agent works with
that person where neither says otherwise. Profiles live in
`workload/profiles/<author-slug>.md`, outside retrieval. The session-start
brief prints the profile of the session identity only. Profiles are
committed, so they hold only what the person is content to share.
5. **Lessons (F8).** Recorded only on an explicit trigger ("remember this",
"lesson: …"), never by guessing from tone. Format: rule, why, applies
when, scope, date. A personal lesson goes to the profile's `## Lessons`; a
KB lesson goes to `wiki/lessons.md` (`type: lessons`), which then carries
`review: needs_update` until someone reviews it. The brief lists KB
lessons added since the person's previous workload note.
6. **`ckb-profile`** is a new skill that owns profiles and lessons. No
existing skill fits, and both need a trigger of their own.
7. **Dropped from the plan:** a `verified` date on rules; `reviewed_on`
already says it.
## Alternatives considered
- **`status` with an exception for decisions** was rejected: two meanings
for one key.
- **A `ckb-review` skill** was rejected: lint already reports page health,
and one more description costs every session tokens.
- **Nested `rules.md` per project** was rejected: project scopes are single
pages, not folders.
- **Lessons detected from corrections automatically** were rejected: noisy,
and they would write to a shared KB on a guess.
## Consequences
- Draft pages are expected, not defects: lint shows a review queue but
counts only inconsistencies (a bad value, a reviewed page changed since
its review, an open contradiction, an unknown tag) as findings.
- `ckb-upgrade` migrates 1.5 → 1.6 by adding `wiki/tags.md` and bumping the
version. It backfills `review` only on request.
- The always-loaded layer grows by one skill description and a few lines in
`AGENTS.md`. The context budget meter (D-0013) measures it.

View file

@ -27,3 +27,4 @@ but they live here, in the template layer, because:
| [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 |
| [D-0014](0014-schema-1-6-review-contradictions-tags-profiles.md) | Schema 1.6: `review`/`reviewed_by`/`reviewed_on` (not `status`), `tags` against `wiki/tags.md`, a `> CONTRADICTION:` marker, protected `## Rules` on project scopes; profiles in `workload/profiles/` and explicit lessons via a new `ckb-profile` skill; claim-level validity deferred |

View file

@ -14,6 +14,10 @@
"index_log": [],
"evidence": [],
"crux": [],
"review": [],
"contradictions": [],
"tags": [],
"review_queue": [],
"hubs": [
[
"entities/atlas-retry-policy",

View file

@ -3,6 +3,7 @@
"k": 10,
"literal_tokens": [],
"scope_page": "wiki/projects/atlas.md",
"tags": [],
"inbox_hits": [],
"empty_graph": false,
"candidates": [
@ -24,6 +25,7 @@
"confidence": "0.9",
"quality": "0.8",
"superseded_by": null,
"review": null,
"sources": [
"raw/archive/2026-09-01/kickoff-notes.md",
"raw/archive/2026-09-02/dlq-review.md"
@ -52,6 +54,7 @@
"confidence": "0.8",
"quality": "0.8",
"superseded_by": null,
"review": null,
"sources": [
"raw/archive/2026-09-01/kickoff-notes.md"
],
@ -76,6 +79,7 @@
"confidence": "0.9",
"quality": "0.8",
"superseded_by": null,
"review": null,
"sources": [
"raw/archive/2026-09-01/kickoff-notes.md",
"raw/archive/2026-09-02"
@ -101,6 +105,7 @@
"confidence": null,
"quality": null,
"superseded_by": null,
"review": null,
"sources": [],
"corroborated_by": [],
"from_inbox": false
@ -121,6 +126,7 @@
"confidence": null,
"quality": null,
"superseded_by": null,
"review": null,
"sources": [],
"corroborated_by": [],
"from_inbox": false
@ -139,6 +145,7 @@
"confidence": null,
"quality": null,
"superseded_by": null,
"review": null,
"sources": [],
"corroborated_by": [],
"from_inbox": false
@ -157,6 +164,7 @@
"confidence": null,
"quality": null,
"superseded_by": null,
"review": null,
"sources": [],
"corroborated_by": [],
"from_inbox": false
@ -175,6 +183,7 @@
"confidence": null,
"quality": null,
"superseded_by": null,
"review": null,
"sources": [],
"corroborated_by": [],
"from_inbox": false
@ -193,6 +202,7 @@
"confidence": null,
"quality": null,
"superseded_by": null,
"review": null,
"sources": [],
"corroborated_by": [],
"from_inbox": false
@ -211,6 +221,7 @@
"confidence": null,
"quality": null,
"superseded_by": null,
"review": null,
"sources": [],
"corroborated_by": [],
"from_inbox": false
@ -229,6 +240,7 @@
"confidence": null,
"quality": null,
"superseded_by": null,
"review": null,
"sources": [],
"corroborated_by": [],
"from_inbox": false

View file

@ -85,6 +85,22 @@ echo "<private>do not keep</private>" >> "$TMP/sec/wiki/overview.md"
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"
# Schema 1.6: review fields, a contradiction marker, tags against a vocabulary, profile and lessons.
S16="$TMP/s16"; mkdir -p "$S16" && cp -r "$FIX/." "$S16/" && W="$S16/wiki"
printf -- '---\ntype: vocabulary\ntldr: Tags.\n---\n\n# Tags\n\n| Tag | Meaning | Use for |\n|---|---|---|\n| `retries` | Retry behaviour | Retry questions |\n' > "$W/tags.md"
echo '| [Tags](tags.md) | Tag vocabulary | Tagging |' >> "$W/index.md"
sed -i 's/^retention: high$/retention: high\ntags: retries, made-up\nreview: reviewed\nreviewed_by: Fixture User\nreviewed_on: 2026-09-01/' "$W/entities/atlas-retry-policy.md"
sed -i 's/^retention: medium$/retention: medium\nreview: draft/' "$W/entities/maria-nowak.md"
printf '\n> CONTRADICTION: three retries (`raw/archive/2026-09-01/kickoff-notes.md`) vs five retries (`raw/archive/2026-09-02/dlq-review.md`) — found 2026-09-24\n' >> "$W/entities/maria-nowak.md"
sed -i 's/^type: project$/type: project\nreview: approved/' "$W/projects/atlas.md"
printf -- '---\ntype: lessons\ntldr: Lessons.\nreview: needs_update\n---\n\n# Lessons\n\n### 2026-09-05 — Old lesson already seen\n- **Scope:** KB\n\n### 2026-09-20 — Cite the runbook for retry numbers\n- **Scope:** KB\n' > "$W/lessons.md"
( cd "$S16" && python3 "$OLDPWD/$LINT" --json --today "$TODAY" || true ) > "$TMP/s16-lint.json"
python3 "$RETR" "how many times does Atlas retry a failed batch" --root "$S16" --today "$TODAY" --tag retries --json > "$TMP/s16-retr.json"
SLUG=$(cd "$S16" && python3 -c "import sys;sys.path.insert(0,sys.argv[1]);import session_start as s;from pathlib import Path;print(s.author_slug(Path('.')))" "$OLDPWD/.agents/skills/ckb-lint/scripts")
mkdir -p "$S16/workload/profiles" && printf -- '---\ntype: profile\n---\n\n# Fixture\n\n## How to work with me\n- Answer in short bullets.\n' > "$S16/workload/profiles/$SLUG.md"
printf -- '---\ntype: session\n---\n\n## Earlier\n- worked\n' > "$S16/workload/2026-09-10_${SLUG}_summary.md"
( cd "$S16" && python3 "$OLDPWD/.agents/skills/ckb-lint/scripts/session_start.py" --today "$TODAY" --no-git ) > "$TMP/s16-start.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"
@ -139,6 +155,33 @@ python3 -c "import json,sys;h=json.load(open(sys.argv[1]))['hooks']['Stop'];c=[x
ls "$TMP"/proj/raw/saved-conversations/*/*.md >/dev/null 2>&1 && [[ ! -e "$TMP/proj/sub/raw" ]] \
|| { echo "autosave hook: run from a subfolder, it did not save into the project root"; fail=1; }
grep -q 'ckb check:' "$TMP/hookroot.json" || { echo "start hook: run from a subfolder, it printed no brief"; fail=1; }
python3 - "$TMP/s16-lint.json" <<'PY' || fail=1
import json, sys
t = json.load(open(sys.argv[1]))["trees"][0]
want = {"review": 2, "contradictions": 1, "tags": 1}
got = {k: len(t[k]) for k in want}
problems = [f"schema 1.6 lint: {k} expected {v}, got {got[k]}: {t[k]}" for k, v in want.items() if got[k] != v]
if not any("changed since its review" in f for f in t["review"]):
problems.append("schema 1.6 lint: reviewed page edited after review not flagged")
if not any("made-up" in f for f in t["tags"]):
problems.append("schema 1.6 lint: unknown tag not flagged")
if sorted(t["review_queue"]) != ["entities/maria-nowak.md (draft)", "lessons.md (needs_update)"]:
problems.append(f"schema 1.6 lint: review queue {t['review_queue']}")
problems and print("\n".join(problems)); sys.exit(1 if problems else 0)
PY
python3 -c "import json,sys;c=json.load(open(sys.argv[1]))['candidates'];assert [x['path'] for x in c]==['wiki/entities/atlas-retry-policy.md'] and c[0]['review']=='reviewed'" "$TMP/s16-retr.json" \
|| { echo "retrieve --tag: expected only the tagged page"; fail=1; }
grep -q '^profile: workload/profiles/' "$TMP/s16-start.txt" && grep -q 'Answer in short bullets' "$TMP/s16-start.txt" || { echo "session_start: profile not printed"; fail=1; }
grep -q '^lessons: 1 in wiki/lessons.md since your note of 2026-09-10' "$TMP/s16-start.txt" && grep -q 'Cite the runbook' "$TMP/s16-start.txt" \
|| { echo "session_start: new lesson not listed"; grep lessons "$TMP/s16-start.txt"; fail=1; }
grep -q '^### Open threads' "$TMP/start-threads.txt" && { echo "session_start: open threads printed twice"; fail=1; }
# A growing transcript: one `match:` allowlist entry covers the same key on every line.
mkdir -p "$TMP/sec/raw/saved-conversations/d" && for i in 1 2 3; do echo "turn $i AKIAQRSTUVWXYZABCDEF" >> "$TMP/sec/raw/saved-conversations/d/t.jsonl"; done
MH=$(cd "$TMP/sec" && { python3 "$OLDPWD/$LINT" --secrets || true; } | grep 't.jsonl' | grep -o 'match:[0-9a-f]*' | head -1)
echo "raw/saved-conversations/*/*.jsonl $MH" >> "$TMP/sec/.secrets-allow"
[[ "$(cd "$TMP/sec" && python3 "$OLDPWD/$LINT" --secrets | tail -1)" == "secrets: 1 possible" ]] || { echo "secrets: match: allowlist entry not honoured"; fail=1; }
[[ "$(cd "$TMP/sec" && bash "$OLDPWD/$QUICK" --today "$TODAY" | sed 's/ (fallback:.*//')" == "ckb check: 1 possible secrets — run \"lint\" for detail" ]] \
|| { echo "lint_quick.sh: match: allowlist entry not honoured"; 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).

View file

@ -1,5 +1,5 @@
---
kb_schema_version: "1.5"
kb_schema_version: "1.6"
---
# Knowledge Base Index
@ -16,6 +16,7 @@ kb_schema_version: "1.5"
| [Decisions](decisions/index.md) | Numbered decision records — what was decided, by whom, when, why, and what it superseded | Asking why something is the way it is, who decided it, when, what changed it, or what is still open |
| [Entities](entities/index.md) | Typed entity pages (people, projects, libraries, concepts) | Looking up a specific person, project, library, or concept |
| [Graph](graph/index.md) | Edge lists and relationship data between entities | Finding what depends on / relates to a given entity |
| [Tags](tags.md) | The closed vocabulary for the optional `tags:` page field | Tagging a page, or filtering retrieval by tag |
## Entity Pages

16
wiki/tags.md Normal file
View file

@ -0,0 +1,16 @@
---
type: vocabulary
tldr: The closed list of tags a page may carry in its `tags:` field; ckb-lint flags any tag not listed here.
last_updated: 2026-11-02
---
# Tags
Every value in a page's `tags:` frontmatter must appear in this table. Add a
row before using a new tag. Keep tags lower-case and hyphenated, and keep the
list short: a tag that fits most pages tells retrieval nothing.
| Tag | Meaning | Use for |
|---|---|---|
*(No tags yet. Add the first row when a page needs one.)*