Template 1.23.0: agent-knowledge release 2, schema 1.6
Schema 1.6, all fields optional (D-0014): - F7 review: `review: draft|reviewed|needs_update`, `reviewed_by`, `reviewed_on`; lint check 17 and a review queue; ckb-lint marks reviews - F4 `> CONTRADICTION:` marker, lint check 18; validity dates deferred - F21 `tags` against the new `wiki/tags.md`, lint check 19, retrieve_candidates.py --tag, DRAFT/NEEDS_UPDATE flags - F9 profiles in workload/profiles/, protected `## Rules` on project scope pages, precedence AGENTS.md > Rules > profile - F8 explicit lessons (profile or wiki/lessons.md); new ckb-profile skill Carry-over: `.secrets-allow` `<glob> match:<hash>` entries (also in the bash/PowerShell fallbacks); open threads no longer print twice. ckb-upgrade migrates 1.5 -> 1.6; init/reset know tags.md; Starlight shows review and tags. Smoke test covers a 1.6 KB. Docs in EN and PL. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
parent
aaeabf3071
commit
bf2cc8e8aa
32 changed files with 901 additions and 50 deletions
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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 |
|
||||
|
||||
|
|
|
|||
|
|
@ -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]]`
|
||||
|
|
|
|||
|
|
@ -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"}
|
||||
|
|
|
|||
|
|
@ -104,6 +104,10 @@ the notes. If the material only *references* a decision without recording
|
|||
it ("as agreed last quarter, we use Postgres"), that's a query-gap candidate,
|
||||
not a decision record — you don't have the rationale or the date.
|
||||
|
||||
When the material falls inside a project scope, read that scope page's
|
||||
`## Rules` before writing and follow them; they are the team's, and this
|
||||
skill never edits them.
|
||||
|
||||
For recurring teams, clients, systems, or initiatives, consider whether a
|
||||
plain project scope page under `wiki/projects/<name>.md` would make future
|
||||
queries easier to route. A scope page should list when to use it, included
|
||||
|
|
@ -129,9 +133,17 @@ into:
|
|||
- **Extends** — the new material adds detail the page doesn't have. Update
|
||||
the page in Step 5.
|
||||
- **Contradicts** — the new material and the page can't both be right. This
|
||||
is the case worth catching: handle it as supersession (see Edge cases), and
|
||||
say so explicitly in the report rather than letting the newer page silently
|
||||
win.
|
||||
is the case worth catching. When the new material clearly replaces the old
|
||||
(a later version of the same document, a recorded decision), handle it as
|
||||
supersession (see Edge cases). When it is not clear which is right, write a
|
||||
marker into the affected page instead of choosing:
|
||||
|
||||
```markdown
|
||||
> CONTRADICTION: retries 3 times (`raw/archive/2026-09-01/kickoff-notes.md`) vs retries 5 times (`raw/archive/2026-11-02/runbook.md`) — found 2026-11-02
|
||||
```
|
||||
|
||||
and set the page to `review: needs_update`. Either way, say so explicitly
|
||||
in the report rather than letting the newer page silently win.
|
||||
- **Untouched** — most of the radius. Drop it and move on.
|
||||
|
||||
Name the owners too. Where an `owns` or `has_expertise_in` edge points at an
|
||||
|
|
@ -164,6 +176,13 @@ gets frontmatter with:
|
|||
- A `last_updated:` timestamp.
|
||||
- A `freshness_window_days:` appropriate to the topic.
|
||||
- A `retention:` level.
|
||||
- `review: draft` on a page this run creates. On a page that is already
|
||||
`review: reviewed`, a change to what it claims (prose, tables, `tldr`,
|
||||
`## Sources`, `## Crux`) sets `review: needs_update`; leave `reviewed_by`
|
||||
and `reviewed_on` as the record of the last review. New links, index rows
|
||||
and formatting are not substance and leave `review` alone.
|
||||
- `tags:` only when a tag in `wiki/tags.md` fits. Never invent one here: a
|
||||
new tag is a row in the vocabulary first, and that is the user's call.
|
||||
|
||||
`type` is also required (per the page frontmatter schema in
|
||||
`CLAUDE.md`/`AGENTS.md` page schema) — set it once, based on the entity/content
|
||||
|
|
@ -328,7 +347,7 @@ started: HH:MM
|
|||
## Blast radius
|
||||
- **Confirmed:** …
|
||||
- **Extended:** …
|
||||
- **Contradicted:** `/wiki/entities/x.md` — superseded by … — review: Owner Name
|
||||
- **Contradicted:** `/wiki/entities/x.md` — superseded by … / CONTRADICTION marker written — review: Owner Name
|
||||
- **Query gaps closed:** …
|
||||
|
||||
## Not ingested
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: ckb-lint
|
||||
description: Health-check wiki/ — frontmatter conformance, freshness, confidence decay, retention, supersession, orphans, graph consistency, index/log drift, source-fingerprint drift, committed secrets, context budget — auto-fixing what is safe and reporting the rest. Also checks each connector-backed libs/<name>/ generated index. Use for "Lint", "health-check the wiki", "check the wiki", or a scheduled wiki health check.
|
||||
description: Health-check wiki/ — frontmatter conformance, freshness, confidence decay, retention, supersession, orphans, graph consistency, index/log drift, source-fingerprint drift, review status, open contradictions, tags, committed secrets, context budget — auto-fixing what is safe and reporting the rest. Also checks each connector-backed libs/<name>/ generated index, and marks pages reviewed. Use for "Lint", "health-check the wiki", "check the wiki", "what needs review", "mark X as reviewed", or a scheduled wiki health check.
|
||||
---
|
||||
|
||||
# Lint skill
|
||||
|
|
@ -53,7 +53,7 @@ when there are findings — read the report either way.
|
|||
|
||||
The script is strictly read-only: it writes nothing, moves nothing, and
|
||||
runs no `git` commands. It covers the mechanical detection in checks 1, 2,
|
||||
3, 4, 6, 7, 8, 10, 12, 13, 15 and 16 below — plus the structural half of check 5
|
||||
3, 4, 6, 7, 8, 10, 12, 13 and 15–19 below — plus the structural half of check 5
|
||||
(decision records) — across `wiki/` and every connector-backed
|
||||
`libs/<name>/` (reporting each one's `access:` level so you know where a
|
||||
fix is even permitted). Check 9, the semantic half of check 5, and every
|
||||
|
|
@ -322,6 +322,47 @@ sources changed or vanished, or that has no `## Sources`. Report only:
|
|||
re-answering is a retrieval, not a lint fix. Suggest re-asking the question
|
||||
and replacing the kept answer.
|
||||
|
||||
### 17 — Review status (schema 1.6)
|
||||
|
||||
A page may carry `review: draft | reviewed | needs_update`, with
|
||||
`reviewed_by` and `reviewed_on`. No `review` field means "not tracked".
|
||||
Drafts are expected, so they are not findings. The script reports only
|
||||
inconsistencies: an unknown value, a `reviewed` page without
|
||||
`reviewed_by`/`reviewed_on`, and a `reviewed` page whose `last_updated` is
|
||||
later than `reviewed_on`. For the last one, compare the page with its
|
||||
previous version (`git log -p`); if what it claims changed, set
|
||||
`review: needs_update`. If only links or formatting changed, say so and ask
|
||||
the user to re-review.
|
||||
|
||||
The report also prints a **review queue**: every `draft` and `needs_update`
|
||||
page. "What needs review?" is answered from it, `needs_update` first,
|
||||
because those pages were reviewed once and have moved since.
|
||||
|
||||
**Marking a review** ("mark X as reviewed", "I've checked X"): only on the
|
||||
person's say-so, and only for the pages they name. Set `review: reviewed`,
|
||||
`reviewed_by` to the session identity's name and `reviewed_on` to today.
|
||||
Leave `last_updated` alone, because the page itself did not change. Log it
|
||||
under Rule B as `REVIEW`. Never mark a page reviewed that the person has
|
||||
not said they read, and never mark a whole directory on a general "looks
|
||||
fine".
|
||||
|
||||
### 18 — Open contradictions
|
||||
|
||||
Every `> CONTRADICTION:` line in a page body is listed until someone resolves
|
||||
it. Never resolve one by picking a side yourself. Show both claims with their
|
||||
sources and offer three routes: supersede one page (two-sided
|
||||
`supersedes`/`superseded_by`), record a decision with `ckb-decide`, or edit
|
||||
the claim the way the person decides. Then remove the marker, keep
|
||||
`review: needs_update` until someone reviews the result, and log it.
|
||||
|
||||
### 19 — Tags
|
||||
|
||||
`tags:` values must appear in `wiki/tags.md`, a table whose first column
|
||||
holds each tag in backticks. A page with an unknown tag is reported, never
|
||||
auto-fixed: either the vocabulary gains a row (the user's call) or the page
|
||||
drops the tag. A connector-backed lib is checked against its own `tags.md`
|
||||
when it has one.
|
||||
|
||||
### Context budget
|
||||
|
||||
`--quick` and the full report flag an always-loaded layer — `AGENTS.md` plus
|
||||
|
|
|
|||
|
|
@ -22,6 +22,9 @@ say what was skipped — by hand, this costs tokens.
|
|||
| 13 | Crux verbatimness | For each `## Crux` quote, `rg -F '<first ~40 chars>' <cited source>` — a miss means the evidence moved. Only practical for a few pages; list candidates and ask which to verify. |
|
||||
| 15 | Secrets and private spans | `rg -n 'BEGIN [A-Z ]*PRIVATE KEY|AKIA[0-9A-Z]{16}|gh[pousr]_[A-Za-z0-9]{36}|xox[abprs]-|sk-[A-Za-z0-9_-]{20}|AIza[0-9A-Za-z_-]{35}|://[^/ :@]+:[^/ @]+@' wiki outputs workload raw` and `rg -n -i '<private>' wiki`. `lint_quick.sh`/`.ps1` counts the reduced set. |
|
||||
| 16 | Kept answers | For each `outputs/answers/*.md`, check its `## Sources` fingerprints as in check 12. |
|
||||
| 17 | Review status | `rg -n '^review:' wiki` — values must be draft/reviewed/needs_update; for each `reviewed` page compare `last_updated` with `reviewed_on`. `rg -l '^review: (draft|needs_update)' wiki` is the review queue. |
|
||||
| 18 | Contradictions | `rg -n '^> *CONTRADICTION:' wiki` — every hit is open until resolved. |
|
||||
| 19 | Tags | `rg -n '^tags:' wiki` against the backticked first column of `wiki/tags.md`. |
|
||||
| — | Context budget | `wc -c AGENTS.md` ÷ 4, plus each skill's `description:` line ÷ 4, against `budget: always_loaded_tokens` in `ckb.yaml` (default 9000). |
|
||||
|
||||
Checks 9–11 (error book, supersession judgment, auto-fix vs. report) are
|
||||
|
|
|
|||
|
|
@ -128,10 +128,13 @@ foreach ($tree in $trees) {
|
|||
$secretRe = '-----BEGIN ([A-Z0-9]+ )*PRIVATE KEY-----|(AKIA|ASIA)[0-9A-Z]{16}|gh[pousr]_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{50,}|xox[abprs]-[A-Za-z0-9-]{10,}|sk-(ant-|proj-)?[A-Za-z0-9_-]{20,}|AIza[0-9A-Za-z_-]{35}'
|
||||
$secretExt = @('.md','.txt','.eml','.csv','.json','.jsonl','.yaml','.yml','.html','.log','.env','.ini','.toml','.sh','.py','.js','.ts','.xml')
|
||||
$allow = @{}
|
||||
$allowMatch = @() # `<glob> match:<hash>`: one matched string, every matching file
|
||||
if (Test-Path -LiteralPath ".secrets-allow" -PathType Leaf) {
|
||||
foreach ($a in (Get-Content -LiteralPath ".secrets-allow")) {
|
||||
$parts = (($a -split '#', 2)[0]).Trim() -split '\s+'
|
||||
if ($parts.Count -eq 2) { $allow["$($parts[0].TrimStart('/')) $($parts[1].ToLowerInvariant())"] = $true }
|
||||
if ($parts.Count -ne 2) { continue }
|
||||
if ($parts[1] -like 'match:*') { $allowMatch += ,@($parts[0].TrimStart('/'), $parts[1].Substring(6).ToLowerInvariant()); continue }
|
||||
$allow["$($parts[0].TrimStart('/')) $($parts[1].ToLowerInvariant())"] = $true
|
||||
}
|
||||
}
|
||||
$sha = [Security.Cryptography.SHA256]::Create()
|
||||
|
|
@ -148,7 +151,11 @@ foreach ($top in @("wiki", "outputs", "workload", "raw")) {
|
|||
if ($line -cnotmatch $secretRe) { continue }
|
||||
$bytes = [Text.Encoding]::UTF8.GetBytes($line.Trim())
|
||||
$h = (-join ($sha.ComputeHash($bytes) | ForEach-Object { $_.ToString("x2") })).Substring(0, 8)
|
||||
if (-not $allow.ContainsKey("$rel $h")) { $secrets++ }
|
||||
if ($allow.ContainsKey("$rel $h")) { continue }
|
||||
$m = [regex]::Match($line, $secretRe).Value
|
||||
$mh = (-join ($sha.ComputeHash([Text.Encoding]::UTF8.GetBytes($m)) | ForEach-Object { $_.ToString("x2") })).Substring(0, 8)
|
||||
if ($allowMatch | Where-Object { $_[1] -eq $mh -and $rel -like $_[0] }) { continue }
|
||||
$secrets++
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -145,6 +145,12 @@ if (( ${#scan[@]} )); then
|
|||
skip_secret "$file" && continue
|
||||
trimmed=$(printf '%s' "$line" | sed 's/^[[:space:]]*//; s/[[:space:]]*$//')
|
||||
if [[ -f .secrets-allow ]] && grep -Eq "^[[:space:]]*/?${file//./\\.}[[:space:]]+$(sha_str "$trimmed")([[:space:]]|#|$)" .secrets-allow; then continue; fi
|
||||
# `<glob> match:<hash>` allows one matched string in every matching file.
|
||||
m=$(printf '%s' "$line" | grep -oE -e "$SECRET_RE" | head -n1); mh=$(sha_str "$m"); allowed=0
|
||||
while read -r glob want _; do
|
||||
[[ "$want" == "match:$mh" && "$file" == ${glob#/} ]] && { allowed=1; break; }
|
||||
done < <(sed 's/#.*//' .secrets-allow 2>/dev/null | grep 'match:' || true)
|
||||
(( allowed )) && continue
|
||||
secrets=$((secrets+1))
|
||||
done < <(grep -rEn "${INCLUDES[@]}" -e "$SECRET_RE" "${scan[@]}" 2>/dev/null)
|
||||
fi
|
||||
|
|
|
|||
|
|
@ -35,6 +35,7 @@ mechanical; deciding that a new decision *replaces* an old one is not.
|
|||
Exit code is 0 when nothing was found and 1 when there are findings.
|
||||
"""
|
||||
import argparse
|
||||
import fnmatch
|
||||
import hashlib
|
||||
import json
|
||||
import re
|
||||
|
|
@ -698,6 +699,89 @@ def check_crux(docs, root):
|
|||
)
|
||||
return findings
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# review (check 17), contradictions (check 18), tags (check 19) — schema 1.6
|
||||
# --------------------------------------------------------------------------
|
||||
|
||||
REVIEW_STATES = {"draft", "reviewed", "needs_update"}
|
||||
CONTRADICTION_RE = re.compile(r"^>\s*CONTRADICTION:\s*(.*)$", re.M)
|
||||
TAG_ROW_RE = re.compile(r"^\|\s*`([^`]+)`\s*\|", re.M)
|
||||
|
||||
|
||||
def check_review(docs):
|
||||
"""Check 17 — the review fields are consistent. A draft is not a finding;
|
||||
a reviewed page edited after its review is."""
|
||||
findings = []
|
||||
for doc in docs:
|
||||
if doc.reserved or doc.fm_error or "review" not in doc.fm:
|
||||
continue
|
||||
rel, state = doc.rel.as_posix(), doc.fm.get("review", "").strip().lower()
|
||||
if state not in REVIEW_STATES:
|
||||
findings.append(f"{rel}: `review: {state}` is not one of {', '.join(sorted(REVIEW_STATES))}")
|
||||
continue
|
||||
if state != "reviewed":
|
||||
continue
|
||||
on = as_date(doc.fm.get("reviewed_on"))
|
||||
if not doc.fm.get("reviewed_by", "").strip():
|
||||
findings.append(f"{rel}: `review: reviewed` but no `reviewed_by`")
|
||||
if on is None:
|
||||
findings.append(f"{rel}: `review: reviewed` but no valid `reviewed_on` date")
|
||||
continue
|
||||
updated = as_date(doc.fm.get("last_updated"))
|
||||
if updated and updated > on:
|
||||
findings.append(f"{rel}: changed since its review (last_updated {updated.isoformat()}, "
|
||||
f"reviewed_on {on.isoformat()}) — set `review: needs_update`, or review it again")
|
||||
return findings
|
||||
|
||||
|
||||
def review_queue(docs):
|
||||
"""Pages awaiting a person: not findings, a to-do list."""
|
||||
return [f"{d.rel.as_posix()} ({d.fm['review'].strip().lower()})" for d in docs
|
||||
if not d.reserved and not d.fm_error
|
||||
and d.fm.get("review", "").strip().lower() in ("draft", "needs_update")]
|
||||
|
||||
|
||||
def check_contradictions(docs):
|
||||
"""Check 18 — every open `> CONTRADICTION:` marker, until a person resolves it."""
|
||||
findings = []
|
||||
for doc in docs:
|
||||
if doc.reserved:
|
||||
continue
|
||||
for m in CONTRADICTION_RE.finditer(doc.body):
|
||||
findings.append(f"{doc.rel.as_posix()}: open contradiction — {m.group(1).strip()[:120]}")
|
||||
return findings
|
||||
|
||||
|
||||
def tag_vocabulary(root):
|
||||
"""Tags listed in `tags.md` (a table whose first cell is a backticked tag), or None."""
|
||||
path = root / "tags.md"
|
||||
if not path.is_file():
|
||||
return None
|
||||
return {t.strip().lower() for t in TAG_ROW_RE.findall(path.read_text(encoding="utf-8", errors="replace"))}
|
||||
|
||||
|
||||
def page_tags(doc):
|
||||
return [t.strip().lower() for t in doc.fm.get("tags", "").strip("[]").split(",") if t.strip()]
|
||||
|
||||
|
||||
def check_tags(root, docs):
|
||||
"""Check 19 — every `tags:` value is in the tree's vocabulary (`tags.md`)."""
|
||||
findings, vocab = [], tag_vocabulary(root)
|
||||
for doc in docs:
|
||||
if doc.reserved or doc.fm_error:
|
||||
continue
|
||||
tags = page_tags(doc)
|
||||
if not tags:
|
||||
continue
|
||||
if vocab is None:
|
||||
findings.append(f"{doc.rel.as_posix()}: has `tags` but the tree has no tags.md vocabulary")
|
||||
continue
|
||||
for tag in tags:
|
||||
if tag not in vocab:
|
||||
findings.append(f"{doc.rel.as_posix()}: tag `{tag}` is not in tags.md — add it there or drop it")
|
||||
return findings
|
||||
|
||||
|
||||
# --------------------------------------------------------------------------
|
||||
# secrets and private spans (check 15), saved answers (check 16), budget
|
||||
# --------------------------------------------------------------------------
|
||||
|
|
@ -741,22 +825,37 @@ def line_hash(line):
|
|||
|
||||
|
||||
def secret_allowlist():
|
||||
"""{(path, line hash)} from `.secrets-allow`: one `<path> <hash>` per line."""
|
||||
"""`.secrets-allow`, one entry per line, two shapes:
|
||||
|
||||
<path> <line hash> this one line, while its text is unchanged
|
||||
<path glob> match:<hash> every occurrence of one matched string in the
|
||||
matching files — for a transcript that grows
|
||||
|
||||
Returns ({(path, line hash)}, [(glob, match hash)])."""
|
||||
path = REPO_ROOT / SECRETS_ALLOW
|
||||
allowed = set()
|
||||
lines, matches = set(), []
|
||||
if not path.is_file():
|
||||
return allowed
|
||||
return lines, matches
|
||||
for raw in path.read_text(encoding="utf-8", errors="replace").splitlines():
|
||||
parts = raw.split("#", 1)[0].split()
|
||||
if len(parts) == 2:
|
||||
allowed.add((parts[0].lstrip("/"), parts[1].lower()))
|
||||
return allowed
|
||||
if len(parts) != 2:
|
||||
continue
|
||||
where, h = parts[0].lstrip("/"), parts[1].lower()
|
||||
if h.startswith("match:"):
|
||||
matches.append((where, h[len("match:"):]))
|
||||
else:
|
||||
lines.add((where, h))
|
||||
return lines, matches
|
||||
|
||||
|
||||
def match_hash(text):
|
||||
return hashlib.sha256(text.encode("utf-8")).hexdigest()[:8]
|
||||
|
||||
|
||||
def check_secrets():
|
||||
"""Check 15 — credential shapes in committed text, and `<private>` spans
|
||||
that reached `wiki/`. The finding never repeats the secret itself."""
|
||||
findings, allowed = [], secret_allowlist()
|
||||
findings, (allowed, allowed_matches) = [], secret_allowlist()
|
||||
for top in SECRET_SCAN_DIRS:
|
||||
base = REPO_ROOT / top
|
||||
if not base.is_dir():
|
||||
|
|
@ -788,15 +887,18 @@ def check_secrets():
|
|||
for m in ASSIGNED_VALUE_RE.finditer(text):
|
||||
key = ASSIGNED_KEY_RE.search(text, max(0, m.start() - 24), m.start())
|
||||
if key:
|
||||
hits.setdefault(lineno(key.start()), ("assigned secret", key.group(0)))
|
||||
hits.setdefault(lineno(key.start()), ("assigned secret", text[key.start():m.end()]))
|
||||
if not hits:
|
||||
continue
|
||||
lines = text.split("\n")
|
||||
for n, (label, match) in sorted(hits.items()):
|
||||
h = line_hash(lines[n - 1])
|
||||
if (rel, h) not in allowed:
|
||||
findings.append(f"{rel}:{n}: possible {label} ({match[:4]}…) "
|
||||
f"— if harmless, add `{rel} {h}` to {SECRETS_ALLOW}")
|
||||
h, mh = line_hash(lines[n - 1]), match_hash(match)
|
||||
if (rel, h) in allowed or any(mh == want and fnmatch.fnmatch(rel, glob)
|
||||
for glob, want in allowed_matches):
|
||||
continue
|
||||
findings.append(f"{rel}:{n}: possible {label} ({match[:4]}…) "
|
||||
f"— if harmless, add `{rel} {h}` (this line) or `{rel} match:{mh}` "
|
||||
f"(this string, every line) to {SECRETS_ALLOW}")
|
||||
return findings
|
||||
|
||||
|
||||
|
|
@ -874,6 +976,9 @@ CHECKS = [
|
|||
("8 index/log", "index_log"),
|
||||
("12 source fingerprints", "evidence"),
|
||||
("13 crux", "crux"),
|
||||
("17 review", "review"),
|
||||
("18 contradictions", "contradictions"),
|
||||
("19 tags", "tags"),
|
||||
]
|
||||
|
||||
# The subset worth running at session start (Rule E): cheap, and each finding
|
||||
|
|
@ -900,6 +1005,10 @@ def run_tree(root, today, label):
|
|||
"index_log": check_index_and_logs(root, docs),
|
||||
"evidence": check_evidence(docs, root),
|
||||
"crux": check_crux(docs, root),
|
||||
"review": check_review(docs),
|
||||
"contradictions": check_contradictions(docs),
|
||||
"tags": check_tags(root, docs),
|
||||
"review_queue": review_queue(docs),
|
||||
"hubs": in_degree(root, docs),
|
||||
}
|
||||
|
||||
|
|
@ -1016,6 +1125,9 @@ def main():
|
|||
if tree["hubs"]:
|
||||
top = ", ".join(f"{name} ({n})" for name, n in tree["hubs"][:5])
|
||||
print(f" [in-degree] most-referenced pages: {top}")
|
||||
if tree["review_queue"]:
|
||||
shown = ", ".join(tree["review_queue"][:8]) + (" …" if len(tree["review_queue"]) > 8 else "")
|
||||
print(f" [review queue] {len(tree['review_queue'])} page(s) await a person: {shown}")
|
||||
if args.scope in ("libs", "all"):
|
||||
print("=== external sources (libs/*/source.yaml)")
|
||||
if source_findings:
|
||||
|
|
|
|||
|
|
@ -16,6 +16,8 @@ What it prints, one line each (plus the tail of the latest workload note):
|
|||
start hook: ... start_hook.py --check, only when it needs action
|
||||
routines: none due | DUE <name>: ... routines.py --due, one line per due routine
|
||||
threads: N open ... unticked `- [ ]` under "Open threads" in workload/ notes; only when any
|
||||
profile: workload/profiles/<slug>.md the session identity's own profile, printed; only when it exists
|
||||
lessons: N new in wiki/lessons.md KB lessons dated after your previous workload note; only when any
|
||||
workload: <file> (last block follows) latest workload/ note by filename date
|
||||
|
||||
Exit 0 unless the repo root is not a KB. Python 3.8+, standard library only.
|
||||
|
|
@ -29,6 +31,7 @@ import os
|
|||
import re
|
||||
import subprocess
|
||||
import sys
|
||||
import unicodedata
|
||||
from datetime import date, datetime
|
||||
from pathlib import Path
|
||||
|
||||
|
|
@ -46,6 +49,11 @@ THREAD_RE = re.compile(r"^\s*[-*]\s+\[ \]\s+(\S.*?)\s*$")
|
|||
THREADS_SHOWN = 5
|
||||
THREAD_STALE_DAYS = 30
|
||||
SET_TITLE = ".agents/skills/ckb-add-conversation/scripts/save_conversation.py --set-title"
|
||||
PROFILE_LINES = 40
|
||||
LESSON_RE = re.compile(r"^###\s+(\d{4}-\d{2}-\d{2})\s+[—-]\s+(.+?)\s*$", re.M)
|
||||
# Letters NFKD does not split into base + accent (Rule D: `Michał Kopeć` -> `michal-kopec`).
|
||||
SLUG_MAP = str.maketrans({"ł": "l", "Ł": "L", "ø": "o", "Ø": "O", "đ": "d", "Đ": "D",
|
||||
"ß": "ss", "æ": "ae", "Æ": "AE", "œ": "oe", "Œ": "OE"})
|
||||
|
||||
|
||||
def run(cmd, cwd):
|
||||
|
|
@ -73,6 +81,13 @@ def identity(root):
|
|||
return f"{user} (OS user; git identity unset — set git config --global user.name / user.email)"
|
||||
|
||||
|
||||
def author_slug(root):
|
||||
"""The Rule D slug of the session identity's name, or None."""
|
||||
name = run(["git", "config", "user.name"], root)[1] or os.environ.get("USER") or os.environ.get("USERNAME") or ""
|
||||
ascii_name = unicodedata.normalize("NFKD", name.translate(SLUG_MAP)).encode("ascii", "ignore").decode()
|
||||
return re.sub(r"[^a-z0-9]+", "-", ascii_name.lower()).strip("-") or None
|
||||
|
||||
|
||||
def yaml_flag(root, block, key, default):
|
||||
"""Minimal reader for `block:\\n key: value` in ckb.yaml; no YAML parser."""
|
||||
path = root / "ckb.yaml"
|
||||
|
|
@ -231,6 +246,46 @@ def threads_lines(root, today):
|
|||
return out
|
||||
|
||||
|
||||
def strip_frontmatter(text):
|
||||
if text.startswith("---\n"):
|
||||
end = text.find("\n---\n", 4)
|
||||
if end != -1:
|
||||
return text[end + 5:]
|
||||
return text
|
||||
|
||||
|
||||
def profile_lines(root, slug):
|
||||
"""The session identity's profile, printed so it is in context; nothing when absent."""
|
||||
path = root / "workload" / "profiles" / f"{slug}.md" if slug else None
|
||||
if not path or not path.is_file():
|
||||
return []
|
||||
body = [l for l in strip_frontmatter(path.read_text(encoding="utf-8", errors="replace")).strip().splitlines()]
|
||||
if len(body) > PROFILE_LINES:
|
||||
body = body[:PROFILE_LINES] + [f"… (rest in {path.relative_to(root).as_posix()})"]
|
||||
return [f"profile: {path.relative_to(root).as_posix()} — yours; follow it where AGENTS.md and "
|
||||
"project rules leave room"] + [" " + l if l else "" for l in body]
|
||||
|
||||
|
||||
def lessons_lines(root, slug, today):
|
||||
"""KB lessons dated after this person's previous workload note (all of them
|
||||
on a first session), so a lesson someone else recorded is not missed."""
|
||||
path = root / "wiki" / "lessons.md"
|
||||
if not path.is_file():
|
||||
return []
|
||||
lessons = LESSON_RE.findall(path.read_text(encoding="utf-8", errors="replace"))
|
||||
prev = None
|
||||
if slug and (root / "workload").is_dir():
|
||||
dates = [f.name[:10] for f in (root / "workload").glob(f"*_{slug}_summary.md") if f.name[:10] < today.isoformat()]
|
||||
prev = max(dates) if dates else None
|
||||
new = [(d, t) for d, t in lessons if prev is None or d > prev]
|
||||
if not new:
|
||||
return []
|
||||
since = f"since your note of {prev}" if prev else "— first session here"
|
||||
out = [f"lessons: {len(new)} in wiki/lessons.md {since} -> read the ones that bear on this session"]
|
||||
out += [f" - {d} — {t}" for d, t in new[-THREADS_SHOWN:]]
|
||||
return out
|
||||
|
||||
|
||||
def latest_workload(root):
|
||||
"""Newest workload note by the date prefix of its filename, any author;
|
||||
ties broken by modification time. Returns (path, last block) or (None, '')."""
|
||||
|
|
@ -245,6 +300,8 @@ def latest_workload(root):
|
|||
text = latest.read_text(encoding="utf-8", errors="replace")
|
||||
blocks = re.split(r"(?m)^(?=## )", text)
|
||||
block = blocks[-1].rstrip() if len(blocks) > 1 else text.rstrip()
|
||||
# Open threads already print on the `threads:` line; don't show them twice.
|
||||
block = re.sub(r"(?ms)^#{2,4}\s+Open threads\s*$.*?(?=^#|\Z)", "", block).rstrip()
|
||||
lines = block.splitlines()
|
||||
if len(lines) > WORKLOAD_TAIL_LINES:
|
||||
lines = lines[:WORKLOAD_TAIL_LINES] + ["…"]
|
||||
|
|
@ -277,6 +334,9 @@ def brief(root, a, hook=None):
|
|||
out.append(extra)
|
||||
out.extend(routines_lines(root, a.today))
|
||||
out.extend(threads_lines(root, today))
|
||||
slug = author_slug(root)
|
||||
out.extend(profile_lines(root, slug))
|
||||
out.extend(lessons_lines(root, slug, today))
|
||||
path, block = latest_workload(root)
|
||||
if path:
|
||||
out.append(f"workload: {path.relative_to(root).as_posix()} — last block:")
|
||||
|
|
|
|||
107
.agents/skills/ckb-profile/SKILL.md
Normal file
107
.agents/skills/ckb-profile/SKILL.md
Normal file
|
|
@ -0,0 +1,107 @@
|
|||
---
|
||||
name: ckb-profile
|
||||
description: Keep a person's profile (role, how to work with them, personal lessons) in workload/profiles/ and record lessons on an explicit request — personal ones in the profile, KB-wide ones in wiki/lessons.md. Use for "set up my profile", "update my profile", "what do you know about me", "remember this", "lesson: …", "from now on always …", "list the lessons", "forget that lesson".
|
||||
---
|
||||
|
||||
# Profile skill
|
||||
|
||||
## Purpose
|
||||
|
||||
Two things a session should not have to relearn: who it is working with, and
|
||||
what a correction taught it. Both are written only when someone asks, never
|
||||
from a guess about tone or preference.
|
||||
|
||||
## Scopes, and which wins
|
||||
|
||||
1. **`AGENTS.md`** — the KB's rules. Always win.
|
||||
2. **A project scope's `## Rules`** — the team's agreements for that project,
|
||||
in `wiki/projects/<name>.md`. Win while working inside that scope.
|
||||
3. **A person's profile** — how to work with that person. Applies where
|
||||
neither of the above says otherwise.
|
||||
|
||||
A profile can never relax a rule from 1 or 2. When it conflicts with one,
|
||||
follow the rule and say so once.
|
||||
|
||||
## Profiles
|
||||
|
||||
One file per person: `workload/profiles/<author-slug>.md`, with the same slug
|
||||
as Rule D (`Michał Kopeć` → `michal-kopec`). It sits outside `wiki/`, so
|
||||
retrieval never reads it and it needs no `wiki/log.md` entry. The
|
||||
session-start brief prints the profile of the session identity, and only
|
||||
that one.
|
||||
|
||||
```markdown
|
||||
---
|
||||
type: profile
|
||||
author: Name
|
||||
author_email: name@example.com
|
||||
last_updated: YYYY-MM-DD
|
||||
---
|
||||
|
||||
# Name
|
||||
|
||||
## Role
|
||||
<!-- What they do, and what they use this KB for. -->
|
||||
|
||||
## How to work with me
|
||||
<!-- Short bullets: language, level of detail, what to ask before doing. -->
|
||||
|
||||
## Lessons
|
||||
<!-- Personal lessons, newest last, in the lesson format below. -->
|
||||
```
|
||||
|
||||
**Set up** ("set up my profile"): ask at most three questions in one message
|
||||
— role, how they want to be worked with, anything to always or never do —
|
||||
and write their answers in their words. Never fill a section by guessing.
|
||||
**Update**: change only what they named, and set `last_updated`. **"What do
|
||||
you know about me"**: show the profile, then say where it lives.
|
||||
|
||||
**Privacy.** A profile is committed and shared with everyone who clones the
|
||||
KB. Say so when creating one. Keep it to working preferences: no health,
|
||||
family, contact details beyond the git identity, or anything the person
|
||||
would not post in a team channel. Text in `<private>…</private>` is never
|
||||
written into a profile.
|
||||
|
||||
## Lessons
|
||||
|
||||
Record a lesson only on an explicit trigger: "remember this", "lesson: …",
|
||||
"from now on always/never …". A correction on its own is not a trigger; at
|
||||
most, offer once: "Want me to keep that as a lesson?"
|
||||
|
||||
```markdown
|
||||
### YYYY-MM-DD — <the rule, one line>
|
||||
- **Why:** <what went wrong or what the person said>
|
||||
- **Applies when:** <the situations it covers>
|
||||
- **Scope:** person | KB
|
||||
- **Recorded by:** Name
|
||||
```
|
||||
|
||||
Ask which scope when it is not obvious:
|
||||
|
||||
- **Person** — how this person likes to work. Append to `## Lessons` in
|
||||
their profile.
|
||||
- **KB** — true for anyone working in this KB (a naming rule, a source not
|
||||
to trust, a step that keeps getting missed). Append to `wiki/lessons.md`.
|
||||
Create the page if it is missing (`type: lessons`, a `tldr`, a routing row
|
||||
in `wiki/index.md`). Set `review: needs_update`, or `draft` on a new page,
|
||||
so a second person checks the lesson before everyone relies on it. Log it
|
||||
under Rule B.
|
||||
|
||||
A lesson that should bind everyone, always, belongs in `AGENTS.md` instead.
|
||||
Suggest that once; do not edit `AGENTS.md` from here.
|
||||
|
||||
The session-start brief lists KB lessons dated after the person's previous
|
||||
workload note. Read the ones that bear on the task.
|
||||
|
||||
**Forgetting**: a lesson is never deleted silently. Strike it through
|
||||
(`~~rule~~ — dropped YYYY-MM-DD: why`) so the record survives. A KB lesson
|
||||
change is logged under Rule B.
|
||||
|
||||
## Edge cases
|
||||
|
||||
- **No git identity** — use the OS-user slug the brief prints, and suggest
|
||||
setting `git config user.name` so the profile follows the person.
|
||||
- **Two people share one git identity** — one profile per identity. Say so
|
||||
and suggest separate identities.
|
||||
- **A profile asks for something a skill forbids** (skip the ingest
|
||||
check-in, push without asking) — follow the skill and say why once.
|
||||
|
|
@ -57,8 +57,9 @@ just said "reset the wiki" — the narrowest reading that satisfies the request.
|
|||
|
||||
| Tier | Contents | Default |
|
||||
|---|---|---|
|
||||
| **1 — Wiki knowledge** | Every page under `wiki/entities/`, `wiki/projects/`, `wiki/decisions/` (the `NNNN-*.md` records), `wiki/graph/edges.json` entries, and all log/overview/query-gap/error-book *entries* | **Yes** |
|
||||
| **1 — Wiki knowledge** | Every page under `wiki/entities/`, `wiki/projects/`, `wiki/decisions/` (the `NNNN-*.md` records), `wiki/graph/edges.json` entries, `wiki/lessons.md`, the rows of `wiki/tags.md`, and all log/overview/query-gap/error-book *entries* | **Yes** |
|
||||
| **2 — Workload history** | Every `workload/*_summary.md` and `workload/ingest-reports/*` | Ask |
|
||||
| **2b — Profiles** | `workload/profiles/*` — people's own preferences and personal lessons | Ask — **default no**; they describe people, not the KB's subject |
|
||||
| **3 — Source material** | `raw/inbox/*`, `raw/archive/*`, `raw/retractions/*`, `raw/saved-conversations/*` | Ask — this is the user's original material and may exist nowhere else |
|
||||
| **4 — Generated artifacts** | `outputs/*` | Ask — cheap to regenerate, usually safe |
|
||||
| **5 — External sources** | `libs/*`, `linked/*` | Ask — **default no.** `linked/` holds symlinks to *other people's* KBs, and deleting a symlink target by accident is a real risk |
|
||||
|
|
@ -131,6 +132,7 @@ Step 8 defines it** — that skill is the single source of truth for what a clea
|
|||
- `wiki/decisions/index.md` — header, placeholder, and the status-vocabulary
|
||||
table **verbatim** (`ckb-decide` and `ckb-lint` both validate against it).
|
||||
- `wiki/graph/edges.json` — `{"version": 1, "last_updated": "<today>", "edges": []}`.
|
||||
- `wiki/tags.md` — frontmatter, explanation and an empty tag table.
|
||||
- `.gitadd` placeholder files in any directory that would otherwise be empty, so
|
||||
the structure survives in git.
|
||||
|
||||
|
|
|
|||
|
|
@ -32,7 +32,7 @@ Same cascade order as CLAUDE.md/AGENTS.md, first match wins:
|
|||
2. `wiki/projects/index.md` — if a project scope matches the question,
|
||||
use that project's listed pages, entity pages, raw/archive sources,
|
||||
connector-backed libs, outputs, and graph areas as the first search
|
||||
boundary. A project scope narrows the first pass only; it never hides
|
||||
boundary, and follow its `## Rules` in how you answer. A project scope narrows the first pass only; it never hides
|
||||
the rest of the cascade.
|
||||
3. `wiki/entities/index.md` — match against entity titles/`tldr`.
|
||||
4. `wiki/decisions/index.md` — for any "why is it like this", "who decided",
|
||||
|
|
@ -66,14 +66,17 @@ a confidence×quality×freshness "trust" list — then fuses them with reciproca
|
|||
rank fusion (`weight / (k + rank)`, `k = 10`, exact-match weighted 2.0 when the
|
||||
question carries literal tokens, in-degree 0.5, trust 0.3). A page ranked third
|
||||
by three signals beats one ranked first by a single signal; consensus is the
|
||||
point. `--json` gives the same result as data.
|
||||
point. `--json` gives the same result as data. `--tag <tag>` (repeatable)
|
||||
keeps only pages carrying those tags, for a question that names a tagged
|
||||
area.
|
||||
|
||||
A candidate under `outputs/answers/` is an answer kept earlier, not a
|
||||
source: use it to find pages fast, then follow its `## Sources` like any
|
||||
other lead. Never ground an answer on a kept answer alone.
|
||||
|
||||
Read the whole output, not the first line. Each candidate shows which lists it
|
||||
came from and at what rank, its `tldr`, `STALE`/`INBOX`/`SUPERSEDED` flags, and
|
||||
came from and at what rank, its `tldr`, `STALE`/`INBOX`/`SUPERSEDED`/`DRAFT`/
|
||||
`NEEDS_UPDATE` flags, and
|
||||
any `raw/archive/` or `outputs/` file it cites that the script folded in as
|
||||
corroboration rather than counting as a second source.
|
||||
|
||||
|
|
@ -216,9 +219,11 @@ mid-answer unless the user asks for that separately.
|
|||
State caveats in the answer itself, not only in the metadata you read to
|
||||
build it. When a page grounding the answer is past its
|
||||
`freshness_window_days`, carries a low `confidence` or `quality`, rests on
|
||||
un-ingested `raw/inbox/` material, or was checked against a cached
|
||||
connector index rather than a live re-fetch, say so in a short clause next
|
||||
to the claim it qualifies. Surface a conflict between two live pages the
|
||||
un-ingested `raw/inbox/` material, was checked against a cached
|
||||
connector index rather than a live re-fetch, is `review: draft` (no person
|
||||
has checked it) or `needs_update`, or carries an open `> CONTRADICTION:`
|
||||
marker on the claim, say so in a short clause next to the claim it
|
||||
qualifies. Surface a conflict between two live pages the
|
||||
same way, even when neither is marked `superseded_by` yet. The metadata
|
||||
already exists and the script's flags already put it in front of you; the failure mode
|
||||
is answering confidently *from* a stale or contested page without passing
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
local signals and fuse them with reciprocal rank fusion.
|
||||
|
||||
python3 retrieve_candidates.py "question text" [--root DIR] [--k 10]
|
||||
[--top 12] [--scope SLUG] [--json]
|
||||
[--top 12] [--scope SLUG] [--tag TAG ...] [--json]
|
||||
|
||||
Signals, each its own ranked list (weight in brackets):
|
||||
exact rg/grep hits on literal tokens, across wiki/, raw/archive/, raw/inbox/,
|
||||
|
|
@ -15,6 +15,8 @@ Signals, each its own ranked list (weight in brackets):
|
|||
indegree how many edges point at a shortlisted page [0.5]
|
||||
trust confidence x quality x freshness, over the shortlist [0.3]
|
||||
|
||||
--tag keeps only wiki pages carrying every named tag (schema 1.6 `tags:`).
|
||||
|
||||
Fused score = sum(weight / (k + rank)) over the lists a candidate appears in.
|
||||
`k` defaults to 10: a local wiki yields a dozen candidates, not hundreds, and
|
||||
k=60 flattens them into near-identical scores.
|
||||
|
|
@ -263,6 +265,7 @@ def main():
|
|||
ap.add_argument("--top", type=int, default=12)
|
||||
ap.add_argument("--scope", help="force a wiki/projects/<slug> scope instead of matching one")
|
||||
ap.add_argument("--today", help="YYYY-MM-DD, for reproducible freshness")
|
||||
ap.add_argument("--tag", action="append", default=[], help="keep only pages with this tag (repeatable)")
|
||||
ap.add_argument("--json", action="store_true")
|
||||
a = ap.parse_args()
|
||||
|
||||
|
|
@ -305,10 +308,14 @@ def main():
|
|||
absorbed[o].append(item)
|
||||
continue
|
||||
results.append((item, sc))
|
||||
if a.tag:
|
||||
want = {t.strip().lower() for t in a.tag}
|
||||
tagged = lambda pg: {t.strip().lower() for t in pg["fm"].get("tags", "").strip("[]").split(",") if t.strip()}
|
||||
results = [(i, sc) for i, sc in results if i in pages and want <= tagged(pages[i])]
|
||||
results = results[:a.top]
|
||||
|
||||
out = {
|
||||
"query": a.query, "k": a.k, "literal_tokens": lits, "scope_page": scope_page,
|
||||
"query": a.query, "k": a.k, "literal_tokens": lits, "scope_page": scope_page, "tags": a.tag,
|
||||
"inbox_hits": sorted(inbox_hits), "empty_graph": not edges,
|
||||
"candidates": [],
|
||||
}
|
||||
|
|
@ -320,7 +327,7 @@ def main():
|
|||
"title": pg["title"] if pg else None, "type": fm.get("type"), "tldr": fm.get("tldr"),
|
||||
"last_updated": fm.get("last_updated"), "stale": (is_fresh(fm, today) is False) if pg else None,
|
||||
"confidence": fm.get("confidence"), "quality": fm.get("quality"),
|
||||
"superseded_by": fm.get("superseded_by"),
|
||||
"superseded_by": fm.get("superseded_by"), "review": fm.get("review"),
|
||||
"sources": pg["sources"] if pg else [], "corroborated_by": absorbed.get(item, []),
|
||||
"from_inbox": item.startswith("raw/inbox/"),
|
||||
})
|
||||
|
|
@ -334,13 +341,16 @@ def main():
|
|||
print(f"literal tokens (exact list weighted 2.0): {', '.join(lits)}")
|
||||
if scope_page:
|
||||
print(f"scope: {scope_page}")
|
||||
if a.tag:
|
||||
print(f"tags: only pages tagged {', '.join(a.tag)}")
|
||||
if out["empty_graph"]:
|
||||
print("graph: empty — graph/indegree lists skipped")
|
||||
if inbox_hits:
|
||||
print(f"raw/inbox/ hits ({len(inbox_hits)}): un-ingested material — an ingest is overdue")
|
||||
print()
|
||||
for i, c in enumerate(out["candidates"], 1):
|
||||
flags = [f for f, on in [("STALE", c["stale"]), ("INBOX", c["from_inbox"]), ("SUPERSEDED", c["superseded_by"])] if on]
|
||||
flags = [f for f, on in [("STALE", c["stale"]), ("INBOX", c["from_inbox"]), ("SUPERSEDED", c["superseded_by"]),
|
||||
("DRAFT", c["review"] == "draft"), ("NEEDS_UPDATE", c["review"] == "needs_update")] if on]
|
||||
rk = " ".join(f"{n}:{r}" for n, r in sorted(c["ranks"].items()))
|
||||
print(f"{i:2}. {c['score']:.4f} {c['path']} [{rk}]" + (f" {' '.join(flags)}" if flags else ""))
|
||||
if c["tldr"]:
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
25
AGENTS.md
25
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_<author>_summary.md # one file per person per day
|
||||
└── ingest-reports/ # One change report per ckb-ingest run
|
||||
├── ingest-reports/ # One change report per ckb-ingest run
|
||||
└── profiles/ # One profile per person (ckb-profile); outside retrieval
|
||||
```
|
||||
|
||||
### Optional Modules
|
||||
|
|
@ -125,9 +128,16 @@ freshness_window_days: 90
|
|||
retention: high|medium|low
|
||||
source_fingerprint: sha256:3f9a2c1e # digest of the source this page was built from
|
||||
source_checked: YYYY-MM-DD # when that digest was last verified
|
||||
review: draft|reviewed|needs_update # absent = not tracked; ckb-lint marks reviews
|
||||
reviewed_by: Name
|
||||
reviewed_on: YYYY-MM-DD
|
||||
tags: tag-one, tag-two # only tags listed in wiki/tags.md
|
||||
---
|
||||
```
|
||||
|
||||
`ckb-ingest` writes `review: draft` on a page it creates and
|
||||
`needs_update` when it changes what a `reviewed` page claims.
|
||||
|
||||
### Page Body Sections
|
||||
Three body sections are reserved across the whole KB. All are optional, but
|
||||
where present they mean exactly this and nothing else:
|
||||
|
|
@ -157,9 +167,17 @@ where present they mean exactly this and nothing else:
|
|||
rewrite, reflow, summarize, or drop this section; regeneration
|
||||
preserves it byte-for-byte. It is the only place a person can annotate
|
||||
an agent-regenerated page and expect it to survive.
|
||||
- **`## Rules`** — on a `wiki/projects/` scope page only: the team's rules
|
||||
for that project. Human-authored and protected like `## Notes`; they apply
|
||||
while working in that scope and yield only to this file.
|
||||
- **`## Evidence`** / other sections are ordinary content with no special
|
||||
handling.
|
||||
|
||||
Two sources that disagree get a marker in the page, never a silent winner:
|
||||
`` > CONTRADICTION: <claim> (`<source>`) vs <claim> (`<source>`) — found YYYY-MM-DD ``.
|
||||
It stays until a person resolves it (supersession, a decision, or an edit),
|
||||
and lint lists every open one.
|
||||
|
||||
Pages with `type: decision` live in `wiki/decisions/` as `NNNN-slug.md` and
|
||||
add `status` (`proposed`/`accepted`/`rejected`/`superseded`/`reversed`),
|
||||
`decided_on`, `decided_by`, and optionally `affects` and `review_on`. They are
|
||||
|
|
@ -167,7 +185,7 @@ append-only: never rewrite a decision's substance to match a later change of
|
|||
mind — record a new decision that supersedes it, and set both
|
||||
`supersedes` and `superseded_by`. `ckb-decide` owns the format.
|
||||
|
||||
`wiki/index.md` alone also carries `kb_schema_version`, currently `"1.5"`
|
||||
`wiki/index.md` alone also carries `kb_schema_version`, currently `"1.6"`
|
||||
for the base contract. An installed module may raise it additively by
|
||||
declaring `requires_kb_schema` and contributing optional types and fields;
|
||||
`ckb-module` applies that bump at install time. Detailed schema migration
|
||||
|
|
@ -198,6 +216,7 @@ file.
|
|||
| Generate a project overview | `ckb-project-summary` |
|
||||
| Prepare a document from a template in `templates/`, list templates, or write a new one | `ckb-document` |
|
||||
| Teach, quiz, or onboard from the wiki | `ckb-teach-me`, `ckb-quiz`, `ckb-onboard-me` |
|
||||
| Set up a person's profile, or record a lesson ("remember this") | `ckb-profile` |
|
||||
|
||||
Disambiguation, only where the table alone is ambiguous:
|
||||
|
||||
|
|
@ -345,6 +364,8 @@ Act only on lines that ask for it, and stay quiet about anything clean:
|
|||
and `ckb-lint` own the details.
|
||||
- `threads:` → mention the count in one line; pick a thread up only when the
|
||||
user asks.
|
||||
- `profile:` → follow it where this file and project rules leave room.
|
||||
- `lessons:` → read the ones that bear on the request.
|
||||
- `routines: DUE` → finish the user's request first; then, in the same turn,
|
||||
perform each due routine's `do` as if asked, run `--mark <name>` once it
|
||||
completes, and report it in one line. A `confirm: true` routine is asked
|
||||
|
|
|
|||
22
README.md
22
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.
|
||||
|
||||
|
|
|
|||
23
README.pl.md
23
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ść.
|
||||
|
|
|
|||
2
VERSION
2
VERSION
|
|
@ -1 +1 @@
|
|||
1.22.1
|
||||
1.23.0
|
||||
|
|
|
|||
|
|
@ -28,14 +28,14 @@ so any page written since 2026-07-13 is still valid today.
|
|||
|
||||
## Contents
|
||||
|
||||
1. [Current page schema (1.5)](#current-page-schema-kb_schema_version-15)
|
||||
1. [Current page schema (1.6)](#current-page-schema-kb_schema_version-16)
|
||||
2. [KB schema version history](#kb-schema-version-history)
|
||||
3. [Template version history](#template-version-history)
|
||||
4. [Migrating between versions](#migrating-between-versions)
|
||||
|
||||
---
|
||||
|
||||
## Current page schema (`kb_schema_version: "1.5"`)
|
||||
## Current page schema (`kb_schema_version: "1.6"`)
|
||||
|
||||
### Frontmatter — every non-reserved page
|
||||
|
||||
|
|
@ -58,6 +58,10 @@ flat `key: value` pairs only, no nesting.
|
|||
| `retention` | no | `high` / `medium` / `low`. A `low` page is archived (never deleted) after 2× its freshness window. |
|
||||
| `source_fingerprint` | no | *(1.5)* Digest of the source this page was built from - `sha256:<8 hex>` for a local file, or `etag:<value>` / `mtime:<iso8601>` for a connector item. |
|
||||
| `source_checked` | no | *(1.5)* `YYYY-MM-DD` - when that digest was last verified. Distinct from `last_updated`: a re-check that finds nothing changed advances this and leaves `last_updated` alone. |
|
||||
| `review` | no | *(1.6)* `draft` / `reviewed` / `needs_update`. Absent means "not tracked". `ckb-ingest` writes `draft` on new pages and `needs_update` when it changes what a `reviewed` page claims; only a person's say-so sets `reviewed` (via `ckb-lint`). |
|
||||
| `reviewed_by` | no | *(1.6)* Who last reviewed the page. Kept when the page moves to `needs_update`, as the record of the last review. |
|
||||
| `reviewed_on` | no | *(1.6)* `YYYY-MM-DD` of that review. Lint flags a `reviewed` page whose `last_updated` is later. |
|
||||
| `tags` | no | *(1.6)* Flat comma list, e.g. `tags: retries, billing`. Every tag must be a row in `wiki/tags.md`. |
|
||||
|
||||
`wiki/index.md` alone carries `kb_schema_version`. It is a bundle-level
|
||||
declaration, not a per-page one - individual pages never carry it.
|
||||
|
|
@ -141,6 +145,25 @@ the only place an annotation survives. Decision pages deliberately have no
|
|||
editable annotation block invites exactly the retroactive revision the
|
||||
append-only rule exists to prevent.
|
||||
|
||||
#### `## Rules`
|
||||
|
||||
*(1.6.)* On a `wiki/projects/` scope page only: the team's rules for that
|
||||
project, which apply while working inside the scope. Human-authored and
|
||||
protected exactly like `## Notes`. They yield only to `AGENTS.md`; a person's
|
||||
profile yields to them.
|
||||
|
||||
#### The contradiction marker
|
||||
|
||||
*(1.6.)* Not a section but a body line, written where two sources disagree
|
||||
and nobody has decided which is right:
|
||||
|
||||
```markdown
|
||||
> CONTRADICTION: three retries (`raw/archive/2026-09-01/kickoff-notes.md`) vs five retries (`raw/archive/2026-11-02/runbook.md`) — found 2026-11-02
|
||||
```
|
||||
|
||||
It stays until a person resolves it (supersession, a decision, or an edit),
|
||||
and lint lists every open one (check 18).
|
||||
|
||||
### Edge vocabulary
|
||||
|
||||
Relationships live in `wiki/graph/edges.json` (and each connector index's own
|
||||
|
|
@ -185,6 +208,8 @@ improving it (in-degree is used as a ranking signal).
|
|||
| `wiki/query-gaps.md` | 1.2 | Questions the wiki could not answer, driving demand-driven ingest |
|
||||
| `wiki/projects/` | 1.2 | Optional local query scopes |
|
||||
| `wiki/decisions/` | 1.4 | Numbered, append-only decision records, with their own `log.md` |
|
||||
| `wiki/tags.md` | 1.6 | The KB's own closed tag vocabulary (`type: vocabulary`); lint checks `tags:` against it |
|
||||
| `wiki/lessons.md` | 1.6 | KB-wide lessons, created on first use by `ckb-profile` (`type: lessons`) |
|
||||
|
||||
Every subdirectory that groups pages carries its own `index.md`, so
|
||||
navigation stays lazy.
|
||||
|
|
@ -193,6 +218,27 @@ navigation stays lazy.
|
|||
|
||||
## KB schema version history
|
||||
|
||||
### 1.6 — 2026-11-02 · review, contradictions, tags, project rules
|
||||
|
||||
From the 2026-10-31 agent-knowledge research (features F7, F4, F21, F9, F8),
|
||||
decided in [D-0014](decisions/0014-schema-1-6-review-contradictions-tags-profiles.md).
|
||||
Additive: a 1.5 page is a valid 1.6 page.
|
||||
|
||||
- **Review fields** `review`/`reviewed_by`/`reviewed_on`. The plan's name was
|
||||
`status`, which decision pages already use with a different vocabulary.
|
||||
- **Contradiction marker** `> CONTRADICTION: …` instead of a silent winner.
|
||||
Claim-level `valid_from`/`valid_to` are deferred.
|
||||
- **`tags`** checked against the new scaffold file `wiki/tags.md`.
|
||||
- **`## Rules`**, a protected section on project scope pages.
|
||||
- **`wiki/lessons.md`**, created on first use.
|
||||
|
||||
Outside `wiki/` and so outside the schema, but shipped together: per-person
|
||||
profiles in `workload/profiles/` and the `ckb-profile` skill.
|
||||
|
||||
**Migration** (`ckb-upgrade` Step 7 b3): add `wiki/tags.md` and its index
|
||||
row, bump the version. `review` is backfilled only on request, and only to
|
||||
`draft`.
|
||||
|
||||
### 1.5 — 2026-09-21 · evidence, fingerprints, and a completed edge vocabulary
|
||||
|
||||
Adopted from an analysis of [trailhq/Graft](https://github.com/trailhq/Graft),
|
||||
|
|
@ -284,7 +330,8 @@ docs. Independent of the content schema above.
|
|||
|
||||
| Version | Date | What landed | Schema |
|
||||
|---|---|---|---|
|
||||
| **1.22.1** | 2026-11-02 | Hooks start from the project root. Claude Code runs a hook in the session's current directory, so the autosave Stop hook's relative `save_conversation.py` path resolved against whatever folder the shell had moved into: a session working inside a nested repo saved its transcript there, and in a folder without the script the save failed silently. `autosave_hook.py` and `start_hook.py` now write `cd "${CLAUDE_PROJECT_DIR:-.}" && …`; `--check` reports an entry installed before this fix as outdated (the session-start brief asks once), and `--install` replaces it without touching other hooks. Smoke test runs both installed hooks from a subfolder | 1.5 |
|
||||
| **1.23.0** | 2026-11-02 | Agent-knowledge release 2, **schema 1.6** (D-0014). **Review (F7):** optional `review: draft|reviewed|needs_update` with `reviewed_by`/`reviewed_on` (the plan's `status` clashed with decision pages); `ckb-ingest` writes `draft` on new pages and `needs_update` when it changes what a reviewed page claims; lint check 17 flags only inconsistencies and prints a review queue; `ckb-lint` marks reviews on the person's say-so. **Contradictions (F4):** a `> CONTRADICTION:` body marker instead of a silent winner, listed by lint check 18 until resolved by supersession, a decision or an edit; claim-level validity dates deferred. **Tags (F21):** `tags:` checked against the new scaffold `wiki/tags.md` (check 19); `retrieve_candidates.py --tag`; `DRAFT`/`NEEDS_UPDATE` retrieval flags. **Scopes and profiles (F9):** `AGENTS.md` > a project scope's protected `## Rules` > a person's profile in `workload/profiles/`, printed by the session-start brief for the session identity only. **Lessons (F8):** on an explicit trigger only; personal in the profile, KB-wide in `wiki/lessons.md` (reviewed before relied on); the brief lists lessons new since the person's previous note. New skill `ckb-profile`. **Carry-over:** `.secrets-allow` accepts `<glob> match:<hash>` entries that cover one string on every line of growing transcripts (bash/PowerShell fallbacks too); open threads no longer print twice. Starlight shows review and tags and a "Needs update" badge; OKF passes the new fields through. `ckb-upgrade` Step 7 b3 migrates 1.5 → 1.6; `ckb-init`/`ckb-reset` know `tags.md`. Always-loaded ~7,245 tokens | 1.6 |
|
||||
| 1.22.1 | 2026-11-02 | Hooks start from the project root. Claude Code runs a hook in the session's current directory, so the autosave Stop hook's relative `save_conversation.py` path resolved against whatever folder the shell had moved into: a session working inside a nested repo saved its transcript there, and in a folder without the script the save failed silently. `autosave_hook.py` and `start_hook.py` now write `cd "${CLAUDE_PROJECT_DIR:-.}" && …`; `--check` reports an entry installed before this fix as outdated (the session-start brief asks once), and `--install` replaces it without touching other hooks. Smoke test runs both installed hooks from a subfolder | 1.5 |
|
||||
| 1.22.0 | 2026-11-02 | Agent-knowledge release 1: seven features from the 2026-10-31 research, no schema change. **Session-start hook (F1):** `session_start.py --hook` prints the Rule E brief as `SessionStart` `additionalContext` on startup, resume, `/clear` and after every compaction; `start_hook.py --check/--install/--remove` manages it in the gitignored `.claude/settings.local.json`; opt-in via `session: start_hook:` in `ckb.yaml`, with a `start hook:` brief line when the two disagree; Rule E stays the fallback (D-0011). **Kept answers (F2):** `ckb-retrieve` Step 8 offers to keep a substantial answer in `outputs/answers/` (`type: answer`) with fingerprinted `## Sources` and `## Gaps`, updates rather than duplicates, and files back only through ingest; lint check 16 reports kept answers whose sources moved (D-0013). **Ingest check-in (F3):** before writing, `ckb-ingest` shows its reading of each source, the pages it will touch and what it contradicts, then waits; batch mode ("ingest in batch", or a `confirm: false` routine) skips it; the ingest report gains `## Check-in`. **Open threads (F5):** `### Open threads` checkboxes in workload notes (Rule D), collected by `session_start.py` into a `threads:` line with the five oldest and a 30-day stale mark; no shared status file (D-0012). **Capture-time dedup (F6):** new `ckb-ingest/scripts/dedup_inbox.py` reports `DUPLICATE`, `SAME TEXT`, `CITED`, `SAME URL` and `INBOX TWIN` against `raw/archive/` and cited fingerprints/URLs before ingest. **Secret and privacy guards (F19):** lint check 15 scans committed text for credential shapes and `wiki/` for `<private>` spans, masks matches, honours a line-hash `.secrets-allow`; `--quick` counts it, `--secrets` runs it alone and `ckb-sync-changes` runs it before staging; ingest drops and retrieval never quotes `<private>` spans; `save_conversation.py` redacts them (D-0013). **Context budget (F20):** `lint_report.py --budget` estimates `AGENTS.md` plus skill descriptions at characters ÷ 4; `--quick` flags it above `budget: always_loaded_tokens` (default 9000). Baseline: ~6,620 tokens at 1.21.0, ~6,810 at 1.22.0. Bash/PowerShell quick fallbacks gain a reduced secret check; smoke test covers every new script | 1.5 |
|
||||
| 1.21.0 | 2026-10-31 | `ABOUT.md`. New root file, written by the KB's owner, stating what the KB holds: purpose, audience, scope (in and out), owners and contacts, expected sources, sensitivity, language and terms, each shipped as a comment saying what to write; `type: about` with a `tldr`. `README.md`/`README.pl.md` link to it under the source-repo pointer, since the README itself is the template's and is overwritten on upgrade. Agents read it and never edit it unless asked; questions about the KB itself are answered from it before `wiki/overview.md`, which stays the agent's summary of what was ingested and now links to it. `ckb-ingest` Step 1 names material outside its scope or ruled out by its sensitivity section and ingests it only on the user's say-so. `ckb-init` copies the scaffold and asks one optional question for Purpose and `tldr`; `ckb-upgrade` creates it only when missing and never diffs it; `ckb-reset` never touches it. `mcp` module: `kb_overview` starts with it and the server's KB description comes from its `tldr` (the scaffold placeholder is ignored). Directory contract and manual updated. D-0010 | 1.5 |
|
||||
| 1.20.0 | 2026-10-30 | Ingest reports. `ckb-ingest` gains Step 8: every run that ingested something writes one file, `workload/ingest-reports/YYYY-MM-DD_HHMM_<author>_ingest.md` (`type: ingest-report`), listing raw files taken in and their archive path and fingerprint, decisions recorded, entities created/updated, other pages, graph edges, the blast radius (confirmed/extended/contradicted with owners, query gaps closed) and inbox files not ingested; every section kept with `- none` when empty. Written once, outside retrieval, no `wiki/log.md` entry, untouched by `ckb-retract`; a subfolder so `session_start.py` keeps reading only session notes. The old Step 8 (summary and sync reminder) becomes Step 9 and names the report. Directory contract, manual and `ckb-reset` tier 2 updated | 1.5 |
|
||||
|
|
|
|||
|
|
@ -29,14 +29,14 @@ strona napisana od 2026-07-13 jest dziś nadal poprawna.
|
|||
|
||||
## Spis treści
|
||||
|
||||
1. [Aktualny schemat strony (1.5)](#aktualny-schemat-strony-kb_schema_version-15)
|
||||
1. [Aktualny schemat strony (1.6)](#aktualny-schemat-strony-kb_schema_version-16)
|
||||
2. [Historia wersji schematu KB](#historia-wersji-schematu-kb)
|
||||
3. [Historia wersji szablonu](#historia-wersji-szablonu)
|
||||
4. [Migracja między wersjami](#migracja-między-wersjami)
|
||||
|
||||
---
|
||||
|
||||
## Aktualny schemat strony (`kb_schema_version: "1.5"`)
|
||||
## Aktualny schemat strony (`kb_schema_version: "1.6"`)
|
||||
|
||||
### Frontmatter — każda strona niezastrzeżona
|
||||
|
||||
|
|
@ -59,6 +59,10 @@ pary `klucz: wartość`, bez zagnieżdżeń.
|
|||
| `retention` | nie | `high` / `medium` / `low`. Strona `low` jest archiwizowana (nigdy usuwana) po 2× swoim oknie świeżości. |
|
||||
| `source_fingerprint` | nie | *(1.5)* Skrót źródła, z którego zbudowano stronę — `sha256:<8 hex>` dla pliku lokalnego albo `etag:<wartość>` / `mtime:<iso8601>` dla elementu z konektora. |
|
||||
| `source_checked` | nie | *(1.5)* `YYYY-MM-DD` — kiedy ten skrót był ostatnio zweryfikowany. To co innego niż `last_updated`: ponowne sprawdzenie, które nie wykryło zmiany, przesuwa to pole i zostawia `last_updated` w spokoju. |
|
||||
| `review` | nie | *(1.6)* `draft` / `reviewed` / `needs_update`. Brak pola oznacza „nieśledzone”. `ckb-ingest` zapisuje `draft` na nowych stronach i `needs_update`, gdy zmienia to, co twierdzi strona `reviewed`; `reviewed` ustawia tylko decyzja człowieka (przez `ckb-lint`). |
|
||||
| `reviewed_by` | nie | *(1.6)* Kto ostatnio przejrzał stronę. Zostaje, gdy strona przechodzi w `needs_update`, jako zapis ostatniego przeglądu. |
|
||||
| `reviewed_on` | nie | *(1.6)* `YYYY-MM-DD` tego przeglądu. Lint flaguje stronę `reviewed`, której `last_updated` jest późniejsze. |
|
||||
| `tags` | nie | *(1.6)* Płaska lista po przecinku, np. `tags: retries, billing`. Każdy tag musi być wierszem w `wiki/tags.md`. |
|
||||
|
||||
Wyłącznie `wiki/index.md` niesie `kb_schema_version`. To deklaracja na
|
||||
poziomie całego zbioru, nie pojedynczej strony — same strony nigdy jej nie
|
||||
|
|
@ -144,6 +148,25 @@ Strony decyzji celowo nie mają `## Notes`: nic ich nie regeneruje, a rekord
|
|||
tylko-do-dopisywania ze swobodnie edytowalnym blokiem adnotacji zaprasza
|
||||
dokładnie do tej wstecznej korekty, której zasada append-only ma zapobiegać.
|
||||
|
||||
#### `## Rules`
|
||||
|
||||
*(1.6.)* Tylko na stronie zakresu w `wiki/projects/`: zasady zespołu dla tego
|
||||
projektu, obowiązujące podczas pracy w tym zakresie. Pisane przez człowieka i
|
||||
chronione dokładnie jak `## Notes`. Ustępują tylko `AGENTS.md`; profil osoby
|
||||
ustępuje im.
|
||||
|
||||
#### Znacznik sprzeczności
|
||||
|
||||
*(1.6.)* Nie sekcja, lecz linia w treści, zapisywana tam, gdzie dwa źródła się
|
||||
nie zgadzają, a nikt nie zdecydował, które ma rację:
|
||||
|
||||
```markdown
|
||||
> CONTRADICTION: three retries (`raw/archive/2026-09-01/kickoff-notes.md`) vs five retries (`raw/archive/2026-11-02/runbook.md`) — found 2026-11-02
|
||||
```
|
||||
|
||||
Zostaje, dopóki człowiek jej nie rozstrzygnie (supersesja, decyzja albo
|
||||
edycja), a lint wypisuje każdą otwartą (kontrola 18).
|
||||
|
||||
### Słownik krawędzi
|
||||
|
||||
Relacje mieszkają w `wiki/graph/edges.json` (oraz we własnym
|
||||
|
|
@ -189,6 +212,8 @@ rankingowym).
|
|||
| `wiki/query-gaps.md` | 1.2 | Pytania, na które wiki nie umiało odpowiedzieć, napędzające ingest sterowany popytem |
|
||||
| `wiki/projects/` | 1.2 | Opcjonalne lokalne zakresy zapytań |
|
||||
| `wiki/decisions/` | 1.4 | Numerowane rekordy decyzji tylko-do-dopisywania, z własnym `log.md` |
|
||||
| `wiki/tags.md` | 1.6 | Własny zamknięty słownik tagów KB (`type: vocabulary`); lint sprawdza względem niego `tags:` |
|
||||
| `wiki/lessons.md` | 1.6 | Lekcje dla całej KB, tworzone przy pierwszym użyciu przez `ckb-profile` (`type: lessons`) |
|
||||
|
||||
Każdy podkatalog grupujący strony niesie własny `index.md`, dzięki czemu
|
||||
nawigacja pozostaje leniwa.
|
||||
|
|
@ -197,6 +222,27 @@ nawigacja pozostaje leniwa.
|
|||
|
||||
## Historia wersji schematu KB
|
||||
|
||||
### 1.6 — 2026-11-02 · przegląd, sprzeczności, tagi, zasady projektu
|
||||
|
||||
Z badania wiedzy dla agentów z 2026-10-31 (funkcje F7, F4, F21, F9, F8),
|
||||
decyzja [D-0014](decisions/0014-schema-1-6-review-contradictions-tags-profiles.md).
|
||||
Addytywnie: strona 1.5 jest poprawną stroną 1.6.
|
||||
|
||||
- **Pola przeglądu** `review`/`reviewed_by`/`reviewed_on`. Plan nazywał je
|
||||
`status`, ale strony decyzji używają już `status` z innym słownikiem.
|
||||
- **Znacznik sprzeczności** `> CONTRADICTION: …` zamiast cichego zwycięzcy.
|
||||
Daty ważności na poziomie twierdzeń (`valid_from`/`valid_to`) odłożone.
|
||||
- **`tags`** sprawdzane względem nowego pliku szkieletu `wiki/tags.md`.
|
||||
- **`## Rules`**, chroniona sekcja na stronach zakresu projektu.
|
||||
- **`wiki/lessons.md`**, tworzony przy pierwszym użyciu.
|
||||
|
||||
Poza `wiki/`, a więc poza schematem, ale w tym samym wydaniu: profile osób w
|
||||
`workload/profiles/` i skill `ckb-profile`.
|
||||
|
||||
**Migracja** (`ckb-upgrade`, krok 7 b3): dodać `wiki/tags.md` i jego wiersz
|
||||
w indeksie, podnieść wersję. `review` uzupełniane tylko na prośbę i tylko do
|
||||
`draft`.
|
||||
|
||||
### 1.5 — 2026-09-21 · dowody, skróty źródeł i dokończony słownik krawędzi
|
||||
|
||||
Zaadaptowane z analizy [trailhq/Graft](https://github.com/trailhq/Graft),
|
||||
|
|
@ -291,7 +337,8 @@ Niezależna od schematu treści powyżej.
|
|||
|
||||
| Wersja | Data | Co weszło | Schemat |
|
||||
|---|---|---|---|
|
||||
| **1.22.1** | 2026-11-02 | Hooki startują z katalogu głównego projektu. Claude Code uruchamia hook w bieżącym katalogu sesji, więc względna ścieżka `save_conversation.py` w hooku autozapisu `Stop` rozwiązywała się względem folderu, do którego przeszła powłoka: sesja pracująca w zagnieżdżonym repozytorium zapisywała tam swój transkrypt, a w folderze bez skryptu zapis cicho się nie udawał. `autosave_hook.py` i `start_hook.py` zapisują teraz `cd "${CLAUDE_PROJECT_DIR:-.}" && …`; `--check` zgłasza wpis zainstalowany przed tą poprawką jako nieaktualny (podsumowanie startu sesji pyta raz), a `--install` podmienia go, nie ruszając innych hooków. Test dymny uruchamia oba zainstalowane hooki z podfolderu | 1.5 |
|
||||
| **1.23.0** | 2026-11-02 | Wiedza dla agentów, wydanie 2, **schemat 1.6** (D-0014). **Przegląd (F7):** opcjonalne `review: draft|reviewed|needs_update` z `reviewed_by`/`reviewed_on` (planowane `status` kolidowało ze stronami decyzji); `ckb-ingest` zapisuje `draft` na nowych stronach i `needs_update`, gdy zmienia to, co twierdzi strona przejrzana; kontrola 17 lintu flaguje tylko niespójności i wypisuje kolejkę przeglądu; `ckb-lint` oznacza przegląd na słowo człowieka. **Sprzeczności (F4):** znacznik `> CONTRADICTION:` w treści zamiast cichego zwycięzcy, wypisywany przez kontrolę 18 do rozstrzygnięcia supersesją, decyzją lub edycją; daty ważności twierdzeń odłożone. **Tagi (F21):** `tags:` sprawdzane względem nowego pliku szkieletu `wiki/tags.md` (kontrola 19); `retrieve_candidates.py --tag`; flagi wyszukiwania `DRAFT`/`NEEDS_UPDATE`. **Zakresy i profile (F9):** `AGENTS.md` > chroniona sekcja `## Rules` zakresu projektu > profil osoby w `workload/profiles/`, wypisywany przez podsumowanie startu sesji tylko dla tożsamości sesji. **Lekcje (F8):** tylko na wyraźne polecenie; osobiste w profilu, dla całej KB w `wiki/lessons.md` (przeglądane, zanim się na nich polega); podsumowanie wymienia lekcje nowe od poprzedniej notatki osoby. Nowy skill `ckb-profile`. **Pozostałości:** `.secrets-allow` przyjmuje wpisy `<glob> match:<skrót>`, które obejmują jeden ciąg w każdej linii rosnących transkryptów (także zapasowe bash/PowerShell); otwarte wątki nie drukują się już dwa razy. Starlight pokazuje przegląd i tagi oraz odznakę „Needs update”; OKF przepuszcza nowe pola. `ckb-upgrade` krok 7 b3 migruje 1.5 → 1.6; `ckb-init`/`ckb-reset` znają `tags.md`. Warstwa ładowana zawsze ~7 245 tokenów | 1.6 |
|
||||
| 1.22.1 | 2026-11-02 | Hooki startują z katalogu głównego projektu. Claude Code uruchamia hook w bieżącym katalogu sesji, więc względna ścieżka `save_conversation.py` w hooku autozapisu `Stop` rozwiązywała się względem folderu, do którego przeszła powłoka: sesja pracująca w zagnieżdżonym repozytorium zapisywała tam swój transkrypt, a w folderze bez skryptu zapis cicho się nie udawał. `autosave_hook.py` i `start_hook.py` zapisują teraz `cd "${CLAUDE_PROJECT_DIR:-.}" && …`; `--check` zgłasza wpis zainstalowany przed tą poprawką jako nieaktualny (podsumowanie startu sesji pyta raz), a `--install` podmienia go, nie ruszając innych hooków. Test dymny uruchamia oba zainstalowane hooki z podfolderu | 1.5 |
|
||||
| 1.22.0 | 2026-11-02 | Wiedza dla agentów, wydanie 1: siedem funkcji z badania z 2026-10-31, bez zmiany schematu. **Hook startu sesji (F1):** `session_start.py --hook` wypisuje podsumowanie z reguły E jako `additionalContext` hooka `SessionStart` przy starcie, wznowieniu, `/clear` i po każdym kompaktowaniu; `start_hook.py --check/--install/--remove` zarządza nim w ignorowanym przez gita `.claude/settings.local.json`; włączany przez `session: start_hook:` w `ckb.yaml`, z linią `start hook:` w podsumowaniu, gdy oba się nie zgadzają; reguła E zostaje jako zapas (D-0011). **Zachowane odpowiedzi (F2):** krok 8 `ckb-retrieve` proponuje zachowanie istotnej odpowiedzi w `outputs/answers/` (`type: answer`) ze skrótami w `## Sources` i sekcją `## Gaps`, aktualizuje zamiast dublować i wprowadza do wiki tylko przez ingest; kontrola 16 lintu zgłasza zachowane odpowiedzi, których źródła się zmieniły (D-0013). **Meldunek przed ingestem (F3):** zanim cokolwiek zapisze, `ckb-ingest` pokazuje, jak rozumie każde źródło, które strony zmieni i z czym jest sprzeczne, po czym czeka; tryb wsadowy („ingest in batch” albo rutyna z `confirm: false`) to pomija; raport ingestu dostaje sekcję `## Check-in`. **Otwarte wątki (F5):** pola `### Open threads` w notatkach workload (reguła D), zbierane przez `session_start.py` w linię `threads:` z pięcioma najstarszymi i znacznikiem po 30 dniach; bez wspólnego pliku statusu (D-0012). **Deduplikacja przy wejściu (F6):** nowy `ckb-ingest/scripts/dedup_inbox.py` zgłasza `DUPLICATE`, `SAME TEXT`, `CITED`, `SAME URL` i `INBOX TWIN` względem `raw/archive/` oraz cytowanych skrótów i adresów URL przed ingestem. **Ochrona sekretów i prywatności (F19):** kontrola 15 lintu szuka postaci danych uwierzytelniających w commitowanym tekście i fragmentów `<private>` w `wiki/`, maskuje dopasowania, honoruje `.secrets-allow` oparte na skrócie linii; `--quick` ją liczy, `--secrets` uruchamia ją osobno, a `ckb-sync-changes` przed stagingiem; ingest odrzuca, a retrieval nigdy nie cytuje fragmentów `<private>`; `save_conversation.py` je redaguje (D-0013). **Budżet kontekstu (F20):** `lint_report.py --budget` szacuje `AGENTS.md` plus opisy skilli jako znaki ÷ 4; `--quick` flaguje przekroczenie `budget: always_loaded_tokens` (domyślnie 9000). Punkt odniesienia: ~6 620 tokenów w 1.21.0, ~6 810 w 1.22.0. Zapasowe kontrole bash/PowerShell dostają okrojoną kontrolę sekretów; test dymny obejmuje każdy nowy skrypt | 1.5 |
|
||||
| 1.21.0 | 2026-10-31 | `ABOUT.md`. Nowy plik w katalogu głównym, pisany przez właściciela KB, mówiący, co ta KB zawiera: cel, odbiorcy, zakres (co wchodzi, a co nie), właściciele i kontakty, oczekiwane źródła, poufność, język i terminy; każda sekcja ma komentarz, co w niej napisać; `type: about` z `tldr`. `README.md`/`README.pl.md` linkują do niego pod wskazaniem repozytorium źródłowego, bo samo README należy do szablonu i jest nadpisywane przy aktualizacji. Agenci go czytają i nie edytują bez prośby; pytania o samą KB dostają odpowiedź najpierw z niego, potem z `wiki/overview.md`, które pozostaje podsumowaniem agenta tego, co przetworzono, i teraz do niego linkuje. `ckb-ingest` w Kroku 1 wskazuje materiał spoza zakresu lub wykluczony przez sekcję poufności i przetwarza go tylko na wyraźną prośbę. `ckb-init` kopiuje szkielet i zadaje jedno opcjonalne pytanie o cel i `tldr`; `ckb-upgrade` tworzy go tylko, gdy go brak, i nigdy go nie porównuje; `ckb-reset` nigdy go nie rusza. Moduł `mcp`: `kb_overview` zaczyna się od niego, a opis KB serwera pochodzi z jego `tldr` (zastępczy tekst szkieletu jest pomijany). Zaktualizowano kontrakt katalogów i podręcznik. D-0010 | 1.5 |
|
||||
| 1.20.0 | 2026-10-30 | Raporty z ingestu. `ckb-ingest` dostaje Krok 8: każde uruchomienie, które coś przetworzyło, zapisuje jeden plik `workload/ingest-reports/YYYY-MM-DD_HHMM_<autor>_ingest.md` (`type: ingest-report`) z listą przyjętych plików z `raw/` wraz ze ścieżką archiwum i odciskiem, zapisanych decyzji, utworzonych/zaktualizowanych encji, innych stron, krawędzi grafu, zasięgu zmian (potwierdzone/rozszerzone/sprzeczne z właścicielami, zamknięte luki w zapytaniach) oraz plików ze skrzynki, których nie przetworzono; każda sekcja zostaje, z `- none`, gdy jest pusta. Zapisywany raz, poza wyszukiwaniem, bez wpisu w `wiki/log.md`, nieruszany przez `ckb-retract`; podfolder, aby `session_start.py` nadal czytał tylko notatki sesji. Dotychczasowy Krok 8 (podsumowanie i przypomnienie o synchronizacji) staje się Krokiem 9 i wskazuje raport. Zaktualizowane: struktura katalogów, podręcznik i poziom 2 w `ckb-reset` | 1.5 |
|
||||
|
|
|
|||
|
|
@ -224,6 +224,18 @@ Three things happen before anything is written:
|
|||
`</private>` in a source is never written into the wiki, quoted, or
|
||||
summarised.
|
||||
|
||||
Pages the agent creates start as `review: draft`, meaning no person has
|
||||
checked them yet. When new material disagrees with a page and it isn't clear
|
||||
which is right, the agent doesn't pick a winner. It writes a marker into the
|
||||
page and tells you:
|
||||
|
||||
```markdown
|
||||
> CONTRADICTION: three retries (`raw/archive/2026-09-01/kickoff-notes.md`) vs five retries (`raw/archive/2026-11-02/runbook.md`) — found 2026-11-02
|
||||
```
|
||||
|
||||
The marker stays until you settle it (see "Review, contradictions and tags"
|
||||
under [Keeping it tidy](#3-keeping-it-tidy)).
|
||||
|
||||
Skill: `.agents/skills/ckb-ingest/SKILL.md`.
|
||||
|
||||
### B. Just tell the agent something in conversation
|
||||
|
|
@ -301,6 +313,12 @@ listing the pages, entities, raw/archive files, connector indexes, and graph
|
|||
areas that should be searched first for that scope. You still keep one
|
||||
local wiki; this just gives repeated questions a better starting area.
|
||||
|
||||
A scope page can also carry your team's rules for that project, in a
|
||||
`## Rules` section you write yourself: "name environments `prod`/`stage`,
|
||||
never `production`", "decisions here need the client's sign-off". The agent
|
||||
follows them whenever it works inside that scope, and no skill ever rewrites
|
||||
them. Only `AGENTS.md` overrides them.
|
||||
|
||||
---
|
||||
|
||||
## 3. Keeping it tidy
|
||||
|
|
@ -373,6 +391,26 @@ allowlisted: the finding prints a `<path> <hash>` line to add to
|
|||
the line brings the finding back. The same check runs before every "sync
|
||||
changes" commit.
|
||||
|
||||
### Review, contradictions and tags
|
||||
|
||||
**Review.** A page can say whether a person has checked it:
|
||||
`review: draft` (the agent wrote it, nobody checked), `reviewed` (with
|
||||
`reviewed_by` and `reviewed_on`), or `needs_update` (it was reviewed, then
|
||||
changed or was contradicted). Ask "what needs review?" for the queue,
|
||||
`needs_update` first. Say "mark X as reviewed" once you have read a page; the
|
||||
agent records your name and today's date and never marks a page you did not
|
||||
name. If a reviewed page later changes, lint notices. Answers built on draft
|
||||
pages say so.
|
||||
|
||||
**Contradictions.** Lint lists every open `> CONTRADICTION:` marker. Settle
|
||||
one by saying which side is right. The agent then either supersedes the
|
||||
wrong page, records a decision ("record a decision: we retry five times"),
|
||||
or edits the claim, and removes the marker.
|
||||
|
||||
**Tags.** A page may carry `tags: retries, billing`, but only tags listed in
|
||||
`wiki/tags.md`. Add a row there before using a new tag; lint flags any tag
|
||||
that isn't listed. Questions can then be narrowed by tag.
|
||||
|
||||
**Context budget.** Every session starts by loading `AGENTS.md` and the
|
||||
one-line description of every skill. That costs tokens before you have said
|
||||
anything. Lint estimates the cost (characters ÷ 4) and flags it when it
|
||||
|
|
@ -800,6 +838,30 @@ Covered in full in [§2](#2-adding-knowledge) - the short version: drop it
|
|||
in `raw/inbox/` and say "Ingest," or tell the agent in chat if it's
|
||||
small enough to state directly.
|
||||
|
||||
### Your profile and lessons
|
||||
|
||||
Say "set up my profile" and the agent asks up to three questions: your role,
|
||||
how you want it to work with you, and anything to always or never do. Your
|
||||
answers go into `workload/profiles/<your-name>.md`. From then on, every
|
||||
session you start prints your profile into the agent's brief. Other people's
|
||||
profiles are not loaded for you. The file is committed, so keep it to
|
||||
working preferences you'd share with the team.
|
||||
|
||||
Your preferences never override the KB's rules. `AGENTS.md` comes first, a
|
||||
project's `## Rules` next, and your profile fills in the rest.
|
||||
|
||||
When the agent gets something wrong, you can make the correction stick:
|
||||
"remember this: always cite the runbook for retry numbers", or
|
||||
"lesson: …". It asks whether the lesson is yours or for everyone:
|
||||
|
||||
- **Yours** goes into your profile.
|
||||
- **Everyone's** goes into `wiki/lessons.md` and waits for a second person
|
||||
to review it. Everyone else's next session lists it as new.
|
||||
|
||||
Nothing becomes a lesson unless you ask. A lesson that should bind everyone
|
||||
always belongs in `AGENTS.md`; the agent will suggest that rather than edit
|
||||
it. Skill: `.agents/skills/ckb-profile/SKILL.md`.
|
||||
|
||||
### Save a conversation
|
||||
|
||||
Every new session gets a title the agent picks from your first message
|
||||
|
|
@ -1038,6 +1100,8 @@ ship it, so a knowledge base never carries it.
|
|||
| "Save this conversation" | Copies the session transcript (JSONL + readable `.md`) into `raw/saved-conversations/<date>/`; outside retrieval | `ckb-add-conversation` |
|
||||
| "Save conversations automatically" / "Turn off autosave" | Flips `conversations.autosave` in `ckb.yaml`; on, every session is saved at its end without asking | `ckb-add-conversation` |
|
||||
| "Rename this conversation to X" / "Stop telling me the title" | Sets the session's title (used by the saved transcript and the workload note) / flips `conversations.announce_title` | `ckb-add-conversation` |
|
||||
| "Set up my profile" / "Remember this: …" / "Lesson: …" | Writes your profile, or records a personal or KB-wide lesson | `ckb-profile` |
|
||||
| "What needs review?" / "Mark X as reviewed" | Lists draft and needs_update pages / records your review on the pages you name | `ckb-lint` |
|
||||
| "Keep this answer" | Saves the last answer to `outputs/answers/` with its sources and gaps | `ckb-retrieve` |
|
||||
| "Ingest in batch" / "Ingest, no check-in" | Ingests without stopping to show its reading of each source first | `ckb-ingest` |
|
||||
| "Turn on the session-start hook" / "Show the context budget" | Sets `session.start_hook` in `ckb.yaml` and installs the per-machine hook / prints the always-loaded token estimate | `ckb-lint` |
|
||||
|
|
|
|||
|
|
@ -234,6 +234,18 @@ Zanim cokolwiek zostanie zapisane, dzieją się trzy rzeczy:
|
|||
`<private>` … `</private>`, nigdy nie trafia do wiki: nie jest zapisywane,
|
||||
cytowane ani streszczane.
|
||||
|
||||
Strony tworzone przez agenta zaczynają jako `review: draft`, czyli nikt ich
|
||||
jeszcze nie sprawdził. Gdy nowy materiał nie zgadza się ze stroną i nie
|
||||
wiadomo, co jest prawdą, agent nie wybiera zwycięzcy. Wpisuje na stronę
|
||||
znacznik i mówi ci o tym:
|
||||
|
||||
```markdown
|
||||
> CONTRADICTION: three retries (`raw/archive/2026-09-01/kickoff-notes.md`) vs five retries (`raw/archive/2026-11-02/runbook.md`) — found 2026-11-02
|
||||
```
|
||||
|
||||
Znacznik zostaje, dopóki go nie rozstrzygniesz (zob. „Przegląd, sprzeczności
|
||||
i tagi” w [Utrzymaniu porządku](#3-utrzymanie-porządku)).
|
||||
|
||||
Skill: `.agents/skills/ckb-ingest/SKILL.md`.
|
||||
|
||||
### B. Po prostu powiedz agentowi coś w rozmowie
|
||||
|
|
@ -312,6 +324,12 @@ wymieniającą strony, encje, pliki z `raw/archive/`, indeksy konektorów i
|
|||
obszary grafu, które należy przeszukać najpierw dla tego zakresu. Nadal masz
|
||||
jedną lokalną wiki; to tylko daje powracającym pytaniom lepszy punkt startowy.
|
||||
|
||||
Strona zakresu może też zawierać zasady zespołu dla tego projektu, w sekcji
|
||||
`## Rules`, którą piszesz sam: „środowiska nazywamy `prod`/`stage`, nigdy
|
||||
`production`”, „decyzje tutaj wymagają zgody klienta”. Agent stosuje je
|
||||
zawsze, gdy pracuje w tym zakresie, a żaden skill ich nie przepisuje. Nadrzędny
|
||||
jest tylko `AGENTS.md`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Utrzymanie porządku
|
||||
|
|
@ -391,6 +409,26 @@ dokumentacji, można dodać do listy dozwolonych: znalezisko podaje linię
|
|||
Skrót obejmuje tę jedną linię, więc jej edycja przywraca znalezisko. Ta sama
|
||||
kontrola działa przed każdym commitem w „sync changes”.
|
||||
|
||||
### Przegląd, sprzeczności i tagi
|
||||
|
||||
**Przegląd.** Strona może mówić, czy sprawdził ją człowiek: `review: draft`
|
||||
(napisał ją agent, nikt nie sprawdził), `reviewed` (z `reviewed_by` i
|
||||
`reviewed_on`) albo `needs_update` (była przejrzana, potem się zmieniła lub
|
||||
pojawiła się sprzeczność). Zapytaj „what needs review?”, żeby zobaczyć
|
||||
kolejkę, najpierw `needs_update`. Powiedz „mark X as reviewed”, gdy
|
||||
przeczytasz stronę; agent zapisze twoje nazwisko i dzisiejszą datę i nigdy nie
|
||||
oznaczy strony, której nie wskazałeś. Jeśli przejrzana strona później się
|
||||
zmieni, lint to zauważy. Odpowiedzi oparte na stronach `draft` mówią o tym.
|
||||
|
||||
**Sprzeczności.** Lint wypisuje każdy otwarty znacznik `> CONTRADICTION:`.
|
||||
Rozstrzygasz go, mówiąc, która strona ma rację. Agent wtedy zastępuje błędną
|
||||
stronę (supersesja), zapisuje decyzję („record a decision: we retry five
|
||||
times”) albo poprawia twierdzenie, i usuwa znacznik.
|
||||
|
||||
**Tagi.** Strona może mieć `tags: retries, billing`, ale tylko z tagami
|
||||
wymienionymi w `wiki/tags.md`. Zanim użyjesz nowego tagu, dodaj tam wiersz;
|
||||
lint flaguje każdy tag spoza listy. Pytania można wtedy zawęzić do tagu.
|
||||
|
||||
**Budżet kontekstu.** Każda sesja zaczyna się od wczytania `AGENTS.md` i
|
||||
jednolinijkowego opisu każdego skilla. To kosztuje tokeny, zanim cokolwiek
|
||||
powiesz. Lint szacuje ten koszt (znaki ÷ 4) i flaguje go, gdy przekroczy
|
||||
|
|
@ -841,6 +879,30 @@ W pełni opisane w [§2](#2-dodawanie-wiedzy) — w skrócie: wrzuć materiał d
|
|||
`raw/inbox/` i powiedz „Ingest”, albo powiedz agentowi w
|
||||
rozmowie, jeśli to wystarczająco krótkie, żeby podać wprost.
|
||||
|
||||
### Twój profil i lekcje
|
||||
|
||||
Powiedz „set up my profile”, a agent zada do trzech pytań: o twoją rolę, o to,
|
||||
jak ma z tobą pracować, i o to, czego zawsze lub nigdy nie robić. Odpowiedzi
|
||||
trafiają do `workload/profiles/<twoje-imię>.md`. Od tej pory każda sesja, którą
|
||||
zaczynasz, wypisuje twój profil w podsumowaniu agenta. Profile innych osób nie
|
||||
są dla ciebie wczytywane. Plik jest commitowany, więc trzymaj w nim tylko
|
||||
preferencje robocze, którymi podzieliłbyś się z zespołem.
|
||||
|
||||
Twoje preferencje nigdy nie są ważniejsze od zasad KB. Najpierw `AGENTS.md`,
|
||||
potem `## Rules` projektu, a resztę uzupełnia twój profil.
|
||||
|
||||
Gdy agent się pomyli, możesz utrwalić poprawkę: „remember this: always cite
|
||||
the runbook for retry numbers” albo „lesson: …”. Agent pyta, czy lekcja jest
|
||||
twoja, czy dla wszystkich:
|
||||
|
||||
- **Twoja** trafia do twojego profilu.
|
||||
- **Dla wszystkich** trafia do `wiki/lessons.md` i czeka na przegląd drugiej
|
||||
osoby. Najbliższa sesja każdej innej osoby wymieni ją jako nową.
|
||||
|
||||
Nic nie staje się lekcją, jeśli o to nie poprosisz. Lekcja, która ma zawsze
|
||||
obowiązywać wszystkich, należy do `AGENTS.md`; agent to zasugeruje, zamiast go
|
||||
edytować. Skill: `.agents/skills/ckb-profile/SKILL.md`.
|
||||
|
||||
### Zapisywanie rozmowy
|
||||
|
||||
Każda nowa sesja dostaje tytuł, który agent sam wybiera na podstawie
|
||||
|
|
@ -1089,6 +1151,8 @@ wiedzy nigdy go nie zawiera.
|
|||
| „Save conversations automatically” / „Turn off autosave” | Przestawia `conversations.autosave` w `ckb.yaml`; po włączeniu każda sesja jest zapisywana na końcu bez pytania | `ckb-add-conversation` |
|
||||
| „Rename this conversation to X” / „Stop telling me the title” | Ustawia tytuł sesji (używany przez zapisany transkrypt i notatkę workload) / przestawia `conversations.announce_title` | `ckb-add-conversation` |
|
||||
| „Retract X” / „Undo the ingest of X” / „This went to the wrong KB” | Pokazuje, co zbudowało źródło (strony, twierdzenia, krawędzie), a po twojej zgodzie usuwa dokładnie to; obsługuje prośby z `raw/retractions/` | `ckb-retract` |
|
||||
| „Set up my profile” / „Remember this: …” / „Lesson: …” | Zapisuje twój profil albo lekcję osobistą lub dla całej KB | `ckb-profile` |
|
||||
| „What needs review?” / „Mark X as reviewed” | Wypisuje strony draft i needs_update / zapisuje twój przegląd wskazanych stron | `ckb-lint` |
|
||||
| „Keep this answer” | Zapisuje ostatnią odpowiedź w `outputs/answers/` razem ze źródłami i lukami | `ckb-retrieve` |
|
||||
| „Ingest in batch” / „Ingest, no check-in” | Ingestuje bez zatrzymywania się, by najpierw pokazać, jak rozumie każde źródło | `ckb-ingest` |
|
||||
| „Turn on the session-start hook” / „Show the context budget” | Ustawia `session.start_hook` w `ckb.yaml` i instaluje hook na tej maszynie / pokazuje szacunek tokenów warstwy ładowanej zawsze | `ckb-lint` |
|
||||
|
|
|
|||
|
|
@ -0,0 +1,91 @@
|
|||
---
|
||||
type: decision
|
||||
tldr: Schema 1.6 adds optional review fields (review, reviewed_by, reviewed_on), a tags field checked against wiki/tags.md, an in-page `> CONTRADICTION:` marker, a protected `## Rules` section on project scope pages, per-person profiles in workload/profiles/, and explicit lessons; ckb-lint owns review marking, a new ckb-profile skill owns profiles and lessons, and claim-level validity dates are deferred.
|
||||
status: accepted
|
||||
decided_on: 2026-11-02
|
||||
decided_by: Michał Kopeć
|
||||
affects: AGENTS.md, wiki/index.md, wiki/tags.md, .agents/skills/ckb-ingest/, .agents/skills/ckb-lint/, .agents/skills/ckb-retrieve/, .agents/skills/ckb-profile/, .agents/skills/ckb-upgrade/, .agents/skills/ckb-init/, .agents/skills/ckb-reset/, .agents/skills/ckb-export-starlight/, docs/CHANGELOG.md, docs/MANUAL.md
|
||||
confidence: 0.75
|
||||
quality: 0.8
|
||||
last_updated: 2026-11-02
|
||||
freshness_window_days: 365
|
||||
retention: high
|
||||
---
|
||||
|
||||
# D-0014 — Schema 1.6: review, contradictions, tags, profiles and lessons
|
||||
|
||||
**Status:** Accepted · **Decided:** 2026-11-02 · **Deciders:** Michał Kopeć
|
||||
|
||||
## Context
|
||||
|
||||
Release 2 of the agent-knowledge plan (research report of 2026-10-31,
|
||||
features F7, F4, F21, F9, F8) needs new page fields and conventions. The
|
||||
plan named the review field `status`, but decision pages already use
|
||||
`status` for `proposed`/`accepted`/…. One field with two vocabularies would
|
||||
make every reader branch on `type`.
|
||||
|
||||
## Decision
|
||||
|
||||
Schema 1.6 is additive: every addition is optional, and a 1.5 page is a valid
|
||||
1.6 page.
|
||||
|
||||
1. **Review (F7).** `review: draft | reviewed | needs_update`, plus
|
||||
`reviewed_by` and `reviewed_on`. An absent `review` means "not tracked", not
|
||||
"draft". `ckb-ingest` writes `review: draft` on pages it creates, and sets
|
||||
`needs_update` when it changes the substance of a `reviewed` page.
|
||||
Substance is what a page claims: prose, tables, `tldr`, `## Sources`,
|
||||
`## Crux`. Links, index rows, formatting and metadata scores are not.
|
||||
`reviewed_by`/`reviewed_on` keep naming the last review. `ckb-lint` owns
|
||||
the review queue and "mark X as reviewed"; no new skill.
|
||||
2. **Contradictions (F4, phase 1).** A line
|
||||
`` > CONTRADICTION: <claim> (`<source>`) vs <claim> (`<source>`) — found YYYY-MM-DD ``
|
||||
in the page body, written by `ckb-ingest` instead of silently picking a
|
||||
winner. The page goes to `needs_update`. Lint lists every open marker; one
|
||||
is closed by supersession, a `ckb-decide` record, or an edit the user
|
||||
chose, and the marker is then removed with a log entry.
|
||||
Claim-level `valid_from`/`valid_to` are **deferred**: prototype them on one
|
||||
page type first.
|
||||
3. **Tags (F21).** `tags: a, b` — a flat comma list, because page
|
||||
frontmatter is flat. Every tag must be listed in `wiki/tags.md`
|
||||
(`type: vocabulary`), a new scaffold file that the KB owns, the way the
|
||||
graph has a closed verb list. `retrieve_candidates.py --tag` filters on
|
||||
them.
|
||||
4. **Scopes and profiles (F9).** Three scopes, in this order of precedence:
|
||||
the rules in `AGENTS.md` always win; inside a project scope, the scope
|
||||
page's `## Rules` section (new, reserved, human-owned and protected like
|
||||
`## Notes`) wins next; a person's profile shapes how the agent works with
|
||||
that person where neither says otherwise. Profiles live in
|
||||
`workload/profiles/<author-slug>.md`, outside retrieval. The session-start
|
||||
brief prints the profile of the session identity only. Profiles are
|
||||
committed, so they hold only what the person is content to share.
|
||||
5. **Lessons (F8).** Recorded only on an explicit trigger ("remember this",
|
||||
"lesson: …"), never by guessing from tone. Format: rule, why, applies
|
||||
when, scope, date. A personal lesson goes to the profile's `## Lessons`; a
|
||||
KB lesson goes to `wiki/lessons.md` (`type: lessons`), which then carries
|
||||
`review: needs_update` until someone reviews it. The brief lists KB
|
||||
lessons added since the person's previous workload note.
|
||||
6. **`ckb-profile`** is a new skill that owns profiles and lessons. No
|
||||
existing skill fits, and both need a trigger of their own.
|
||||
7. **Dropped from the plan:** a `verified` date on rules; `reviewed_on`
|
||||
already says it.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
- **`status` with an exception for decisions** was rejected: two meanings
|
||||
for one key.
|
||||
- **A `ckb-review` skill** was rejected: lint already reports page health,
|
||||
and one more description costs every session tokens.
|
||||
- **Nested `rules.md` per project** was rejected: project scopes are single
|
||||
pages, not folders.
|
||||
- **Lessons detected from corrections automatically** were rejected: noisy,
|
||||
and they would write to a shared KB on a guess.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Draft pages are expected, not defects: lint shows a review queue but
|
||||
counts only inconsistencies (a bad value, a reviewed page changed since
|
||||
its review, an open contradiction, an unknown tag) as findings.
|
||||
- `ckb-upgrade` migrates 1.5 → 1.6 by adding `wiki/tags.md` and bumping the
|
||||
version. It backfills `review` only on request.
|
||||
- The always-loaded layer grows by one skill description and a few lines in
|
||||
`AGENTS.md`. The context budget meter (D-0013) measures it.
|
||||
|
|
@ -27,3 +27,4 @@ but they live here, in the template layer, because:
|
|||
| [D-0011](0011-session-start-hook.md) | Session start can run as a per-machine, opt-in Claude Code `SessionStart` hook that injects the Rule E brief before the first message and after every compaction; Rule E stays the fallback |
|
||||
| [D-0012](0012-open-threads-not-a-status-file.md) | "What is in flight" is collected from `### Open threads` checkboxes in each person's workload notes, not a shared status page; threads close where they were opened |
|
||||
| [D-0013](0013-kept-answers-and-secret-guards.md) | Kept answers go to `outputs/answers/` with fingerprinted sources and reach the wiki only through ingest; committed text is scanned for secrets and `<private>` spans, never auto-fixed, with a line-hash allowlist |
|
||||
| [D-0014](0014-schema-1-6-review-contradictions-tags-profiles.md) | Schema 1.6: `review`/`reviewed_by`/`reviewed_on` (not `status`), `tags` against `wiki/tags.md`, a `> CONTRADICTION:` marker, protected `## Rules` on project scopes; profiles in `workload/profiles/` and explicit lessons via a new `ckb-profile` skill; claim-level validity deferred |
|
||||
|
|
|
|||
|
|
@ -14,6 +14,10 @@
|
|||
"index_log": [],
|
||||
"evidence": [],
|
||||
"crux": [],
|
||||
"review": [],
|
||||
"contradictions": [],
|
||||
"tags": [],
|
||||
"review_queue": [],
|
||||
"hubs": [
|
||||
[
|
||||
"entities/atlas-retry-policy",
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -85,6 +85,22 @@ echo "<private>do not keep</private>" >> "$TMP/sec/wiki/overview.md"
|
|||
ALLOW=$(grep -o 'add `workload/[^`]*`' "$TMP/secrets.txt" | sed 's/^add `//; s/`$//')
|
||||
echo "$ALLOW # smoke: fixture key" > "$TMP/sec/.secrets-allow"
|
||||
( cd "$TMP/sec" && python3 "$OLDPWD/$LINT" --secrets || true ) > "$TMP/secrets-allowed.txt"
|
||||
# Schema 1.6: review fields, a contradiction marker, tags against a vocabulary, profile and lessons.
|
||||
S16="$TMP/s16"; mkdir -p "$S16" && cp -r "$FIX/." "$S16/" && W="$S16/wiki"
|
||||
printf -- '---\ntype: vocabulary\ntldr: Tags.\n---\n\n# Tags\n\n| Tag | Meaning | Use for |\n|---|---|---|\n| `retries` | Retry behaviour | Retry questions |\n' > "$W/tags.md"
|
||||
echo '| [Tags](tags.md) | Tag vocabulary | Tagging |' >> "$W/index.md"
|
||||
sed -i 's/^retention: high$/retention: high\ntags: retries, made-up\nreview: reviewed\nreviewed_by: Fixture User\nreviewed_on: 2026-09-01/' "$W/entities/atlas-retry-policy.md"
|
||||
sed -i 's/^retention: medium$/retention: medium\nreview: draft/' "$W/entities/maria-nowak.md"
|
||||
printf '\n> CONTRADICTION: three retries (`raw/archive/2026-09-01/kickoff-notes.md`) vs five retries (`raw/archive/2026-09-02/dlq-review.md`) — found 2026-09-24\n' >> "$W/entities/maria-nowak.md"
|
||||
sed -i 's/^type: project$/type: project\nreview: approved/' "$W/projects/atlas.md"
|
||||
printf -- '---\ntype: lessons\ntldr: Lessons.\nreview: needs_update\n---\n\n# Lessons\n\n### 2026-09-05 — Old lesson already seen\n- **Scope:** KB\n\n### 2026-09-20 — Cite the runbook for retry numbers\n- **Scope:** KB\n' > "$W/lessons.md"
|
||||
( cd "$S16" && python3 "$OLDPWD/$LINT" --json --today "$TODAY" || true ) > "$TMP/s16-lint.json"
|
||||
python3 "$RETR" "how many times does Atlas retry a failed batch" --root "$S16" --today "$TODAY" --tag retries --json > "$TMP/s16-retr.json"
|
||||
SLUG=$(cd "$S16" && python3 -c "import sys;sys.path.insert(0,sys.argv[1]);import session_start as s;from pathlib import Path;print(s.author_slug(Path('.')))" "$OLDPWD/.agents/skills/ckb-lint/scripts")
|
||||
mkdir -p "$S16/workload/profiles" && printf -- '---\ntype: profile\n---\n\n# Fixture\n\n## How to work with me\n- Answer in short bullets.\n' > "$S16/workload/profiles/$SLUG.md"
|
||||
printf -- '---\ntype: session\n---\n\n## Earlier\n- worked\n' > "$S16/workload/2026-09-10_${SLUG}_summary.md"
|
||||
( cd "$S16" && python3 "$OLDPWD/.agents/skills/ckb-lint/scripts/session_start.py" --today "$TODAY" --no-git ) > "$TMP/s16-start.txt"
|
||||
|
||||
# Private spans never reach a saved conversation.
|
||||
mkdir -p "$TMP/priv" && sed 's#How many times does Atlas retry a failed batch?#<private>hunter2 is the vault code</private> How many times does Atlas retry a failed batch?#' \
|
||||
tests/fixtures/conversation/session.jsonl > "$TMP/priv-session.jsonl"
|
||||
|
|
@ -139,6 +155,33 @@ python3 -c "import json,sys;h=json.load(open(sys.argv[1]))['hooks']['Stop'];c=[x
|
|||
ls "$TMP"/proj/raw/saved-conversations/*/*.md >/dev/null 2>&1 && [[ ! -e "$TMP/proj/sub/raw" ]] \
|
||||
|| { echo "autosave hook: run from a subfolder, it did not save into the project root"; fail=1; }
|
||||
grep -q 'ckb check:' "$TMP/hookroot.json" || { echo "start hook: run from a subfolder, it printed no brief"; fail=1; }
|
||||
python3 - "$TMP/s16-lint.json" <<'PY' || fail=1
|
||||
import json, sys
|
||||
t = json.load(open(sys.argv[1]))["trees"][0]
|
||||
want = {"review": 2, "contradictions": 1, "tags": 1}
|
||||
got = {k: len(t[k]) for k in want}
|
||||
problems = [f"schema 1.6 lint: {k} expected {v}, got {got[k]}: {t[k]}" for k, v in want.items() if got[k] != v]
|
||||
if not any("changed since its review" in f for f in t["review"]):
|
||||
problems.append("schema 1.6 lint: reviewed page edited after review not flagged")
|
||||
if not any("made-up" in f for f in t["tags"]):
|
||||
problems.append("schema 1.6 lint: unknown tag not flagged")
|
||||
if sorted(t["review_queue"]) != ["entities/maria-nowak.md (draft)", "lessons.md (needs_update)"]:
|
||||
problems.append(f"schema 1.6 lint: review queue {t['review_queue']}")
|
||||
problems and print("\n".join(problems)); sys.exit(1 if problems else 0)
|
||||
PY
|
||||
python3 -c "import json,sys;c=json.load(open(sys.argv[1]))['candidates'];assert [x['path'] for x in c]==['wiki/entities/atlas-retry-policy.md'] and c[0]['review']=='reviewed'" "$TMP/s16-retr.json" \
|
||||
|| { echo "retrieve --tag: expected only the tagged page"; fail=1; }
|
||||
grep -q '^profile: workload/profiles/' "$TMP/s16-start.txt" && grep -q 'Answer in short bullets' "$TMP/s16-start.txt" || { echo "session_start: profile not printed"; fail=1; }
|
||||
grep -q '^lessons: 1 in wiki/lessons.md since your note of 2026-09-10' "$TMP/s16-start.txt" && grep -q 'Cite the runbook' "$TMP/s16-start.txt" \
|
||||
|| { echo "session_start: new lesson not listed"; grep lessons "$TMP/s16-start.txt"; fail=1; }
|
||||
grep -q '^### Open threads' "$TMP/start-threads.txt" && { echo "session_start: open threads printed twice"; fail=1; }
|
||||
# A growing transcript: one `match:` allowlist entry covers the same key on every line.
|
||||
mkdir -p "$TMP/sec/raw/saved-conversations/d" && for i in 1 2 3; do echo "turn $i AKIAQRSTUVWXYZABCDEF" >> "$TMP/sec/raw/saved-conversations/d/t.jsonl"; done
|
||||
MH=$(cd "$TMP/sec" && { python3 "$OLDPWD/$LINT" --secrets || true; } | grep 't.jsonl' | grep -o 'match:[0-9a-f]*' | head -1)
|
||||
echo "raw/saved-conversations/*/*.jsonl $MH" >> "$TMP/sec/.secrets-allow"
|
||||
[[ "$(cd "$TMP/sec" && python3 "$OLDPWD/$LINT" --secrets | tail -1)" == "secrets: 1 possible" ]] || { echo "secrets: match: allowlist entry not honoured"; fail=1; }
|
||||
[[ "$(cd "$TMP/sec" && bash "$OLDPWD/$QUICK" --today "$TODAY" | sed 's/ (fallback:.*//')" == "ckb check: 1 possible secrets — run \"lint\" for detail" ]] \
|
||||
|| { echo "lint_quick.sh: match: allowlist entry not honoured"; fail=1; }
|
||||
# The template must stay inside its own context budget.
|
||||
python3 "$LINT" --budget > "$TMP/budget.txt" || { echo "budget: template is over its own always-loaded budget"; head -3 "$TMP/budget.txt"; fail=1; }
|
||||
# mcp module: what a remote client may read and write (no MCP SDK needed).
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
kb_schema_version: "1.5"
|
||||
kb_schema_version: "1.6"
|
||||
---
|
||||
|
||||
# Knowledge Base Index
|
||||
|
|
@ -16,6 +16,7 @@ kb_schema_version: "1.5"
|
|||
| [Decisions](decisions/index.md) | Numbered decision records — what was decided, by whom, when, why, and what it superseded | Asking why something is the way it is, who decided it, when, what changed it, or what is still open |
|
||||
| [Entities](entities/index.md) | Typed entity pages (people, projects, libraries, concepts) | Looking up a specific person, project, library, or concept |
|
||||
| [Graph](graph/index.md) | Edge lists and relationship data between entities | Finding what depends on / relates to a given entity |
|
||||
| [Tags](tags.md) | The closed vocabulary for the optional `tags:` page field | Tagging a page, or filtering retrieval by tag |
|
||||
|
||||
## Entity Pages
|
||||
|
||||
|
|
|
|||
16
wiki/tags.md
Normal file
16
wiki/tags.md
Normal file
|
|
@ -0,0 +1,16 @@
|
|||
---
|
||||
type: vocabulary
|
||||
tldr: The closed list of tags a page may carry in its `tags:` field; ckb-lint flags any tag not listed here.
|
||||
last_updated: 2026-11-02
|
||||
---
|
||||
|
||||
# Tags
|
||||
|
||||
Every value in a page's `tags:` frontmatter must appear in this table. Add a
|
||||
row before using a new tag. Keep tags lower-case and hyphenated, and keep the
|
||||
list short: a tag that fits most pages tells retrieval nothing.
|
||||
|
||||
| Tag | Meaning | Use for |
|
||||
|---|---|---|
|
||||
|
||||
*(No tags yet. Add the first row when a page needs one.)*
|
||||
Loading…
Add table
Reference in a new issue