diff --git a/.agents/skills/ckb-decide/SKILL.md b/.agents/skills/ckb-decide/SKILL.md index b381f43..f5ea0fa 100644 --- a/.agents/skills/ckb-decide/SKILL.md +++ b/.agents/skills/ckb-decide/SKILL.md @@ -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 diff --git a/.agents/skills/ckb-export-okf/SKILL.md b/.agents/skills/ckb-export-okf/SKILL.md index 59e6a72..3a6b2fb 100644 --- a/.agents/skills/ckb-export-okf/SKILL.md +++ b/.agents/skills/ckb-export-okf/SKILL.md @@ -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 | diff --git a/.agents/skills/ckb-export-starlight/SKILL.md b/.agents/skills/ckb-export-starlight/SKILL.md index b41f284..b3f59a4 100644 --- a/.agents/skills/ckb-export-starlight/SKILL.md +++ b/.agents/skills/ckb-export-starlight/SKILL.md @@ -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]]` diff --git a/.agents/skills/ckb-export-starlight/scripts/export_starlight.py b/.agents/skills/ckb-export-starlight/scripts/export_starlight.py index 3016a7e..d6d7dc7 100644 --- a/.agents/skills/ckb-export-starlight/scripts/export_starlight.py +++ b/.agents/skills/ckb-export-starlight/scripts/export_starlight.py @@ -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"} diff --git a/.agents/skills/ckb-ingest/SKILL.md b/.agents/skills/ckb-ingest/SKILL.md index 9b08392..2f72c74 100644 --- a/.agents/skills/ckb-ingest/SKILL.md +++ b/.agents/skills/ckb-ingest/SKILL.md @@ -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/.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 diff --git a/.agents/skills/ckb-init/SKILL.md b/.agents/skills/ckb-init/SKILL.md index 1732782..c1f27cf 100644 --- a/.agents/skills/ckb-init/SKILL.md +++ b/.agents/skills/ckb-init/SKILL.md @@ -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 diff --git a/.agents/skills/ckb-lint/SKILL.md b/.agents/skills/ckb-lint/SKILL.md index 107f3c6..fc2315a 100644 --- a/.agents/skills/ckb-lint/SKILL.md +++ b/.agents/skills/ckb-lint/SKILL.md @@ -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// 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// 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//` (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 diff --git a/.agents/skills/ckb-lint/references/manual-checklist.md b/.agents/skills/ckb-lint/references/manual-checklist.md index eaabe35..0e8c4d3 100644 --- a/.agents/skills/ckb-lint/references/manual-checklist.md +++ b/.agents/skills/ckb-lint/references/manual-checklist.md @@ -22,6 +22,9 @@ say what was skipped — by hand, this costs tokens. | 13 | Crux verbatimness | For each `## Crux` quote, `rg -F '' ` — 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 '' 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 diff --git a/.agents/skills/ckb-lint/scripts/lint_quick.ps1 b/.agents/skills/ckb-lint/scripts/lint_quick.ps1 index 5f96e31..7f10aef 100644 --- a/.agents/skills/ckb-lint/scripts/lint_quick.ps1 +++ b/.agents/skills/ckb-lint/scripts/lint_quick.ps1 @@ -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 = @() # ` match:`: 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++ } } } diff --git a/.agents/skills/ckb-lint/scripts/lint_quick.sh b/.agents/skills/ckb-lint/scripts/lint_quick.sh index 2306da6..ee62368 100755 --- a/.agents/skills/ckb-lint/scripts/lint_quick.sh +++ b/.agents/skills/ckb-lint/scripts/lint_quick.sh @@ -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 + # ` match:` 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 diff --git a/.agents/skills/ckb-lint/scripts/lint_report.py b/.agents/skills/ckb-lint/scripts/lint_report.py index b7a7745..02bf221 100644 --- a/.agents/skills/ckb-lint/scripts/lint_report.py +++ b/.agents/skills/ckb-lint/scripts/lint_report.py @@ -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 ` ` per line.""" + """`.secrets-allow`, one entry per line, two shapes: + + this one line, while its text is unchanged + match: 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 `` 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: diff --git a/.agents/skills/ckb-lint/scripts/session_start.py b/.agents/skills/ckb-lint/scripts/session_start.py index 98795e5..b64fcbb 100644 --- a/.agents/skills/ckb-lint/scripts/session_start.py +++ b/.agents/skills/ckb-lint/scripts/session_start.py @@ -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 : ... routines.py --due, one line per due routine threads: N open ... unticked `- [ ]` under "Open threads" in workload/ notes; only when any + profile: workload/profiles/.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: (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:") diff --git a/.agents/skills/ckb-profile/SKILL.md b/.agents/skills/ckb-profile/SKILL.md new file mode 100644 index 0000000..c5ffb88 --- /dev/null +++ b/.agents/skills/ckb-profile/SKILL.md @@ -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/.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/.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 + + +## How to work with me + + +## Lessons + +``` + +**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 `…` 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 — +- **Why:** +- **Applies when:** +- **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. diff --git a/.agents/skills/ckb-reset/SKILL.md b/.agents/skills/ckb-reset/SKILL.md index 1844c59..3ee7fb2 100644 --- a/.agents/skills/ckb-reset/SKILL.md +++ b/.agents/skills/ckb-reset/SKILL.md @@ -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": "", "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. diff --git a/.agents/skills/ckb-retrieve/SKILL.md b/.agents/skills/ckb-retrieve/SKILL.md index 7f628f1..83db986 100644 --- a/.agents/skills/ckb-retrieve/SKILL.md +++ b/.agents/skills/ckb-retrieve/SKILL.md @@ -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 ` (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 diff --git a/.agents/skills/ckb-retrieve/scripts/retrieve_candidates.py b/.agents/skills/ckb-retrieve/scripts/retrieve_candidates.py index 5da9baf..d13294f 100755 --- a/.agents/skills/ckb-retrieve/scripts/retrieve_candidates.py +++ b/.agents/skills/ckb-retrieve/scripts/retrieve_candidates.py @@ -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/ 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"]: diff --git a/.agents/skills/ckb-upgrade/SKILL.md b/.agents/skills/ckb-upgrade/SKILL.md index 11c5c7a..8fb3abc 100644 --- a/.agents/skills/ckb-upgrade/SKILL.md +++ b/.agents/skills/ckb-upgrade/SKILL.md @@ -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. diff --git a/AGENTS.md b/AGENTS.md index 0930cd3..d33a849 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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__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: (``) vs (``) — 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 ` once it completes, and report it in one line. A `confirm: true` routine is asked diff --git a/README.md b/README.md index dde4955..c14d64e 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/README.pl.md b/README.pl.md index 889a5aa..1d718fa 100644 --- a/README.pl.md +++ b/README.pl.md @@ -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ść. diff --git a/VERSION b/VERSION index 6245bee..a6c2798 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.22.1 +1.23.0 diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 26f0231..a402657 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -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:` / `mtime:` 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 ` match:` 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 `` 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 `` 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__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 | diff --git a/docs/CHANGELOG.pl.md b/docs/CHANGELOG.pl.md index 9b53c4f..d463ba5 100644 --- a/docs/CHANGELOG.pl.md +++ b/docs/CHANGELOG.pl.md @@ -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:` / `mtime:` 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 ` match:`, 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 `` 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 ``; `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__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 | diff --git a/docs/MANUAL.md b/docs/MANUAL.md index 23d7af8..8a94cf9 100644 --- a/docs/MANUAL.md +++ b/docs/MANUAL.md @@ -224,6 +224,18 @@ Three things happen before anything is written: `` 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 ` ` 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/.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//`; 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` | diff --git a/docs/MANUAL.pl.md b/docs/MANUAL.pl.md index f8b328f..9c24416 100644 --- a/docs/MANUAL.pl.md +++ b/docs/MANUAL.pl.md @@ -234,6 +234,18 @@ Zanim cokolwiek zostanie zapisane, dzieją się trzy rzeczy: `` … ``, 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/.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` | diff --git a/docs/decisions/0014-schema-1-6-review-contradictions-tags-profiles.md b/docs/decisions/0014-schema-1-6-review-contradictions-tags-profiles.md new file mode 100644 index 0000000..0ca369b --- /dev/null +++ b/docs/decisions/0014-schema-1-6-review-contradictions-tags-profiles.md @@ -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: (``) vs (``) — 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/.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. diff --git a/docs/decisions/README.md b/docs/decisions/README.md index 7aa09d9..6d0d739 100644 --- a/docs/decisions/README.md +++ b/docs/decisions/README.md @@ -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 `` 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 | diff --git a/tests/expected/lint.json b/tests/expected/lint.json index 0659028..2cdb312 100644 --- a/tests/expected/lint.json +++ b/tests/expected/lint.json @@ -14,6 +14,10 @@ "index_log": [], "evidence": [], "crux": [], + "review": [], + "contradictions": [], + "tags": [], + "review_queue": [], "hubs": [ [ "entities/atlas-retry-policy", diff --git a/tests/expected/retrieve.json b/tests/expected/retrieve.json index f274619..1d91b12 100644 --- a/tests/expected/retrieve.json +++ b/tests/expected/retrieve.json @@ -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 diff --git a/tests/smoke.sh b/tests/smoke.sh index e535995..977ec2a 100755 --- a/tests/smoke.sh +++ b/tests/smoke.sh @@ -85,6 +85,22 @@ echo "do not keep" >> "$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?#hunter2 is the vault code 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). diff --git a/wiki/index.md b/wiki/index.md index 3139486..401c10a 100644 --- a/wiki/index.md +++ b/wiki/index.md @@ -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 diff --git a/wiki/tags.md b/wiki/tags.md new file mode 100644 index 0000000..c14111a --- /dev/null +++ b/wiki/tags.md @@ -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.)*