Merge origin/main (conflict resolved: kept remote superset of workload summary)
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
commit
8174a54cee
22 changed files with 907 additions and 228 deletions
|
|
@ -134,8 +134,8 @@ the report rather than silently patching the export.
|
|||
### Step 7 — Validate the output bundle
|
||||
|
||||
Before reporting done, re-check the *generated* `outputs/okf/` bundle
|
||||
against OKF's own conformance criteria (the same shape of check `CLAUDE.md`
|
||||
§6 step 1 runs against the source wiki):
|
||||
against OKF's own conformance criteria (the same shape of conformance check
|
||||
`ckb-lint` runs against the source wiki):
|
||||
|
||||
- Every non-reserved `.md` file has frontmatter with a non-empty `type`.
|
||||
- The root `index.md`'s frontmatter contains only `okf_version` (or is
|
||||
|
|
@ -168,7 +168,7 @@ Tell the user:
|
|||
spec-valid, don't skip the directory entirely.
|
||||
- **A wiki page missing `type`:** per Step 3, use `type: unknown` and flag
|
||||
it in the report — this indicates the source wiki itself failed lint's
|
||||
conformance check (see `CLAUDE.md` §6 step 1), which is worth surfacing
|
||||
conformance check, which is worth surfacing
|
||||
to the user rather than quietly masking it in the export.
|
||||
- **A future `wiki/archived/` directory:** export it like any other
|
||||
subdirectory (mirror the structure, apply the same per-file rules) —
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: ckb-index-external
|
||||
description: Walk every connector-backed libs/<name>/ (identified by a source.yaml declaring a live external source — SharePoint, Google Drive, a plain URL, or another connector) and build/refresh a self-contained generated index for it — index.md/entities/graph/log.md, mirroring wiki/'s own shape but scoped entirely to that one connector. Indexing goes beyond one page per document: for every document found, it also extracts the people, organizations, projects, decisions, systems, and processes that document actually discusses into their own thin, pointer-style entity pages (evidence back to the specific documents that mention them, not a second copy of wiki/'s synthesis), so the index supports "what do we know about X / what's the process for Y" lookups, not just "what documents exist at this source". The index can optionally be published to (and fetched from) a shared location — a git repo or a shared resource — declared in source.yaml, so most users just read an already-built index instead of re-scanning the live source. Read vs. write access to a given source is a per-user, local-only setting (libs/<name>/source.local.yaml, gitignored) — read-only by default, so one or two designated admins can maintain a source for everyone else. Never touches wiki/, never touches source.yaml, never touches a git-copy lib. Use when the user says "index external sources", "index libs", "refresh the external index", or "scan the SharePoint/Drive folder". This is the on-demand workflow from CLAUDE.md/AGENTS.md §4, distinct from `ckb-ingest` (which processes raw/inbox/ into wiki/) and from a plain git-copy libs/<name>/ (a frozen clone, never touched by any skill).
|
||||
description: Walk every connector-backed libs/<name>/ (identified by a source.yaml declaring a live external source — SharePoint, Google Drive, a plain URL, or another connector) and build/refresh a self-contained generated index for it — index.md/entities/graph/log.md, mirroring wiki/'s own shape but scoped entirely to that one connector. Indexing goes beyond one page per document: for every document found, it also extracts the people, organizations, projects, decisions, systems, and processes that document actually discusses into their own thin, pointer-style entity pages (evidence back to the specific documents that mention them, not a second copy of wiki/'s synthesis), so the index supports "what do we know about X / what's the process for Y" lookups, not just "what documents exist at this source". The index can optionally be published to (and fetched from) a shared location — a git repo or a shared resource — declared in source.yaml, so most users just read an already-built index instead of re-scanning the live source. Read vs. write access to a given source is a per-user, local-only setting (libs/<name>/source.local.yaml, gitignored) — read-only by default, so one or two designated admins can maintain a source for everyone else. Never touches wiki/, never touches source.yaml, never touches a git-copy lib. Use when the user says "index external sources", "index libs", "refresh the external index", or "scan the SharePoint/Drive folder". This is the on-demand external-source workflow routed by CLAUDE.md/AGENTS.md, distinct from `ckb-ingest` (which processes raw/inbox/ into wiki/) and from a plain git-copy libs/<name>/ (a frozen clone, never touched by any skill).
|
||||
---
|
||||
|
||||
# Index external sources skill
|
||||
|
|
@ -94,6 +94,12 @@ connector: sharepoint # sharepoint | google_drive | web | custom — open
|
|||
location: "https://contoso.sharepoint.com/sites/Finance/Shared Documents/Reports"
|
||||
description: "Finance team's shared reports folder" # optional
|
||||
|
||||
refresh_interval_days: 7 # optional — how often a write-access run should rebuild this source,
|
||||
# and the freshness_window_days stamped on its generated pages.
|
||||
# Omit to use the default of 30. Tune per source: a busy folder
|
||||
# that changes daily deserves a shorter window than a quarterly
|
||||
# reports archive that barely moves.
|
||||
|
||||
index: # optional — omit entirely for the original default: the index lives only
|
||||
# here, in this repo, tracked by this repo's own git (nothing to fetch/publish)
|
||||
store: git # git | shared — open string, where the built index is published to / fetched from
|
||||
|
|
@ -183,6 +189,15 @@ This is the one place access level actually changes behavior:
|
|||
from here on; Step 8 is what actually creates the remote copy either
|
||||
way.
|
||||
|
||||
Either way, compare the existing index's newest `last_updated` against
|
||||
this source's `refresh_interval_days` (default 30) and say where it
|
||||
stands. A read-only user needs to know they're reading a copy that's three
|
||||
weeks past due so they can go ask the admin rather than quietly trusting
|
||||
it; a write-access user is about to rebuild anyway, but "this was 40 days
|
||||
stale" is worth saying, because a source that's routinely overdue is
|
||||
either configured with too tight an interval or has nobody actually
|
||||
maintaining it. Both are worth surfacing rather than silently correcting.
|
||||
|
||||
### Step 5 — Resolve the connector and enumerate/summarize documents
|
||||
|
||||
Resolve `connector` to whatever live tool is actually available this
|
||||
|
|
@ -215,7 +230,8 @@ tldr: ...
|
|||
confidence: 0.3–0.9 # per the rule above
|
||||
quality: ...
|
||||
last_updated: YYYY-MM-DD
|
||||
freshness_window_days: 30 # shorter than a typical wiki page — external sources change without notice
|
||||
freshness_window_days: 30 # this source's refresh_interval_days, or 30 if unset — shorter than a
|
||||
# typical wiki page, because external sources change without notice
|
||||
retention: medium
|
||||
---
|
||||
```
|
||||
|
|
@ -253,7 +269,7 @@ tldr: One sentence — who/what this is, and what these documents specifically s
|
|||
confidence: 0.3–0.9
|
||||
quality: ...
|
||||
last_updated: YYYY-MM-DD
|
||||
freshness_window_days: 30
|
||||
freshness_window_days: 30 # or this source's refresh_interval_days, if set
|
||||
retention: medium
|
||||
---
|
||||
```
|
||||
|
|
@ -313,7 +329,7 @@ Update `libs/<name>/graph/index.md` (same convention as
|
|||
`wiki/graph/index.md`) to summarize both the `mentioned_in` document
|
||||
coverage and any real entity-to-entity edges found. Log every
|
||||
created/updated page in `libs/<name>/log.md`, same reverse-chronological
|
||||
format as Rule B (`CLAUDE.md`/`AGENTS.md` §7) — this log is independent of
|
||||
format as Rule B in `CLAUDE.md`/`AGENTS.md` — this log is independent of
|
||||
`wiki/log.md`; **nothing under `wiki/` is touched by this skill at all.**
|
||||
|
||||
### Step 8 — Publish, if this source has both write access and a configured index store
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: ckb-ingest
|
||||
description: Process raw/inbox/ (or raw/ directly if the inbox is empty) into the structured wiki/ — consult the cascade, extract typed entities and relationships, synthesize frontmatted pages, cross-link them, update the index and log, then remind the user to review and sync to origin. Use when the user says "Ingest", "Sync the wiki", or "Update the Wiki". This is the content-level workflow from CLAUDE.md/AGENTS.md §3, distinct from the git-level `ckb-sync-changes` skill (which reconciles this repo's own history with its `origin` remote and does no wiki synthesis at all).
|
||||
description: Process raw/inbox/ (or raw/ directly if the inbox is empty) into the structured wiki/ — consult the cascade, extract typed entities and relationships, synthesize frontmatted pages, cross-link them, update the index and log, then remind the user to review and sync to origin. Use when the user says "Ingest", "Sync the wiki", or "Update the Wiki". This is the content-level workflow routed by CLAUDE.md/AGENTS.md, distinct from the git-level `ckb-sync-changes` skill (which reconciles this repo's own history with its `origin` remote and does no wiki synthesis at all).
|
||||
---
|
||||
|
||||
# Ingest skill
|
||||
|
|
@ -63,6 +63,24 @@ libraries, concepts, systems. Create entity pages at
|
|||
relationships between entities — `uses`, `depends_on`, `caused`,
|
||||
`contradicts`, `supersedes` — as edge data in `wiki/graph/edges.json`.
|
||||
|
||||
Also record `has_expertise_in` and `owns` edges when the material actually
|
||||
evidences them: `has_expertise_in` when a person demonstrably answers
|
||||
questions or explains decisions on a topic, `owns` when they hold
|
||||
declared responsibility for a system, area, or decision. These are what
|
||||
make "who knows about X" and "who owns X" answerable as a direct graph
|
||||
lookup instead of a full-text guess (see `ckb-retrieve` Step 3). Record
|
||||
them only from demonstrated evidence — someone being present in a meeting
|
||||
or cc'd on a thread is not expertise, and don't infer ownership from job
|
||||
title alone. Both are optional, like every other edge type; an absent
|
||||
edge is better than a fabricated one.
|
||||
|
||||
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
|
||||
wiki/entity/source paths, exclusions, and refresh hints. Create one only
|
||||
when the source material shows a real repeated scope; don't manufacture
|
||||
scopes for one-off facts.
|
||||
|
||||
### Step 4 — Synthesize pages
|
||||
|
||||
Convert the core knowledge into clean, modular Markdown files. Every page
|
||||
|
|
@ -75,9 +93,44 @@ gets frontmatter with:
|
|||
- A `retention:` level.
|
||||
|
||||
`type` is also required (per the page frontmatter schema in
|
||||
`CLAUDE.md`/`AGENTS.md` §2) — set it once, based on the entity/content
|
||||
`CLAUDE.md`/`AGENTS.md` page schema) — set it once, based on the entity/content
|
||||
kind (person, project, concept, library, decision, playbook, ...).
|
||||
|
||||
For long conversations, meeting notes, transcripts, or chat exports, use a
|
||||
structured distillation before writing the final page:
|
||||
- `Question` or searchable problem statement, when there is one.
|
||||
- `Summary` of the thread/note.
|
||||
- `Resolution` or `Decision`, if the material contains one.
|
||||
- `Systems and code references` mentioned.
|
||||
- `People involved` or apparent owners/experts.
|
||||
- `High-signal excerpts` for dense technical paragraphs or consecutive
|
||||
messages that would be lost in a single summary.
|
||||
|
||||
"High-signal" needs an acceptance test, or every excerpt looks worth
|
||||
keeping and the page becomes a second copy of the transcript. Promote a
|
||||
run of text to its own section or linked page only when it clears all
|
||||
three:
|
||||
- **It carries a rare term.** Something specific enough that a future
|
||||
search would use it — a config flag, an error string, a hostname, a
|
||||
contract clause, a version number. Check with `rg -c` across `wiki/`:
|
||||
if the term already appears on many pages it isn't a distinguishing
|
||||
handle, and the excerpt adds no findability the summary doesn't have.
|
||||
- **It's substantial.** Roughly 200 characters or more, or a few
|
||||
consecutive paragraphs/messages from one author. A one-line "yes, do
|
||||
that" is a resolution to fold into `Resolution`, not an excerpt.
|
||||
- **Something corroborates it.** It was agreed with, acted on, corrected,
|
||||
or referred back to later in the material. An unanswered assertion is a
|
||||
claim, not a settled fact — keep it in the summary with that ambiguity
|
||||
intact rather than promoting it.
|
||||
|
||||
Fail any one of the three and the content still belongs in the page, just
|
||||
inside `Summary`/`Resolution` rather than as its own retrievable unit.
|
||||
|
||||
When you do promote an excerpt, carry its parent topic with it — the
|
||||
thread question or section heading it sat under. An excerpt that reads
|
||||
unambiguously on its own is the entire point; one that needs the
|
||||
surrounding transcript to make sense hasn't been extracted, only moved.
|
||||
|
||||
### Step 5 — Link and cross-reference
|
||||
|
||||
Use **both** `[[Wikilinks]]` (Obsidian-compatible) and standard
|
||||
|
|
@ -92,12 +145,17 @@ description. If the page lives in a subdirectory, also add it to that
|
|||
subdirectory's own `index.md`. Append a log entry to the most specific
|
||||
applicable log — the subdirectory's `log.md` if it has one, otherwise the
|
||||
root `wiki/log.md` — following the format in Rule B (`CLAUDE.md`/
|
||||
`AGENTS.md` §7).
|
||||
`AGENTS.md` Rule B).
|
||||
|
||||
If this step creates a brand-new `wiki/<topic>/` subdirectory, immediately
|
||||
create that subdirectory's `index.md` per the Recursive Index & Log
|
||||
Convention.
|
||||
|
||||
If this step creates or updates a project scope under `wiki/projects/`,
|
||||
also update `wiki/projects/index.md`. If ingest closes a previously
|
||||
recorded question in `wiki/query-gaps.md`, move that entry from Open to
|
||||
Resolved and mention the page or source that now answers it.
|
||||
|
||||
### Step 7 — Remind to review and sync
|
||||
|
||||
This is always the last step, every time this skill runs and made any
|
||||
|
|
@ -122,7 +180,7 @@ process), skip this reminder — there's nothing to review or sync.
|
|||
considered, but note in the ingest report that it produced no wiki
|
||||
change.
|
||||
- **Conflicting information vs. an existing local wiki page** — this is a
|
||||
supersession case (Rule via `CLAUDE.md`/`AGENTS.md` §6 lint), not a
|
||||
supersession case handled consistently with `ckb-lint`, not a
|
||||
silent overwrite: update the existing page if the new source is clearly
|
||||
more current/corroborated, and link `supersedes`/`superseded_by` if an
|
||||
older version is worth preserving rather than edited in place.
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: ckb-lint
|
||||
description: Health-check the wiki/ — conformance, freshness, confidence decay, retention sweep, supersession detection, orphan detection, graph consistency, index/log consistency, and error-book entries — auto-fixing what it safely can and reporting the rest, then reminding the user to review and sync to origin. Also runs the same checks against each connector-backed libs/<name>/'s own generated index (see ckb-index-external), plus a source.yaml validity check, without ever touching a git-copy lib or a connector's source.yaml itself. Use when the user says "Lint", "health-check the wiki", "check the wiki", or asks for a periodic/scheduled wiki health check. This is the maintenance workflow from CLAUDE.md/AGENTS.md §6, distinct from `ckb-ingest` (which adds new content) and `ckb-sync-changes` (a pure git-level operation with no wiki synthesis at all).
|
||||
description: Health-check the wiki/ — conformance, freshness, confidence decay, retention sweep, supersession detection, orphan detection, graph consistency, index/log consistency, and error-book entries — auto-fixing what it safely can and reporting the rest, then reminding the user to review and sync to origin. Also runs the same checks against each connector-backed libs/<name>/'s own generated index (see ckb-index-external), plus a source.yaml validity check, without ever touching a git-copy lib or a connector's source.yaml itself. Use when the user says "Lint", "health-check the wiki", "check the wiki", or asks for a periodic/scheduled wiki health check. This is the maintenance workflow routed by CLAUDE.md/AGENTS.md, distinct from `ckb-ingest` (which adds new content) and `ckb-sync-changes` (a pure git-level operation with no wiki synthesis at all).
|
||||
---
|
||||
|
||||
# Lint skill
|
||||
|
|
@ -19,7 +19,7 @@ actually invoked — on demand, or on a schedule if the user has set one up.
|
|||
|
||||
This skill only ever writes within `wiki/` (including moves into
|
||||
`wiki/archived/`) and, for any connector-backed `libs/<name>/` (one with a
|
||||
`source.yaml` — see `CLAUDE.md`/`AGENTS.md` §1/§4) where this user has
|
||||
`source.yaml` — see `CLAUDE.md`/`AGENTS.md` directory contract) where this user has
|
||||
local `access: write` (see `ckb-index-external`), within that connector's
|
||||
own agent-owned generated index (`index.md`/`entities/`/`graph/`/`log.md`).
|
||||
For a connector-backed `libs/<name>/` where this user is read-only (the
|
||||
|
|
@ -80,7 +80,7 @@ check. Pages that fall below 0.3 confidence get flagged for re-review.
|
|||
|
||||
Move `retention: low` pages older than 2× their `freshness_window_days`
|
||||
into `wiki/archived/`. Never delete — always move, and log the move (see
|
||||
Rule B in `CLAUDE.md`/`AGENTS.md` §7) with a note explaining why.
|
||||
Rule B in `CLAUDE.md`/`AGENTS.md`) with a note explaining why.
|
||||
|
||||
### 5 — Supersession detection
|
||||
|
||||
|
|
@ -124,9 +124,20 @@ doesn't need an Error Book entry — this is for patterns, not incidents.
|
|||
For each `libs/<name>/source.yaml`, verify it has a non-empty `connector`
|
||||
and `location` — report only, this file is never edited by any skill. If
|
||||
an `index:` block is present, verify it has a non-empty `store` and
|
||||
`location` too. Also flag (report only) a `libs/<name>/` that ambiguously
|
||||
has both real content files and a `source.yaml` — that's a configuration
|
||||
conflict for the user to resolve, not something to guess at.
|
||||
`location` too. If `refresh_interval_days` is present, verify it's a
|
||||
positive integer. Also flag (report only) a `libs/<name>/` that
|
||||
ambiguously has both real content files and a `source.yaml` — that's a
|
||||
configuration conflict for the user to resolve, not something to guess at.
|
||||
|
||||
Report any connector-backed source whose generated index is overdue:
|
||||
newest `last_updated` in `libs/<name>/` older than its
|
||||
`refresh_interval_days` (default 30). Report it the same way whether or
|
||||
not this user has write access — a read-only user can't fix it, but
|
||||
knowing which source to chase the admin about is the actionable part. Name
|
||||
how overdue it is rather than just "stale," since a source two days past a
|
||||
7-day interval is a different situation from one six months past a 30-day
|
||||
one. Never re-index here; that's `ckb-index-external`'s job, and suggesting
|
||||
it is as far as this check goes.
|
||||
|
||||
Don't flag a missing `libs/<name>/source.local.yaml` as an issue — its
|
||||
absence is the correct, read-only default (see `ckb-index-external`), not
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
name: cbk-quiz
|
||||
name: ckb-quiz
|
||||
description: Quiz the user on knowledge captured in the wiki. Reads wiki pages, generates questions in the user's chosen format (open questions or multiple choice), runs the quiz one question at a time with score tracking and immediate feedback. Use when the user asks for a quiz, wants to test their knowledge, or says "quiz me on X".
|
||||
---
|
||||
|
||||
|
|
@ -1,15 +1,15 @@
|
|||
---
|
||||
name: ckb-retrieve
|
||||
description: Governs how a question actually gets answered from the knowledge base. An index entry — a wiki page's `tldr`, a connector-index document/entity page — is deliberately compressed so lazy-loading stays cheap; that compression also means it can be incomplete, paraphrased loosely, or stale relative to the real source. This skill makes "go verify against the source before answering" a standing step, not an optional last resort: every time a page surfaced by the index looks relevant enough to actually ground part of the answer, follow it to its underlying source material — a wiki page's own `## Sources` citations into `raw/archive/`/`outputs/`, or a connector-index page's `resource:` pointer back to the live connector item — before treating its content as settled. Use whenever answering a question or researching a topic from `wiki/`, `linked/<name>/`, or a connector-backed `libs/<name>/` — this is the retrieval half of CLAUDE.md/AGENTS.md §5 QUERY WORKFLOW, always in play, not something the user needs to name explicitly. Distinct from `ckb-onboard-me` (produces a reading-order tour, not an answer to a specific question) and from the write-side skills `ckb-ingest`/`ckb-index-external`/`ckb-lint` (build or repair the index; this skill only ever reads it, plus the sources behind it).
|
||||
description: Governs how a question actually gets answered from the knowledge base. An index entry — a wiki page's `tldr`, a connector-index document/entity page — is deliberately compressed so lazy-loading stays cheap; that compression also means it can be incomplete, paraphrased loosely, or stale relative to the real source. This skill makes "go verify against the source before answering" a standing step, not an optional last resort: every time a page surfaced by the index looks relevant enough to actually ground part of the answer, follow it to its underlying source material — a wiki page's own `## Sources` citations into `raw/archive/`/`outputs/`, or a connector-index page's `resource:` pointer back to the live connector item — before treating its content as settled. Use whenever answering a question or researching a topic from `wiki/`, `linked/<name>/`, or a connector-backed `libs/<name>/` — this is the retrieval workflow routed by CLAUDE.md/AGENTS.md, always in play, not something the user needs to name explicitly. Distinct from `ckb-onboard-me` (produces a reading-order tour, not an answer to a specific question) and from the write-side skills `ckb-ingest`/`ckb-index-external`/`ckb-lint` (build or repair the index; this skill only ever reads it, plus the sources behind it).
|
||||
---
|
||||
|
||||
# Retrieve (source-verified query) skill
|
||||
|
||||
## Purpose
|
||||
|
||||
The whole point of `tldr`/lazy-loading (CLAUDE.md/AGENTS.md §1
|
||||
"Lazy-Loading with 'Use When' Triggers", §5 "QUERY WORKFLOW") is that most
|
||||
of the wiki never has to enter context — a one-sentence summary decides
|
||||
The whole point of `tldr`/lazy-loading (CLAUDE.md/AGENTS.md index-first
|
||||
navigation and skill routing) is that most of the wiki never has to enter
|
||||
context — a one-sentence summary decides
|
||||
whether a page is worth opening at all. That's the right trade for
|
||||
*deciding relevance*. It's the wrong trade for *grounding an answer*: a
|
||||
`tldr` is a compression of whatever the page's author judged important at
|
||||
|
|
@ -39,8 +39,8 @@ prompts that should route here:
|
|||
- A direct question answerable from the wiki ("what do we know about X",
|
||||
"what's the status of Y", "who owns Z").
|
||||
- "Look up X" / "check the wiki for X" / "search for X".
|
||||
- Mid-conversation moments where CLAUDE.md/AGENTS.md §5's QUERY WORKFLOW
|
||||
applies — this skill *is* that workflow's implementation.
|
||||
- Mid-conversation moments where CLAUDE.md/AGENTS.md routes a KB question
|
||||
to retrieval — this skill *is* that workflow's implementation.
|
||||
|
||||
Do **not** use this skill for:
|
||||
- Building or refreshing an index in the first place — that's
|
||||
|
|
@ -59,10 +59,15 @@ Do **not** use this skill for:
|
|||
|
||||
### Step 1 — Read the index
|
||||
|
||||
Same cascade order as CLAUDE.md/AGENTS.md §5, first match wins:
|
||||
Same cascade order as CLAUDE.md/AGENTS.md, first match wins:
|
||||
1. `wiki/index.md` — match the question against the **Use when** column.
|
||||
2. `wiki/entities/index.md` — match against entity titles/`tldr`.
|
||||
3. If nothing local matches: each `linked/<name>/` index (alphabetical),
|
||||
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
|
||||
the rest of the cascade.
|
||||
3. `wiki/entities/index.md` — match against entity titles/`tldr`.
|
||||
4. If nothing local matches: each `linked/<name>/` index (alphabetical),
|
||||
then each connector-backed `libs/<name>/entities/index.md` — for a
|
||||
connector-backed lib this means its *generated* index (both the
|
||||
Documents and the Entities & Processes sections `ckb-index-external`
|
||||
|
|
@ -80,14 +85,94 @@ only tangential can still be hiding the exact fact needed in its body or
|
|||
its Sources. Keep the shortlist to what's plausibly relevant; this isn't
|
||||
"open everything," it's "don't stop at one."
|
||||
|
||||
If index/TLDR matching is not enough, run a local hybrid pass before
|
||||
giving up: use `rg` for exact tokens across `wiki/`, `raw/archive/`,
|
||||
`outputs/`, `raw/inbox/`, and readable upstream indexes; combine those
|
||||
hits with project-scope matches, entity/title/TLDR matches, graph
|
||||
proximity, freshness, confidence, and quality. Prefer exact text matches
|
||||
for error strings, commands, flags, filenames, hostnames, IDs, and other
|
||||
literals; prefer entity/semantic matches for paraphrased questions.
|
||||
|
||||
Sweep `raw/inbox/` even though nothing there has been ingested yet.
|
||||
Material dropped an hour ago can already hold the answer, and finding it
|
||||
there is also the clearest possible signal that an `ckb-ingest` run is
|
||||
overdue — mention that. Say plainly when an answer rests on un-ingested
|
||||
inbox material rather than on a synthesized page.
|
||||
|
||||
Keep each signal's hits as its own ranked list rather than merging them by
|
||||
eye as you go. Step 4 needs the separate orderings.
|
||||
|
||||
### Step 3 — Walk the graph for anything the shortlist missed
|
||||
|
||||
If a shortlisted page has edges in `wiki/graph/edges.json` (or a
|
||||
connector's own `graph/edges.json`), follow `depends_on`/`uses`/`caused`
|
||||
edges one hop out — the same way §5 Step 4 already directs — to catch a
|
||||
connected page the index text match alone wouldn't have surfaced.
|
||||
edges one hop out to catch a connected page the index text match alone
|
||||
wouldn't have surfaced.
|
||||
|
||||
### Step 4 — Follow every page on the shortlist to its source before answering from it
|
||||
For "who knows about X" and "who owns X" questions — both advertised in
|
||||
the trigger phrases above — the graph is the primary lookup rather than a
|
||||
fallback. Read the `has_expertise_in` and `owns` edges pointing at the
|
||||
topic entity and answer from the people or teams on the other end,
|
||||
ordered by how many distinct sources evidence each edge. Where no such
|
||||
edge exists yet, fall back to authorship evidence: who the `## Sources`
|
||||
material actually shows answering questions on that topic. Say which of
|
||||
the two grounded the answer, since an inferred expert is a weaker claim
|
||||
than a recorded one.
|
||||
|
||||
### Step 4 — Fuse the signals, dedupe, then rerank
|
||||
|
||||
Signals disagree, and none of them is trustworthy alone: an exact `rg` hit
|
||||
can sit in a page that answers a different question, and a confident TLDR
|
||||
match can be a loose paraphrase of something stale. Don't settle that by
|
||||
picking a favourite signal — fuse the ranked lists from Step 2.
|
||||
|
||||
**Fuse.** For every candidate, sum `weight / (k + rank)` across each list
|
||||
it appears in, where `rank` is its 1-based position in that list. Use
|
||||
`k = 10` and a default `weight` of 1.0. A page ranked third in three
|
||||
different lists beats one ranked first in a single list; consensus is the
|
||||
whole point.
|
||||
|
||||
`k = 10` is deliberately smaller than the `k = 60` rank fusion is usually
|
||||
quoted with. 60 is tuned for retrievers returning hundreds of candidates,
|
||||
and against the dozen-or-so a local wiki produces it flattens every score
|
||||
into near-identical values. Raise a list's weight when the question
|
||||
warrants it — for a pasted error string, command, flag, or ID, weight the
|
||||
exact-match list around 2.0, because no amount of title/TLDR similarity
|
||||
should outrank a literal match on the token the user actually pasted.
|
||||
|
||||
**Dedupe.** Collapse candidates carrying the *same claim* into one entry
|
||||
before ranking further. Step 6 actively manufactures these: a `wiki/`
|
||||
page, the `raw/archive/` file it cites, and a connector-index page whose
|
||||
`resource:` points back at that same wiki page are three hits for one
|
||||
fact. Keep whichever sits closest to the primary material and record the
|
||||
others as corroboration, not as independent evidence. Three views of one
|
||||
claim are not three sources.
|
||||
|
||||
**Rerank.** Score each surviving candidate 0–10 on how well it answers
|
||||
*the literal question asked*, not on how well it matches the query's
|
||||
vocabulary, then keep the best handful and drop the rest. This is the same
|
||||
agent making a deliberate second pass, not a separate model. The point is
|
||||
that relevance judgment happens explicitly, over the shortlist, in one
|
||||
place — rather than being folded silently into how the final answer gets
|
||||
drafted.
|
||||
|
||||
### Step 5 — Expand local context and build an evidence packet
|
||||
|
||||
For every result that survived Step 4, keep a small evidence packet with:
|
||||
- source path or connector resource
|
||||
- matched claim or short excerpt
|
||||
- source date or `last_updated`
|
||||
- freshness/confidence/quality signals, when available
|
||||
- project-scope or graph relationship hints, when relevant
|
||||
- which signals it was fused from, its rerank score, and anything it
|
||||
absorbed during dedupe — this is what Step 7 draws caveats from
|
||||
|
||||
When a match is a section, heading, or snippet inside a larger Markdown
|
||||
file, include nearby headings/paragraphs before deciding what it means.
|
||||
Avoid answering from an isolated fragment when the neighboring context
|
||||
changes the interpretation.
|
||||
|
||||
### Step 6 — Follow every page on the shortlist to its source before answering from it
|
||||
|
||||
This is the step this skill exists to enforce. For each page on the
|
||||
shortlist that will actually ground part of the answer:
|
||||
|
|
@ -120,7 +205,7 @@ deck doesn't need a full read every time, just enough (search for the
|
|||
name/topic, read the surrounding context) to confirm the point actually
|
||||
being used.
|
||||
|
||||
### Step 5 — Reconcile and answer
|
||||
### Step 7 — Reconcile and answer
|
||||
|
||||
If the source confirms the index, answer normally — but note what
|
||||
grounded it (e.g. "per the kickoff transcript cited in
|
||||
|
|
@ -134,12 +219,32 @@ exist to eventually catch, so mention it's worth a lint pass if the gap
|
|||
looks like more than a one-off, but don't rewrite the wiki page yourself
|
||||
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
|
||||
same way, even when neither is marked `superseded_by` yet. The metadata
|
||||
already exists and Step 4 already put it in front of you; the failure mode
|
||||
is answering confidently *from* a stale or contested page without passing
|
||||
that on, which leaves the reader no way to weigh it.
|
||||
|
||||
If no page anywhere is even plausibly relevant, say so — don't verify
|
||||
against a source that has nothing to do with the question just to appear
|
||||
thorough, and don't fabricate an answer either.
|
||||
thorough, and don't fabricate an answer either. For durable missing
|
||||
knowledge, add or propose a short `wiki/query-gaps.md` entry with the
|
||||
question, date, search areas tried, and the smallest missing source/page
|
||||
that would close the gap. If you edit `wiki/query-gaps.md`, update
|
||||
`wiki/log.md` immediately.
|
||||
|
||||
## Edge cases
|
||||
|
||||
- **Only one signal returned anything** — fusion is a no-op, so don't run
|
||||
the arithmetic for show. The rerank still applies (it's the check that
|
||||
the one list actually answers the question rather than merely matching
|
||||
its wording), and dedupe still applies as soon as Step 6 pulls in a
|
||||
page's own cited source.
|
||||
- **A cited source file no longer exists** (moved, renamed, or cleaned
|
||||
up) — say so plainly rather than silently falling back to the `tldr` as
|
||||
if it had been verified. Flag it as a likely `ckb-lint` finding (a
|
||||
|
|
@ -169,8 +274,9 @@ thorough, and don't fabricate an answer either.
|
|||
- **Nothing in the index is even plausibly relevant** — say the knowledge
|
||||
base has nothing on this yet, and suggest `ckb-ingest` (for new raw
|
||||
material) or `ckb-index-external` (for a connector-backed source) if
|
||||
that seems like the actual gap. Don't stretch a weak match into an
|
||||
answer just to have one.
|
||||
that seems like the actual gap. For durable gaps, record or propose a
|
||||
`wiki/query-gaps.md` entry. Don't stretch a weak match into an answer
|
||||
just to have one.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -31,7 +31,7 @@ Use this skill when the user says things like:
|
|||
- "sync the repo"
|
||||
|
||||
Do **not** use this skill for bare "Sync" or "Sync the wiki" — those trigger
|
||||
the content-level Ingestion Workflow in `CLAUDE.md`/`AGENTS.md` §3 instead
|
||||
the content-level ingest workflow routed by `CLAUDE.md`/`AGENTS.md` instead
|
||||
(processing `raw/inbox/` into `wiki/`), which this skill has nothing to do
|
||||
with.
|
||||
|
||||
|
|
|
|||
|
|
@ -36,6 +36,29 @@ the template layer, or vice versa: a KB might already have the latest
|
|||
an older (or no) schema version, or the reverse. This skill checks and
|
||||
offers to fix both, separately.
|
||||
|
||||
## Schema versioning policy
|
||||
|
||||
`wiki/index.md` is the only wiki file that carries `kb_schema_version`.
|
||||
Treat it as the version of the wiki content contract, not as a per-page
|
||||
field.
|
||||
|
||||
Use schema versions as `MAJOR.MINOR`:
|
||||
- Bump the **minor** version for backward-compatible additions: optional
|
||||
frontmatter fields, optional reserved wiki scaffolds, new optional
|
||||
subdirectories such as `wiki/projects/`, or additional optional
|
||||
index/log conventions.
|
||||
- Bump the **major** version for breaking changes: removing or renaming a
|
||||
required field, changing the meaning of an existing required field,
|
||||
removing an existing reserved filename convention, or changing cascade
|
||||
lookup semantics in a way older tooling cannot safely interpret.
|
||||
|
||||
The root `VERSION` file tracks the template/tooling release, not just the
|
||||
wiki schema. When a schema convention changes in the template repo, update
|
||||
the relevant docs/skills and `VERSION` in the same template-layer change.
|
||||
When migrating an existing KB's content layer, bump `wiki/index.md`'s
|
||||
`kb_schema_version` only after the confirmed migration has actually
|
||||
completed.
|
||||
|
||||
This is different from `ckb-sync-changes` (reconciles *this* repo's own
|
||||
commit history with *its own* `origin` remote — same content, no template
|
||||
comparison) and from `ckb-init` (bootstraps a brand-new, empty KB from the
|
||||
|
|
@ -240,7 +263,7 @@ exists, even if it looks sparse):
|
|||
its own `index.md` per the Recursive Index & Log Convention.
|
||||
|
||||
**b. Backfill frontmatter on every existing page**, per the schema in
|
||||
`AGENTS.md` §2. For each `.md` file under `wiki/` (excluding the reserved
|
||||
`AGENTS.md` page schema. For each `.md` file under `wiki/` (excluding the reserved
|
||||
`index.md`/`log.md`/`error-book.md`), check its frontmatter against the
|
||||
schema and fix only what's missing — never touch a field that's already
|
||||
present, and never alter the page's body text:
|
||||
|
|
|
|||
298
AGENTS.md
298
AGENTS.md
|
|
@ -1,209 +1,179 @@
|
|||
# SYSTEM PROMPT: CASCADE KNOWLEDGE BASE ARCHITECT
|
||||
|
||||
## ROLE & PHILOSOPHY
|
||||
You are an autonomous Knowledge Architect Agent for a **Cascade Knowledge Base**. The system is designed as a layered stack: read-only upstream knowledge bases (symlinked in `linked/` and git-managed copies in `libs/`) form the foundation, and the local mutable knowledge base overlays on top. This means knowledge flows downward through the cascade — upstream truths are preserved, while you only ever modify the local layer.
|
||||
## ROLE
|
||||
You are an autonomous Knowledge Architect Agent for a Cascade Knowledge Base.
|
||||
The local `wiki/` overlays read-only upstream knowledge in `linked/` and
|
||||
`libs/`. Local knowledge wins when the same entity exists in multiple layers.
|
||||
|
||||
If an entity exists in both the local wiki and any upstream KB, the local version takes precedence and overrides the upstream one.
|
||||
|
||||
You view directories as storage disks, context windows as RAM, and your processing loops as CPU cycles. Your sole objective is to build, maintain, and dynamically structure a comprehensive knowledge base, respecting the cascade priority rules at all times.
|
||||
|
||||
You possess full autonomy over local directory structure, file naming conventions, and cross-referencing. You must strictly adhere to the operational boundaries and file management rules detailed below.
|
||||
Keep the always-loaded rules small. Detailed workflows live in skills and
|
||||
should be loaded only when their trigger applies.
|
||||
|
||||
---
|
||||
|
||||
## 1. DIRECTORY STRUCTURE
|
||||
The root directory contains exactly seven top-level entries. You must maintain this structure flawlessly:
|
||||
## 1. DIRECTORY CONTRACT
|
||||
Maintain this root layout:
|
||||
|
||||
```
|
||||
├── libs/ # Read-only external sources, one of two kinds per <name>/ subfolder:
|
||||
│ └── <name>/ # - GIT-COPY: a git-managed clone/ZIP unpack, gitignored, fully immutable — never write here.
|
||||
│ # - CONNECTOR: identified by a user-authored source.yaml (connector + location,
|
||||
│ # optionally an index: block pointing at a shared/pre-built index to fetch from).
|
||||
│ # The agent owns and maintains a self-contained generated index alongside it —
|
||||
│ # index.md/entities/graph/log.md, mirroring wiki/'s own shape but scoped entirely
|
||||
│ # to this one connector. See §4 EXTERNAL SOURCE INDEXING. source.yaml itself stays
|
||||
│ # user-only, same as everything in a git-copy lib. Whether *this* user may rebuild
|
||||
│ # it (vs. only read a fetched/published copy) is a local, per-user, gitignored
|
||||
│ # source.local.yaml — read-only by default.
|
||||
├── linked/ # SYMLINKS ONLY. Each entry is a symbolic link to another KB root (read-only upstream source of truth).
|
||||
│ └── <name>/ # Individual upstream knowledge base (immutable — never write here).
|
||||
├── outputs/ # MANAGED BY AGENT. Generated artifacts, exports, compiled files produced from the wiki.
|
||||
│ # On-demand workflows beyond Ingest/Lint may be defined as Claude Code Skills under
|
||||
│ # `.claude/skills/` — check there before assuming a capability doesn't exist.
|
||||
├── raw/ # WRITTEN BY USER ONLY. Raw files, scratchpad notes, URLs, links.txt.
|
||||
│ ├── inbox/ # Drop zone: unprocessed material the agent cleans on ingest.
|
||||
│ └── archive/ # AGENT MAINTAINED. Ingested raw material, filed by ingestion date.
|
||||
│ └── <YYYY-MM-DD>/ # One folder per ingestion date; holds every raw/inbox file processed that day.
|
||||
├── tmp/ # MANAGED BY AGENT. Temporary files, caches, intermediate processing artifacts (gitignored).
|
||||
├── wiki/ # MANAGED BY AGENT. The local, mutable, structured markdown wiki. Overlays linked/ and libs/.
|
||||
│ ├── index.md # Entry point / routing table with "Use when" triggers. Carries kb_schema_version.
|
||||
│ ├── overview.md # High-level map of the knowledge base.
|
||||
│ ├── log.md # AGENT LOG. Root rollup tracking wiki-level modifications (see Recursive Index & Log Convention).
|
||||
│ ├── error-book.md # AGENT MAINTAINED. Records compilation errors and derived constraints.
|
||||
│ ├── entities/ # AGENT POPULATED. Typed entity pages (people, projects, concepts, libraries). Has its own index.md.
|
||||
│ └── graph/ # AGENT MAINTAINED. Edge lists and relationship data for the knowledge graph. Has its own index.md.
|
||||
└── workload/ # MANAGED BY AGENT. Summaries of discussions and decisions.
|
||||
├── libs/ # Read-only external sources:
|
||||
│ └── <name>/ # - git-copy clone/ZIP: immutable, never write here
|
||||
│ # - connector source: has user-authored source.yaml
|
||||
│ # and an agent-owned generated index
|
||||
├── linked/ # Symlinks to other KB roots, read-only
|
||||
├── outputs/ # Agent-generated artifacts and exports
|
||||
├── raw/ # User-provided source material
|
||||
│ ├── inbox/ # Drop zone for unprocessed material
|
||||
│ └── archive/ # Agent-filed processed inputs by date
|
||||
├── tmp/ # Agent temporary files and caches
|
||||
├── wiki/ # Local mutable structured wiki
|
||||
│ ├── index.md # Routing table with kb_schema_version
|
||||
│ ├── overview.md
|
||||
│ ├── log.md
|
||||
│ ├── error-book.md
|
||||
│ ├── query-gaps.md
|
||||
│ ├── projects/
|
||||
│ ├── entities/
|
||||
│ └── graph/
|
||||
└── workload/ # Session summaries and decisions
|
||||
└── YYYY-MM-DD_summary.md
|
||||
```
|
||||
|
||||
### Cascade Lookup Priority
|
||||
When searching for any entity, concept, or file, use the following cascade (first match wins):
|
||||
### Cascade Priority
|
||||
When searching for any entity, concept, or file, use first match wins:
|
||||
|
||||
1. **Local wiki/** — highest priority; agent-written content overlays everything below.
|
||||
2. **linked/\<name\>/** — read-only upstream KBs mounted as symlinks, searched in alphabetical order.
|
||||
3. **libs/\<name\>/** — read-only external sources, searched in alphabetical order. For a git-copy lib this is its cloned files; for a connector-backed lib (one with a `source.yaml`) this layer's content *is* the agent-generated index (`index.md`/`entities/`/`graph/`) built by the `ckb-index-external` skill, not raw copied files — see §4.
|
||||
4. If no match is found anywhere, treat the entity as unknown.
|
||||
1. `wiki/` - local mutable layer.
|
||||
2. `linked/<name>/` - read-only upstream KBs, alphabetical.
|
||||
3. `libs/<name>/` - read-only external sources, alphabetical. For a
|
||||
connector-backed lib, this means its generated index, not the live
|
||||
connector itself.
|
||||
4. If no match is found, treat the entity as unknown.
|
||||
|
||||
You must **never** create, modify, move, or delete any file or directory inside `linked/` or a git-copy `libs/<name>/`. The one exception is a connector-backed `libs/<name>/`'s own generated index, which the agent owns and maintains exactly like `wiki/` — see Rule A in §7.
|
||||
Never write inside `linked/` or a git-copy `libs/<name>/`.
|
||||
|
||||
Connector-backed `libs/<name>/` folders are the exception: if a folder has
|
||||
`source.yaml`, the agent may maintain that folder's generated
|
||||
`index.md`/`entities/`/`graph/`/`log.md` through `ckb-index-external`.
|
||||
The agent must never edit `source.yaml`. Rebuilding from the live connector
|
||||
requires local `libs/<name>/source.local.yaml` with `access: write`;
|
||||
absence means read-only.
|
||||
|
||||
### Index-First Navigation
|
||||
When searching for information, always start by looking for `index.md` files.
|
||||
Read the index to discover what pages and subdirectories are available before
|
||||
drilling into individual files. Scan `index.md` across all layers:
|
||||
For KB questions, start at `wiki/index.md`, then matching subdirectory
|
||||
indexes. Only drill into pages that match the task. If local indexes do not
|
||||
answer, continue through `linked/` and `libs/` indexes in cascade order.
|
||||
|
||||
1. **wiki/** — scan `wiki/index.md`, then recursively check any subdirectory `wiki/<topic>/index.md`.
|
||||
2. **linked/\<name\>/** — for each linked upstream KB, scan its root `index.md` and subdirectory indexes.
|
||||
3. **libs/\<name\>/** — same pattern: root index first, then subdirectory indexes as needed.
|
||||
|
||||
This avoids blind filesystem scans and uses the index as a curated table of contents — exactly as Karpathy's original pattern intended.
|
||||
|
||||
### Recursive Index & Log Convention
|
||||
Index-First Navigation only works if subdirectory indexes actually exist. Maintain them as follows:
|
||||
|
||||
- Every `wiki/` subdirectory that groups multiple pages (`entities/`, `graph/`, and any future topic folder) must contain its own `index.md`. It carries no frontmatter and is a flat bullet list of links, each with a one-line description mirroring the linked page's `tldr` — plus a link to any nested subdirectory.
|
||||
- A subdirectory may also keep its own `log.md` once it has enough independent change history to warrant one (a judgment call — typically once it holds several pages or changes on its own cadence, separate from the rest of the wiki). Entries follow the same reverse-chronological format as Rule B.
|
||||
- The root `wiki/log.md` stays the top-level rollup: it records changes made directly under `wiki/` (`index.md`, `overview.md`, `error-book.md`, directory-creation events) plus one pointer line whenever a subdirectory log absorbs a change, e.g. `- See wiki/entities/log.md for entity-page changes on this date.` Each change gets exactly one home log — never record the same change in both.
|
||||
- The same convention applies verbatim inside a connector-backed `libs/<name>/` (§4) — its generated `index.md`/`entities/index.md`/`graph/index.md`/`log.md` mirror this pattern exactly, scoped entirely to that one connector. Its `log.md` is independent of `wiki/log.md` — never record a connector-indexing change in both.
|
||||
|
||||
### Lazy-Loading with "Use When" Triggers
|
||||
The `wiki/index.md` is a routing table. Each entry has a **Use when** column
|
||||
that lists trigger keywords. Before loading any page:
|
||||
|
||||
1. Read `wiki/index.md` (stays in context — it is small).
|
||||
2. Match the current task's keywords against the **Use when** entries.
|
||||
3. Only load the matching page(s). Do not load every page.
|
||||
4. If a page has a `tldr:` frontmatter field, read that first. If it answers the query, skip the body.
|
||||
|
||||
This keeps context lean: ~3–4 pages loaded instead of all pages.
|
||||
Every `wiki/` subdirectory that groups pages, including `projects/`,
|
||||
`entities/`, and `graph/`, must have its own `index.md`. Use the same
|
||||
convention inside connector-backed libs for their generated index.
|
||||
|
||||
---
|
||||
|
||||
## 2. PAGE FRONTMATTER SCHEMA
|
||||
|
||||
Every wiki page must use YAML frontmatter. `type` is required; the rest are optional:
|
||||
## 2. PAGE SCHEMA
|
||||
Every non-reserved wiki page uses YAML frontmatter. `type` is required; the
|
||||
other fields are optional but preferred when meaningful:
|
||||
|
||||
```yaml
|
||||
---
|
||||
type: concept # REQUIRED. Open string for the entity/content kind (e.g. person, project, concept, library, decision, playbook). Unregistered — new values are always valid; readers must tolerate unrecognized types.
|
||||
resource: https://... # Optional. Canonical URI to the authoritative external source this page describes (a linked/<name>/... or libs/<name>/... path, ticket, repo, doc, dataset). Keeps "what the wiki says about it" separate from "where the real thing lives."
|
||||
type: concept
|
||||
resource: https://...
|
||||
tldr: One-sentence summary optimised for LLM reading
|
||||
confidence: 0.0–1.0 # How many/corroborated sources support this
|
||||
quality: 0.0–1.0 # Self-evaluation: well-structured, consistent, cited
|
||||
confidence: 0.0-1.0
|
||||
quality: 0.0-1.0
|
||||
supersedes: path/to/older/page.md
|
||||
superseded_by: path/to/newer/page.md
|
||||
last_updated: YYYY-MM-DD
|
||||
freshness_window_days: 90 # Days before considered potentially stale
|
||||
retention: high|medium|low # How aggressively to deprioritize when old
|
||||
freshness_window_days: 90
|
||||
retention: high|medium|low
|
||||
---
|
||||
```
|
||||
|
||||
- **`type`** — required on every page. Set once on write and rarely changed; it's the first thing lint checks for conformance, and it's how pages in `entities/` get grouped without depending on directory naming alone.
|
||||
- **`resource`** — set when the page describes something with a stable external address. Omit for pages that are pure synthesis (e.g. an overview or a decision writeup with no single external source).
|
||||
- **`tldr`** — generated on write. If the TLDR alone answers a query, the body is never loaded.
|
||||
- **`confidence`** — set on write based on source corroboration. Decays with time unless reinforced by new sources.
|
||||
- **`quality`** — self-score on write. Below 0.7 → flag for review.
|
||||
- **`supersedes` / `superseded_by`** — when new info contradicts or updates an old page, link them. Old pages are preserved but marked stale.
|
||||
- **`last_updated`** — set automatically on every write or edit.
|
||||
- **`freshness_window_days`** — pages older than this window are flagged stale during lint.
|
||||
- **`retention`** — `low` pages may be archived or deprioritized after the freshness window expires.
|
||||
|
||||
### Schema Versioning
|
||||
`wiki/index.md` (only) carries an additional frontmatter field, `kb_schema_version` (e.g. `"1.1"`), declaring which revision of this schema the wiki was authored against. Bump the minor version when adding an optional field (backward-compatible); bump the major version when changing or removing a required field or reserved filename convention (breaking). Individual pages do not carry this field — it is a bundle-level declaration, not a per-page one.
|
||||
`wiki/index.md` alone also carries `kb_schema_version`, currently `"1.3"`.
|
||||
Detailed schema migration and version-bump policy belongs in
|
||||
`ckb-upgrade`.
|
||||
|
||||
---
|
||||
|
||||
## 3. INGESTION WORKFLOW (TRIGGERED ON DEMAND)
|
||||
## 3. SKILL ROUTING
|
||||
Use skills for procedural work instead of keeping full workflows in this
|
||||
file.
|
||||
|
||||
When the user says "Ingest", "Sync the wiki", or "Update the Wiki" (for syncing this repo's own git history with its remote, see the ckb-sync-changes skill under `.claude/skills/` instead), run the **ckb-ingest** Claude Code Skill — see `.agents/skills/ckb-ingest/SKILL.md` — rather than following inline steps here, so the full procedure (process inbox, consult cascade, extract entities, synthesize pages, cross-link, update index/log, then remind to review and sync) only loads into context when actually invoked.
|
||||
| User intent | Skill |
|
||||
|---|---|
|
||||
| Answer or research a KB question | `ckb-retrieve` |
|
||||
| Ingest raw material into `wiki/` | `ckb-ingest` |
|
||||
| Index connector-backed `libs/` sources | `ckb-index-external` |
|
||||
| Health-check or repair wiki/index structure | `ckb-lint` |
|
||||
| Sync this repo with `origin` | `ckb-sync-changes` |
|
||||
| Upgrade template or wiki schema | `ckb-upgrade` |
|
||||
| Bootstrap a new empty KB | `ckb-init` |
|
||||
| Export OKF or Starlight artifacts | `ckb-export-okf`, `ckb-export-starlight` |
|
||||
| Generate a project overview | `ckb-project-summary` |
|
||||
| Teach, quiz, or onboard from the wiki | `ckb-teach-me`, `cbk-quiz`, `ckb-onboard-me` |
|
||||
|
||||
Short routing rules:
|
||||
|
||||
- For questions, use `ckb-retrieve`; it owns project scopes, hybrid local
|
||||
search, rank fusion across signals, dedupe/rerank, expertise and
|
||||
ownership lookups, evidence packets, source verification, answer
|
||||
caveats, and query-gap capture.
|
||||
- For "Ingest", "Sync the wiki", or "Update the wiki", use `ckb-ingest`.
|
||||
- For "Index external sources", "index libs", or "refresh the external
|
||||
index", use `ckb-index-external`.
|
||||
- For "Lint" or "health-check the wiki", use `ckb-lint`.
|
||||
- For "sync changes", "sync with origin", or "push and pull my changes",
|
||||
use `ckb-sync-changes`, not ingest.
|
||||
- For "upgrade the wiki" or "check for a newer template version", use
|
||||
`ckb-upgrade`.
|
||||
|
||||
---
|
||||
|
||||
## 4. EXTERNAL SOURCE INDEXING (TRIGGERED ON DEMAND)
|
||||
## 4. NON-NEGOTIABLE RULES
|
||||
|
||||
When the user says "Index external sources" (or "index libs", "refresh the external index"), run the **ckb-index-external** Claude Code Skill — see `.agents/skills/ckb-index-external/SKILL.md` — rather than following inline steps here, so the full procedure only loads into context when actually invoked. It walks every connector-backed `libs/<name>/` (one with a `source.yaml` — see §1), fetches a shared/pre-built index if `source.yaml` declares one (`index.store`/`index.location` — git or a shared resource), and — only if this user has local `access: write` in `libs/<name>/source.local.yaml` (read-only by default) — resolves the declared connector to whatever live tool is available this session and builds/refreshes that connector's own self-contained `index.md`/`entities/`/`graph/`/`log.md`, publishing it back to the shared store if one is configured. This never touches `wiki/`, never touches `source.yaml`, and never touches a git-copy lib.
|
||||
### Rule A: Immutability
|
||||
Do not modify `linked/` or git-copy `libs/<name>/`. To correct upstream
|
||||
knowledge, write a local override in `wiki/`.
|
||||
|
||||
For connector-backed `libs/<name>/`, only generated index files are
|
||||
agent-owned. `source.yaml` is user-owned. `source.local.yaml` may be created
|
||||
or edited only when the user explicitly asks to become or stop being that
|
||||
source's admin.
|
||||
|
||||
### Rule B: Wiki Change Log
|
||||
Every create, update, move, or delete inside `wiki/` must be logged
|
||||
immediately in `wiki/log.md` before proceeding.
|
||||
|
||||
Use reverse chronological order and this format:
|
||||
|
||||
```markdown
|
||||
## [YYYY-MM-DD HH:MM] - [ACTION TYPE]
|
||||
- **File Affected:** `wiki/path/to/file.md`
|
||||
- **Description:** Brief summary of what knowledge or structure changed.
|
||||
- **Source:** Chat conversation, raw file, URL, or skill name.
|
||||
---
|
||||
```
|
||||
|
||||
## 5. QUERY WORKFLOW
|
||||
### Rule C: Links
|
||||
For upstream references, link with project-root-relative paths such as
|
||||
`linked/<name>/...` or `libs/<name>/...`.
|
||||
|
||||
When answering a question or researching a topic:
|
||||
For local wiki references, prefer project-root-absolute paths such as
|
||||
`/wiki/entities/foo.md`. Use both `[[Wikilinks]]` and standard Markdown
|
||||
links on cross-references whenever practical.
|
||||
|
||||
1. **Read the index** — `wiki/index.md` first. Match query keywords against **Use when** triggers.
|
||||
2. **Read TLDRs** — for any matched page, read its `tldr:` frontmatter first. If it answers the query, stop.
|
||||
3. **Load full pages** — only if the TLDR was insufficient.
|
||||
4. **Walk the graph** — if the entity has relationships in `wiki/graph/edges.json`, follow them to discover connected pages (e.g. "what depends on X?").
|
||||
5. **Fall back upstream** — if the local wiki has no match, check `linked/<name>/` indexes, then `libs/<name>/` indexes (for a connector-backed lib, that means its generated `entities/`/`index.md`, not the live source directly — if it's not there yet, suggest running "index external sources" rather than fetching the live source ad hoc). Apply cascade priority throughout.
|
||||
### Rule D: Session Summary
|
||||
After every conversational turn where you read, write, search, ingest, lint,
|
||||
or answer, append a short note to `workload/YYYY-MM-DD_summary.md`.
|
||||
|
||||
---
|
||||
### Rule E: Session Start and End
|
||||
At session start, read `wiki/index.md`, the latest `workload/` summary, and
|
||||
run a cheap `git status` check. If there are uncommitted changes or the
|
||||
branch is ahead/behind its remote-tracking branch, tell the user and suggest
|
||||
`ckb-sync-changes`.
|
||||
|
||||
## 6. MAINTENANCE WORKFLOW (LINT)
|
||||
At session end, update `workload/` and repeat the same unsynchronized-change
|
||||
check. Do not fetch or push unless the user asks.
|
||||
|
||||
Periodically (or when asked to "Lint"), run the **ckb-lint** Claude Code Skill — see `.agents/skills/ckb-lint/SKILL.md` — rather than following inline steps here, so the full checklist (conformance, freshness, confidence decay, retention sweep, supersession detection, orphan detection, graph consistency, index/log consistency, error-book entries, auto-fix vs. report, then a reminder to review and sync) only loads into context when actually invoked.
|
||||
|
||||
---
|
||||
|
||||
## 7. COMPLIANCE & LOGGING RULES (NON-NEGOTIABLE)
|
||||
|
||||
### Rule A: Immutability of linked/ and libs/
|
||||
You must **never** write, modify, move, or delete any file or directory inside `linked/` or a git-copy `libs/<name>/`. These are read-only upstream sources of truth managed exclusively by the User. If information in them is outdated or incorrect, you may override it by writing a corrected version in the local `wiki/`. The local version will take priority in the cascade lookup.
|
||||
|
||||
**Exception — connector-backed `libs/<name>/`:** identified by the presence of a `source.yaml` (see §1). Its `source.yaml` is user-authored and stays just as untouchable as anything else here. But everything else in that folder — `index.md`, `entities/`, `graph/`, `log.md` — is a generated index the agent owns and maintains exactly as it would `wiki/`, built and refreshed by the `ckb-index-external` skill (§4). This exception applies only to a `libs/<name>/` that has a `source.yaml`; a plain git-copy lib has no such carve-out.
|
||||
|
||||
Within that exception, two things the agent may always do regardless of this user's access level: fetch a shared/pre-built index down into `libs/<name>/` if `source.yaml` declares one, and read whatever's cached there. Actually rebuilding it from the live connector — and publishing that rebuild back to a shared store — is gated by a separate, local, per-user `libs/<name>/source.local.yaml` (never committed, never synced, never read by anyone else): `access: write` opts this user in; its absence (the default) means read-only. Unlike `source.yaml`, the agent *may* create or edit `source.local.yaml` — but only when this user explicitly asks to become (or stop being) that source's admin, never on its own initiative.
|
||||
|
||||
### Rule B: The Wiki Change Log (`wiki/log.md`)
|
||||
Every single time you create, modify, move, or delete a file within the `wiki/` directory, you must immediately document it in `wiki/log.md` before proceeding.
|
||||
- **Ordering:** The most recent action **must always be at the very top** of the file (chrono-reverse order).
|
||||
- **Format Per Entry:**
|
||||
```markdown
|
||||
## [YYYY-MM-DD HH:MM] - [ACTION TYPE: e.g., CREATE/UPDATE/DELETE]
|
||||
- **File Affected:** `wiki/path/to/file.md`
|
||||
- **Description:** Brief summary of what knowledge was added or altered.
|
||||
- **Source:** [e.g., Chat conversation, raw/notes.txt, URL]
|
||||
---
|
||||
```
|
||||
|
||||
### Rule C: Cascade-Anchored References with Dual-Linking
|
||||
When cross-referencing an entity that exists in an upstream KB, write the link using the relative path from the project root (e.g., `linked/<name>/wiki/concepts/foo.md` or `libs/<name>/docs/bar.md`). This preserves the cascade structure and makes it clear which layer the reference belongs to.
|
||||
|
||||
For references between pages within `wiki/` itself, prefer project-root-absolute paths (e.g. `/wiki/entities/foo.md`) over relative paths (`../entities/foo.md`). Absolute paths keep resolving correctly if either page is later moved during a lint or reorganization pass; relative paths silently break.
|
||||
|
||||
Use **both** `[[Wikilinks]]` (Obsidian-compatible) and standard `[markdown](path.md)` links on every cross-reference. This ensures the wiki works in Obsidian graph view, GitHub rendering, and CLI tools.
|
||||
|
||||
### Rule D: Session Summary (`workload/`)
|
||||
After every conversational turn where you take any action (read, write, search, ingest, lint, answer a question), update the summary file in `workload/`. If today's file already exists, append new notes to it; otherwise create it.
|
||||
- **Naming:** `workload/YYYY-MM-DD_summary.md`
|
||||
- **Content:** Brief record of what was discussed, what actions were taken, and what decisions were made during this exchange.
|
||||
- **Purpose:** Provides continuity between sessions and a browsable history of how the knowledge base evolved.
|
||||
|
||||
### Rule E: Automation Hooks
|
||||
Follow these event-driven behaviors:
|
||||
|
||||
- **On new source in inbox** — on the next ingest, auto-process: extract entities, update graph, update index, write to log.
|
||||
- **On new or changed `libs/<name>/source.yaml`** — on the next "index external sources" run, process it: resolve the connector, enumerate documents, build/refresh that connector's own `index.md`/`entities/`/`graph/`/`log.md`.
|
||||
- **On session start** — read `wiki/index.md` and the latest `workload/` summary to load relevant context. Also check for unsynchronized changes (`git status` — uncommitted local changes, or the local branch ahead/behind its remote-tracking ref) and, if any are found, tell the user and suggest running the `ckb-sync-changes` skill before proceeding. This is a cheap, read-only check (no `git fetch`) — a heads-up, not a substitute for actually running that skill.
|
||||
- **On session end** — compress the session into observations and file insights into `workload/`. Also re-run the same unsynchronized-changes check as at session start — the session's own work may have just created new local changes — and suggest `ckb-sync-changes` if anything is now pending.
|
||||
- **On query** — if the answer has lasting value, file it back into `wiki/` as a new page or update to an existing one.
|
||||
- **On memory write** — check for contradictions with existing wiki content. If found, apply supersession (link old → new) and log it.
|
||||
- **On schedule** — periodic lint, consolidation, retention decay, freshness check.
|
||||
|
||||
### Rule F: Demand-Driven Context (DDC)
|
||||
Use agent failures as the signal for what knowledge to add:
|
||||
|
||||
1. When you cannot answer a question or complete a task, identify the missing knowledge.
|
||||
2. Propose a minimal entity or page to fill the gap.
|
||||
3. The user approves or provides the source material.
|
||||
4. Add it to `raw/inbox/` or describe it in chat.
|
||||
5. Next ingest cycle incorporates it.
|
||||
|
||||
This keeps the wiki lean — you only add what is needed, not what is merely available.
|
||||
### Rule F: Demand-Driven Context
|
||||
When the KB cannot answer something, identify the missing knowledge and
|
||||
propose the smallest source or page that would close the gap. `ckb-retrieve`
|
||||
owns durable query-gap entries; `ckb-ingest` owns turning approved/source
|
||||
material into wiki pages.
|
||||
|
|
|
|||
84
MANUAL.md
84
MANUAL.md
|
|
@ -105,6 +105,13 @@ which stay entirely read-only. There are three ways to mount one:
|
|||
committed, never seen by anyone else). This is deliberate: it lets one
|
||||
or two people maintain a source for the whole team instead of everyone
|
||||
redundantly re-scanning it.
|
||||
- **You can set how often it should be refreshed.** Add an optional
|
||||
`refresh_interval_days: 7` to `source.yaml` (it defaults to 30). A
|
||||
folder that churns daily wants a shorter window than a quarterly
|
||||
archive nobody touches. Both "index external sources" and "Lint" then
|
||||
tell you when a source is overdue and by how much — which matters most
|
||||
if you're read-only for it, since knowing *which* source has gone
|
||||
stale is what lets you go ask the person who maintains it.
|
||||
|
||||
Either way, once it's mounted, just ask questions normally — the agent
|
||||
checks your local `wiki/` first, then walks `linked/`, then `libs/`, and
|
||||
|
|
@ -143,6 +150,17 @@ Example:
|
|||
> reminding you to review the result and say "sync changes" once you're
|
||||
> happy with it.
|
||||
|
||||
For a long transcript, the agent doesn't just write one summary page. It
|
||||
pulls out the searchable question, the summary, the resolution, the systems
|
||||
and people involved — and promotes individual passages to their own
|
||||
findable sections when they'd otherwise be lost inside a summary. That last
|
||||
part has a deliberate bar: a passage has to contain a genuinely specific
|
||||
term (a flag, an error string, a clause, a version), run to a couple of
|
||||
sentences at least, and be corroborated by something later in the material.
|
||||
Otherwise it stays folded into the summary. Without that bar every
|
||||
paragraph looks quotable and the wiki page ends up being the transcript
|
||||
again, which defeats the point of ingesting it.
|
||||
|
||||
If `raw/inbox/` is empty, the agent scans `raw/` directly instead (still
|
||||
skipping `raw/archive/`, which is already-processed history).
|
||||
|
||||
|
|
@ -172,6 +190,21 @@ ingest incorporates it. This keeps the wiki demand-driven: it grows around
|
|||
what you actually ask, not everything that could theoretically be written
|
||||
down.
|
||||
|
||||
Durable misses can also be tracked in `wiki/query-gaps.md`. A good gap
|
||||
entry is tiny: the question, where the agent looked, and the smallest
|
||||
source or page that would make the answer available next time.
|
||||
|
||||
### D. Create a local project scope
|
||||
|
||||
When a topic, client, system, or initiative comes up often, ask:
|
||||
|
||||
> "Create a project scope for payments integration."
|
||||
|
||||
The agent creates or updates a plain Markdown page under `wiki/projects/`
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## 3. Keeping it tidy
|
||||
|
|
@ -191,6 +224,9 @@ This runs a health check across the whole wiki:
|
|||
- orphaned pages (nothing links to them) get backlinked or archived
|
||||
- broken graph edges get fixed or removed
|
||||
- missing/duplicate index and log entries get corrected
|
||||
- connector-backed sources whose index is overdue for a refresh get
|
||||
flagged, with how overdue they are — useful even if you're read-only for
|
||||
that source, since it tells you who to chase
|
||||
- recurring systemic issues get written into `wiki/error-book.md`
|
||||
|
||||
It fixes what it safely can on its own, and reports the rest for you to
|
||||
|
|
@ -346,11 +382,43 @@ Just ask, in plain language:
|
|||
|
||||
> "What do we know about the Q3 migration risk?"
|
||||
|
||||
The agent reads `wiki/index.md` first to find relevant pages, checks their
|
||||
one-line `tldr` before loading the full page, walks the knowledge graph for
|
||||
connected facts, and falls back to `linked/`/`libs/` if the local wiki has
|
||||
nothing. You get an answer grounded in what's actually written down, not a
|
||||
guess.
|
||||
The agent reads `wiki/index.md` first to find relevant pages. If a matching
|
||||
project scope exists under `wiki/projects/`, it searches that scope first.
|
||||
Then it checks one-line `tldr` fields, runs exact local search for literal
|
||||
tokens when needed, expands context around matching sections, walks the
|
||||
knowledge graph for connected facts, and falls back to `linked/`/`libs/` if
|
||||
the local wiki has nothing. You get an answer grounded in what's actually
|
||||
written down, not a guess.
|
||||
|
||||
Two things about that worth knowing as a user:
|
||||
|
||||
- **It searches `raw/inbox/` too.** Something you dropped in this morning
|
||||
and haven't ingested yet can still answer your question. The agent will
|
||||
tell you when an answer came from un-ingested material, which doubles as
|
||||
a nudge that "Ingest" is overdue.
|
||||
- **Answers carry their own caveats.** If the page behind an answer is past
|
||||
its freshness window, scored low on confidence, or was read from a cached
|
||||
connector index instead of a live check, the answer says so next to the
|
||||
claim. If two pages disagree and neither has been marked superseded yet,
|
||||
you'll hear about that too. The point is that you never have to go read
|
||||
the frontmatter yourself to know how much to trust what you just got.
|
||||
|
||||
### Ask who knows something
|
||||
|
||||
> "Who knows about the checkpoint restore path?" / "Who owns the billing
|
||||
> service?"
|
||||
|
||||
These are answered from the knowledge graph directly rather than by
|
||||
keyword-searching for names. Ingest records an expertise or ownership edge
|
||||
when the source material actually shows someone answering questions on a
|
||||
topic or holding declared responsibility for it — not from having attended
|
||||
a meeting or from a job title. If nobody has a recorded edge yet, the agent
|
||||
falls back to who the archived sources show answering that kind of question
|
||||
and tells you it's inferring rather than reporting.
|
||||
|
||||
When there is still no answer, the agent should tell you what is missing
|
||||
and either add/propose a short entry in `wiki/query-gaps.md` or suggest the
|
||||
smallest source to drop into `raw/inbox/`.
|
||||
|
||||
### Learn from the wiki
|
||||
|
||||
|
|
@ -450,6 +518,7 @@ Example:
|
|||
> connector: sharepoint
|
||||
> location: "https://contoso.sharepoint.com/sites/Finance/Shared Documents/Reports"
|
||||
> description: "Finance team's shared reports folder"
|
||||
> refresh_interval_days: 7
|
||||
> ```
|
||||
> *then say "Index external sources."*
|
||||
>
|
||||
|
|
@ -533,7 +602,7 @@ graph stay in sync with what you changed.
|
|||
| `raw/archive/<date>/` | Agent | Auto-filed copy of what you dropped in `raw/inbox/`, organised by ingestion date. Don't hand-file here — let Ingest do it, so the date and pairing with the log entry stay accurate. |
|
||||
| `linked/<name>/` | **You** (you create the symlink) | Points at another KB's real files, which live and get edited *in that other repo* — never here. The agent must never write inside `linked/`. |
|
||||
| `libs/<name>/` (git-copy, no `source.yaml`) | **You** (you `git clone`) | A frozen copy of an external KB. Update it by re-pulling that repo yourself, not by hand-editing files here. The agent must never write inside it. |
|
||||
| `libs/<name>/source.yaml` (connector) | **You, only** | Declares the connector, location, and optionally where a shared/pre-built index lives (`index:`). The agent reads it but never writes it — same as anything else upstream. |
|
||||
| `libs/<name>/source.yaml` (connector) | **You, only** | Declares the connector, location, optionally how often it should be refreshed (`refresh_interval_days:`), and optionally where a shared/pre-built index lives (`index:`). The agent reads it but never writes it — same as anything else upstream. |
|
||||
| `libs/<name>/source.local.yaml` (connector) | **You** (or the agent, only when you explicitly ask to become/stop being that source's admin) | Per-person, per-machine `access: write`/`read` setting — never committed, never seen by anyone else. Absent = read-only, the default. |
|
||||
| `libs/<name>/{index.md,entities/,graph/,log.md}` (connector) | Agent-generated, **you can freely edit** | The agent's own index of that one connector's source, built/refreshed by "Index external sources" — but only if you have `access: write` locally; read-only users just get a fetched copy. Structurally the same deal as the main `wiki/` row below — feel free to correct an entry by hand, then run "Lint" (it now also checks connector-backed indexes, respecting the same read/write split). Scoped entirely to that connector; never blended into `wiki/`. |
|
||||
| `wiki/` (pages, `index.md`, `overview.md`, `log.md`, `error-book.md`, `entities/`, `graph/`) | Agent-generated, **you can freely edit** | This is the one place the agent both writes and expects you might too. Feel free to correct a page by hand — just keep the frontmatter fields intact (or update `last_updated`), and run Lint afterward if you touched something the index/graph/log reference. |
|
||||
|
|
@ -563,4 +632,5 @@ graph stay in sync with what you changed.
|
|||
| "Export the wiki to Starlight" | Human-readable docs site at `outputs/starlight/` | `ckb-export-starlight` |
|
||||
| "Upgrade the wiki" / "Check for a newer template version" | Checks template + wiki schema versions against the canonical repo, upgrades what you accept | `ckb-upgrade` |
|
||||
| "Index external sources" / "Index libs" | Builds/refreshes a self-contained index for each connector-backed `libs/<name>/` | `ckb-index-external` |
|
||||
| Just ask a question | Answers from the wiki, using the index/TLDR/graph cascade | — (core query workflow) |
|
||||
| Just ask a question | Answers from the wiki, using the index/TLDR/graph cascade, with caveats when a source is stale or contested | `ckb-retrieve` |
|
||||
| "Who knows about X" / "Who owns X" | Answers from expertise/ownership edges in the graph | `ckb-retrieve` |
|
||||
|
|
|
|||
88
MANUAL.pl.md
88
MANUAL.pl.md
|
|
@ -110,6 +110,14 @@ podpięcia:
|
|||
niewidoczny dla współpracowników). To celowe: pozwala jednej lub dwóm
|
||||
osobom utrzymywać źródło dla całego zespołu, zamiast żeby każdy
|
||||
redundantnie je skanował.
|
||||
- **Możesz ustawić, jak często ma być odświeżane.** Dodaj opcjonalne
|
||||
`refresh_interval_days: 7` do `source.yaml` (domyślnie 30). Folder
|
||||
zmieniający się codziennie potrzebuje krótszego okna niż kwartalne
|
||||
archiwum, którego nikt nie tyka. Wtedy zarówno „index external
|
||||
sources", jak i „Lint" powiedzą ci, kiedy źródło jest zaległe i o ile —
|
||||
co ma największe znaczenie, jeśli masz do niego dostęp tylko do
|
||||
odczytu, bo wiedza o tym, *które* źródło się przedawniło, pozwala
|
||||
zapytać osobę, która je utrzymuje.
|
||||
|
||||
Niezależnie od sposobu, po podpięciu wystarczy normalnie zadawać pytania —
|
||||
agent sprawdza najpierw twoją lokalną `wiki/`, potem przechodzi przez
|
||||
|
|
@ -149,6 +157,17 @@ Przykład:
|
|||
> `raw/archive/2026-07-10/`. Na koniec przypomina o przejrzeniu wyniku i
|
||||
> powiedzeniu „sync changes”, gdy będziesz zadowolony.
|
||||
|
||||
Przy długim transkrypcie agent nie pisze po prostu jednej strony
|
||||
podsumowania. Wyciąga wyszukiwalne pytanie, podsumowanie, rozwiązanie oraz
|
||||
zaangażowane systemy i osoby — a pojedyncze fragmenty awansuje do własnych
|
||||
znajdowalnych sekcji, jeśli inaczej przepadłyby wewnątrz podsumowania. Ta
|
||||
ostatnia część ma celowy próg: fragment musi zawierać naprawdę konkretny
|
||||
termin (flagę, komunikat błędu, klauzulę, numer wersji), mieć co najmniej
|
||||
kilka zdań i być potwierdzony przez coś dalej w materiale. W przeciwnym razie
|
||||
zostaje wtopiony w podsumowanie. Bez tego progu każdy akapit wygląda na wart
|
||||
zacytowania, a strona wiki znów staje się transkryptem — co przekreśla sens
|
||||
jego zingestowania.
|
||||
|
||||
Jeśli `raw/inbox/` jest puste, agent skanuje bezpośrednio `raw/` (nadal
|
||||
pomijając `raw/archive/`, które zawiera już przetworzoną historię).
|
||||
|
||||
|
|
@ -179,6 +198,21 @@ ingest to wchłonie. Dzięki temu wiki pozostaje napędzana zapotrzebowaniem:
|
|||
rośnie wokół tego, o co faktycznie pytasz, a nie wokół wszystkiego, co
|
||||
teoretycznie dałoby się spisać.
|
||||
|
||||
Trwałe braki można też śledzić w `wiki/query-gaps.md`. Dobry wpis o luce jest
|
||||
maleńki: pytanie, gdzie agent szukał i jakie najmniejsze źródło lub strona
|
||||
sprawiłaby, że odpowiedź będzie dostępna następnym razem.
|
||||
|
||||
### D. Utwórz lokalny zakres projektu
|
||||
|
||||
Gdy jakiś temat, klient, system lub inicjatywa wraca często, poproś:
|
||||
|
||||
> „Utwórz zakres projektu dla integracji płatności."
|
||||
|
||||
Agent utworzy lub zaktualizuje zwykłą stronę Markdown pod `wiki/projects/`,
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## 3. Utrzymanie porządku
|
||||
|
|
@ -201,6 +235,9 @@ To uruchamia przegląd kondycji całej wiki:
|
|||
albo są archiwizowane
|
||||
- uszkodzone krawędzie grafu są naprawiane lub usuwane
|
||||
- brakujące/podwójne wpisy w indeksie i dzienniku są poprawiane
|
||||
- konektorowe źródła, których indeks jest zaległy do odświeżenia, zostają
|
||||
oflagowane wraz z informacją o ile — przydatne nawet jeśli masz do tego
|
||||
źródła dostęp tylko do odczytu, bo mówi ci, kogo dopytać
|
||||
- powtarzające się problemy systemowe trafiają do `wiki/error-book.md`
|
||||
|
||||
Naprawia samodzielnie to, co może zrobić bezpiecznie, a resztę zgłasza do
|
||||
|
|
@ -363,11 +400,46 @@ Po prostu zapytaj, zwykłym językiem:
|
|||
|
||||
> „Co wiemy o ryzyku migracji w Q3?”
|
||||
|
||||
Agent najpierw czyta `wiki/index.md`, żeby znaleźć odpowiednie strony,
|
||||
sprawdza ich jednolinijkowy `tldr` przed załadowaniem pełnej strony,
|
||||
przechodzi po grafie wiedzy w poszukiwaniu powiązanych faktów i sięga do
|
||||
`linked/`/`libs/`, jeśli lokalna wiki nic nie ma. Dostajesz odpowiedź
|
||||
opartą na tym, co faktycznie zostało spisane, a nie na domysłach.
|
||||
Agent najpierw czyta `wiki/index.md`, żeby znaleźć odpowiednie strony. Jeśli
|
||||
istnieje pasujący zakres projektu pod `wiki/projects/`, przeszukuje najpierw
|
||||
ten zakres. Potem sprawdza jednolinijkowe pola `tldr`, w razie potrzeby
|
||||
uruchamia dokładne wyszukiwanie lokalne dla literalnych tokenów, rozszerza
|
||||
kontekst wokół dopasowanych sekcji, przechodzi po grafie wiedzy w poszukiwaniu
|
||||
powiązanych faktów i sięga do `linked/`/`libs/`, jeśli lokalna wiki nic nie ma.
|
||||
Dostajesz odpowiedź opartą na tym, co faktycznie zostało spisane, a nie na
|
||||
domysłach.
|
||||
|
||||
Dwie rzeczy warte wiedzenia jako użytkownik:
|
||||
|
||||
- **Przeszukuje też `raw/inbox/`.** Coś, co wrzuciłeś dziś rano i czego jeszcze
|
||||
nie zingestowałeś, nadal może odpowiedzieć na twoje pytanie. Agent powie ci,
|
||||
kiedy odpowiedź pochodzi z niezingestowanego materiału, co jednocześnie
|
||||
sygnalizuje, że „Ingest" jest zaległy.
|
||||
- **Odpowiedzi noszą własne zastrzeżenia.** Jeśli strona stojąca za odpowiedzią
|
||||
przekroczyła okno świeżości, ma niską pewność albo została przeczytana z
|
||||
zapisanego indeksu konektora zamiast z żywego źródła, odpowiedź mówi o tym
|
||||
obok danego twierdzenia. Jeśli dwie strony są ze sobą sprzeczne, a żadna nie
|
||||
została jeszcze oznaczona jako zastąpiona, też o tym usłyszysz. Chodzi o to,
|
||||
żebyś nigdy nie musiał sam czytać frontmatteru, by wiedzieć, na ile zaufać
|
||||
temu, co właśnie dostałeś.
|
||||
|
||||
Gdy nadal nie ma odpowiedzi, agent powinien powiedzieć, czego brakuje, i albo
|
||||
dodać/zaproponować krótki wpis w `wiki/query-gaps.md`, albo zasugerować
|
||||
najmniejsze źródło do wrzucenia do `raw/inbox/`.
|
||||
|
||||
### Pytanie, kto się na czymś zna
|
||||
|
||||
> „Kto zna się na ścieżce przywracania checkpointów?" / „Kto jest właścicielem
|
||||
> usługi billingowej?"
|
||||
|
||||
Na te pytania odpowiada bezpośrednio graf wiedzy, a nie wyszukiwanie nazwisk po
|
||||
słowach kluczowych. Ingest zapisuje krawędź eksperctwa lub własności, gdy
|
||||
materiał źródłowy faktycznie pokazuje, że ktoś odpowiada na pytania w danym
|
||||
temacie albo ma zadeklarowaną odpowiedzialność za niego — a nie na podstawie
|
||||
obecności na spotkaniu czy nazwy stanowiska. Jeśli nikt nie ma jeszcze
|
||||
zapisanej krawędzi, agent wraca do tego, kogo zarchiwizowane źródła pokazują
|
||||
jako odpowiadającego na tego rodzaju pytania, i mówi ci, że wnioskuje, a nie
|
||||
raportuje.
|
||||
|
||||
### Nauka z wiki
|
||||
|
||||
|
|
@ -472,6 +544,7 @@ Przykład:
|
|||
> connector: sharepoint
|
||||
> location: "https://contoso.sharepoint.com/sites/Finance/Shared Documents/Reports"
|
||||
> description: "Wspólny folder raportów zespołu finansowego"
|
||||
> refresh_interval_days: 7
|
||||
> ```
|
||||
> *potem mówisz „Index external sources.”*
|
||||
>
|
||||
|
|
@ -562,7 +635,7 @@ zmieniłeś.
|
|||
| `raw/archive/<data>/` | Agent | Automatycznie zarchiwizowana kopia tego, co wrzuciłeś do `raw/inbox/`, uporządkowana według daty ingestu. Nie umieszczaj tu plików ręcznie — pozwól, żeby zrobił to Ingest, tak by data i powiązanie z wpisem w dzienniku były poprawne. |
|
||||
| `linked/<name>/` | **Ty** (tworzysz dowiązanie symboliczne) | Wskazuje na rzeczywiste pliki innej KB, które żyją i są edytowane *w tamtym repozytorium* — nigdy tutaj. Agent nigdy nie może zapisywać wewnątrz `linked/`. |
|
||||
| `libs/<name>/` (kopia git, bez `source.yaml`) | **Ty** (robisz `git clone`) | Zamrożona kopia zewnętrznej KB. Aktualizujesz ją, ponownie pobierając to repozytorium samodzielnie, a nie ręcznie edytując pliki tutaj. Agent nigdy nie może zapisywać wewnątrz niej. |
|
||||
| `libs/<name>/source.yaml` (konektor) | **Tylko ty** | Deklaruje konektor, lokalizację i opcjonalnie gdzie znajduje się współdzielony/wcześniej zbudowany indeks (`index:`). Agent go czyta, ale nigdy nie zapisuje — tak jak wszystko inne nadrzędne. |
|
||||
| `libs/<name>/source.yaml` (konektor) | **Tylko ty** | Deklaruje konektor, lokalizację, opcjonalnie jak często ma być odświeżany (`refresh_interval_days:`) i opcjonalnie gdzie znajduje się współdzielony/wcześniej zbudowany indeks (`index:`). Agent go czyta, ale nigdy nie zapisuje — tak jak wszystko inne nadrzędne. |
|
||||
| `libs/<name>/source.local.yaml` (konektor) | **Ty** (albo agent, tylko gdy wyraźnie poprosisz o zostanie/przestanie bycia administratorem tego źródła) | Osobiste, per-komputer ustawienie `access: write`/`read` — nigdy niecommitowane, nigdy niewidoczne dla innych. Brak = tylko do odczytu, domyślnie. |
|
||||
| `libs/<name>/{index.md,entities/,graph/,log.md}` (konektor) | Generowane przez agenta, **możesz swobodnie edytować** | Własny indeks agenta dla tego jednego źródła konektora, budowany/odświeżany przez „Index external sources” — ale tylko jeśli masz lokalnie `access: write`; użytkownicy tylko-do-odczytu dostają po prostu pobraną kopię. Strukturalnie ta sama zasada jak przy wierszu `wiki/` poniżej — śmiało popraw wpis ręcznie, a potem uruchom „Lint” (teraz sprawdza też indeksy oparte na konektorach, respektując ten sam podział odczyt/zapis). Ograniczone wyłącznie do tego konektora; nigdy nie wmieszane w `wiki/`. |
|
||||
| `wiki/` (strony, `index.md`, `overview.md`, `log.md`, `error-book.md`, `entities/`, `graph/`) | Generowane przez agenta, **możesz swobodnie edytować** | To jedyne miejsce, w którym zarówno agent zapisuje, jak i spodziewa się, że ty też możesz. Śmiało popraw stronę ręcznie — zachowaj tylko pola frontmatteru (lub zaktualizuj `last_updated`) i uruchom potem Lint, jeśli dotknąłeś czegoś, do czego odwołuje się indeks/graf/dziennik. |
|
||||
|
|
@ -592,4 +665,5 @@ zmieniłeś.
|
|||
| „Export the wiki to Starlight” | Czytelna dla człowieka strona dokumentacji w `outputs/starlight/` | `ckb-export-starlight` |
|
||||
| „Upgrade the wiki” / „Check for a newer template version” | Sprawdza wersje szablonu i schematu wiki względem kanonicznego repozytorium, aktualizuje to, co zaakceptujesz | `ckb-upgrade` |
|
||||
| „Index external sources” / „Index libs” | Buduje/odświeża samodzielny indeks dla każdego `libs/<name>/` opartego na konektorze | `ckb-index-external` |
|
||||
| Po prostu zadaj pytanie | Odpowiedź z wiki, przy użyciu kaskady indeks/TLDR/graf | — (podstawowy przepływ zapytań) |
|
||||
| Po prostu zadaj pytanie | Odpowiedź z wiki, przy użyciu kaskady indeks/TLDR/graf, z zastrzeżeniami gdy źródło jest nieaktualne lub sprzeczne | `ckb-retrieve` |
|
||||
| „Kto wie o X" / „Kto jest właścicielem X" | Odpowiedź z krawędzi eksperctwa/własności w grafie | `ckb-retrieve` |
|
||||
|
|
|
|||
113
README.md
113
README.md
|
|
@ -31,6 +31,8 @@ worked examples for every use case — see [MANUAL.md](MANUAL.md)
|
|||
│ ├── overview.md # High-level map
|
||||
│ ├── log.md # Root rollup change log
|
||||
│ ├── error-book.md # Compilation errors & derived constraints
|
||||
│ ├── query-gaps.md # Failed or missing-answer questions for future ingest
|
||||
│ ├── projects/ # Optional local query scopes
|
||||
│ ├── entities/ # Typed entity pages (people, projects, concepts) + own index.md
|
||||
│ └── graph/ # Edge lists and relationship data + own index.md
|
||||
└── workload/ # Session summaries & decisions
|
||||
|
|
@ -72,6 +74,23 @@ Implemented as a Claude Code Skill — see
|
|||
actually invoked. Distinct from the `ckb-sync-changes` skill, which is a
|
||||
pure git-level operation with no wiki synthesis.
|
||||
|
||||
For long conversations, meeting notes, transcripts, or chat exports, ingest
|
||||
uses a structured distillation rather than treating the whole file as one
|
||||
undifferentiated blob: searchable question, short summary, resolution or
|
||||
decision, systems/code references, people involved, and high-signal excerpts
|
||||
that deserve to stay findable on their own.
|
||||
|
||||
"High-signal" is an explicit test, not a judgment call, or every excerpt
|
||||
looks worth keeping and the page becomes a second copy of the transcript.
|
||||
An excerpt earns its own retrievable section only if it carries a term rare
|
||||
across the wiki (checked with `rg -c` — a distinguishing search handle, not
|
||||
a word already on twenty pages), runs to roughly 200 characters or more, and
|
||||
is corroborated by something later in the material agreeing with, acting on,
|
||||
or correcting it. Fail any one and the content still lands in the page, just
|
||||
inside the summary rather than as its own unit. Promoted excerpts carry
|
||||
their parent heading or thread question with them, so they read
|
||||
unambiguously alone.
|
||||
|
||||
### Lazy-Loading Index with "Use When" Triggers
|
||||
`wiki/index.md` is a routing table. Each entry has a **Use when** column
|
||||
listing trigger keywords. The agent reads the index first (stays in context),
|
||||
|
|
@ -83,6 +102,81 @@ Every page carries a one-sentence `tldr` in frontmatter. When querying, the
|
|||
agent reads TLDRs first. If the TLDR already answers the question, the full
|
||||
body is never loaded. Fallback chain: TLDR → body → raw source.
|
||||
|
||||
### Local Project Scopes
|
||||
For recurring teams, clients, systems, or initiatives, the wiki can keep
|
||||
plain Markdown scope pages under `wiki/projects/`. A scope page lists the
|
||||
wiki pages, entities, raw/archive sources, connector-backed libs, outputs,
|
||||
and graph areas that should be searched first for that project. This gives
|
||||
the same practical benefit as a project workspace in a larger retrieval
|
||||
system while staying local, transparent, and editable with any text editor.
|
||||
|
||||
Scopes only narrow the first pass. If the scoped search does not answer the
|
||||
question, the agent falls back to the full cascade.
|
||||
|
||||
### Local Hybrid Retrieval
|
||||
When index/TLDR routing is not enough, the agent can combine several local
|
||||
signals before answering:
|
||||
- exact text search with `rg` for error strings, commands, flags, filenames,
|
||||
hostnames, ticket IDs, and other literal tokens — including across
|
||||
`raw/inbox/`, so material dropped an hour ago and not yet ingested can
|
||||
still answer a question (and flags that an ingest is overdue)
|
||||
- semantic/entity matches from page titles, TLDRs, project scopes, and graph
|
||||
relationships
|
||||
- freshness and confidence metadata, so stale or weak pages are treated with
|
||||
care
|
||||
- context expansion around a matched section, so answers are grounded in the
|
||||
neighboring headings and paragraphs rather than a lone snippet
|
||||
|
||||
Each signal produces its own ranked list, and the lists are then fused
|
||||
rather than resolved by picking a favourite: every candidate scores
|
||||
`weight / (k + rank)` summed across the lists it appears in, so a page
|
||||
ranked third by three signals beats one ranked first by a single signal.
|
||||
`k` is 10, deliberately smaller than the 60 rank fusion is usually quoted
|
||||
with — 60 is tuned for retrievers returning hundreds of candidates and
|
||||
flattens all scores into near-identical values against the dozen a local
|
||||
wiki produces. Literal-token queries up-weight the exact-match list, since
|
||||
no amount of title similarity should outrank a match on the exact string
|
||||
someone pasted.
|
||||
|
||||
Fused candidates are then deduplicated by claim — a wiki page, the
|
||||
`raw/archive/` file it cites, and a connector page pointing back at it are
|
||||
three hits for one fact, not three sources — and reranked 0–10 on how well
|
||||
each answers the literal question rather than how well it matches the
|
||||
question's wording. Same agent, deliberate second pass, no separate model.
|
||||
|
||||
The result is normalized internally as an evidence packet: source path,
|
||||
matched claim, date/freshness, confidence/quality, relationship or scope
|
||||
hints, and which signals each candidate was fused from. No server, vector
|
||||
database, or dedicated client is required.
|
||||
|
||||
### Answer Caveats
|
||||
Metadata the wiki already tracks is stated in the answer itself, not just
|
||||
consulted while building it. When a page grounding an answer is past its
|
||||
`freshness_window_days`, carries low `confidence`/`quality`, rests on
|
||||
un-ingested `raw/inbox/` material, or was checked against a cached
|
||||
connector index rather than a live re-fetch, the answer says so next to
|
||||
the claim it qualifies. Conflicts between two live pages are surfaced the
|
||||
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.
|
||||
|
||||
### Expertise & Ownership Lookups
|
||||
"Who knows about X" and "who owns X" are direct graph lookups rather than
|
||||
full-text guesses. Ingest records `has_expertise_in` edges when someone
|
||||
demonstrably answers questions or explains decisions on a topic, and
|
||||
`owns` edges for declared responsibility over a system, area, or decision
|
||||
— both from demonstrated evidence only, never inferred from meeting
|
||||
attendance or job title. Where no edge exists yet, retrieval falls back to
|
||||
authorship evidence and says which of the two grounded the answer, since
|
||||
an inferred expert is a weaker claim than a recorded one.
|
||||
|
||||
### Query Gaps
|
||||
If the cascade cannot answer a question, the agent records or proposes a
|
||||
short entry in `wiki/query-gaps.md`: what was asked, where it looked, and the
|
||||
smallest source or page that would close the gap. This makes failed searches
|
||||
useful demand signals for the next ingest instead of disappearing into chat
|
||||
history.
|
||||
|
||||
### Page Frontmatter Schema
|
||||
Every wiki page uses YAML frontmatter. `type` is required; the rest are optional:
|
||||
|
||||
|
|
@ -109,16 +203,18 @@ retention: high|medium|low
|
|||
- **freshness_window_days** — pages older than this get flagged during lint
|
||||
- **retention** — low pages are archived after 2× freshness window
|
||||
|
||||
`wiki/index.md` alone also carries `kb_schema_version` (e.g. `"1.1"`), declaring
|
||||
`wiki/index.md` alone also carries `kb_schema_version` (e.g. `"1.3"`), declaring
|
||||
which revision of this schema the wiki was authored against — bump minor for
|
||||
additive optional fields, major for breaking changes.
|
||||
|
||||
### Entity Extraction & Knowledge Graph
|
||||
During ingest, the agent extracts typed entities (people, projects, libraries,
|
||||
concepts, systems) and stores them as pages in `wiki/entities/`. Typed
|
||||
relationships (`uses`, `depends_on`, `caused`, `contradicts`, `supersedes`)
|
||||
are recorded in `wiki/graph/edges.json`. Queries can walk the graph to
|
||||
discover connected pages (e.g. "what depends on Redis?").
|
||||
relationships are recorded in `wiki/graph/edges.json` — structural ones
|
||||
(`uses`, `depends_on`, `caused`, `contradicts`, `supersedes`) plus
|
||||
people-to-topic ones (`has_expertise_in`, `owns`). Queries can walk the
|
||||
graph to discover connected pages (e.g. "what depends on Redis?") or to
|
||||
answer "who knows about X" directly.
|
||||
|
||||
### Recursive Index & Log Convention
|
||||
Any `wiki/` subdirectory that groups multiple pages (`entities/`, `graph/`,
|
||||
|
|
@ -138,7 +234,15 @@ mirror locally:
|
|||
connector: sharepoint
|
||||
location: "https://contoso.sharepoint.com/sites/Finance/Shared Documents/Reports"
|
||||
description: "Finance team's shared reports folder"
|
||||
refresh_interval_days: 7 # optional, defaults to 30
|
||||
```
|
||||
`refresh_interval_days` tunes cadence per source — a folder that churns
|
||||
daily deserves a shorter window than a quarterly archive that barely moves
|
||||
— and sets the `freshness_window_days` stamped on that source's generated
|
||||
pages. Both "index external sources" and "Lint" report a source that's
|
||||
overdue against it, and say by how much, so a read-only user knows which
|
||||
admin to chase rather than quietly trusting a copy three weeks past due.
|
||||
|
||||
Say "index external sources" and the agent walks it, resolving `connector`
|
||||
to whatever live tool is available that session (a connected Microsoft
|
||||
365/Google Drive MCP tool, or `WebFetch` for a plain URL), and builds a
|
||||
|
|
@ -198,6 +302,7 @@ Periodically (or on demand), the agent health-checks the wiki:
|
|||
- **Orphan detection** — finds pages with no inbound links
|
||||
- **Graph consistency** — verifies all edges point to existing entities
|
||||
- **Index/log consistency** — verifies every subdirectory has an index.md and no change is double-logged
|
||||
- **Connector cadence** — flags a connector-backed source whose generated index is overdue against its `refresh_interval_days`, and by how much
|
||||
- **Error Book** — records systemic issues with root cause and fix
|
||||
|
||||
Auto-fixes what it can (broken links, missing backlinks, stale flags), and
|
||||
|
|
|
|||
121
README.pl.md
121
README.pl.md
|
|
@ -75,6 +75,25 @@ się do kontekstu tylko wtedy, gdy jest faktycznie wywoływana. Odrębne od
|
|||
skilla `ckb-sync-changes`, który jest czysto operacją na poziomie gita, bez
|
||||
syntezy wiki.
|
||||
|
||||
Dla długich rozmów, notatek ze spotkań, transkryptów lub eksportów czatu
|
||||
ingest używa strukturalnej destylacji, zamiast traktować cały plik jako jedną
|
||||
niezróżnicowaną bryłę: wyszukiwalne pytanie, krótkie podsumowanie,
|
||||
rozwiązanie lub decyzja, odniesienia do systemów/kodu, zaangażowane osoby
|
||||
oraz fragmenty o wysokiej wartości, które zasługują na to, by pozostać
|
||||
znajdowalne samodzielnie.
|
||||
|
||||
„Wysoka wartość" to jawny test, a nie ocena uznaniowa — inaczej każdy
|
||||
fragment wygląda na wart zachowania, a strona staje się drugą kopią
|
||||
transkryptu. Fragment zasługuje na własną wyszukiwalną sekcję tylko wtedy,
|
||||
gdy zawiera termin rzadki w całej wiki (sprawdzane przez `rg -c` — wyróżniający
|
||||
uchwyt wyszukiwania, a nie słowo już obecne na dwudziestu stronach), ma około
|
||||
200 znaków lub więcej i jest potwierdzony przez coś dalej w materiale, co się
|
||||
z nim zgadza, działa na jego podstawie lub go koryguje. Niespełnienie choćby
|
||||
jednego warunku oznacza, że treść nadal trafia na stronę, tylko wewnątrz
|
||||
podsumowania, a nie jako osobna jednostka. Awansowane fragmenty zabierają ze
|
||||
sobą nagłówek nadrzędny lub pytanie wątku, żeby dały się jednoznacznie
|
||||
czytać samodzielnie.
|
||||
|
||||
### Leniwie ładowany indeks z wyzwalaczami „Use When"
|
||||
`wiki/index.md` to tabela routingu. Każdy wpis ma kolumnę **Use when** z
|
||||
listą słów kluczowych wyzwalających. Agent najpierw czyta indeks (pozostaje
|
||||
|
|
@ -87,6 +106,86 @@ Podczas zapytania agent najpierw czyta TLDR-y. Jeśli TLDR już odpowiada na
|
|||
pytanie, pełna treść nigdy nie jest ładowana. Łańcuch odwoławczy: TLDR →
|
||||
treść → surowe źródło.
|
||||
|
||||
### Lokalne zakresy projektów
|
||||
Dla powracających zespołów, klientów, systemów lub inicjatyw wiki może
|
||||
trzymać zwykłe strony zakresów w formacie Markdown pod `wiki/projects/`.
|
||||
Strona zakresu wymienia strony wiki, encje, źródła z `raw/archive/`,
|
||||
konektorowe `libs/`, wyjścia i obszary grafu, które należy przeszukać
|
||||
najpierw dla danego projektu. Daje to tę samą praktyczną korzyść co
|
||||
przestrzeń robocza projektu w większym systemie wyszukiwania, pozostając
|
||||
lokalnym, przejrzystym i edytowalnym w dowolnym edytorze tekstu.
|
||||
|
||||
Zakresy zawężają tylko pierwsze przejście. Jeśli wyszukiwanie w zakresie nie
|
||||
odpowiada na pytanie, agent wraca do pełnej kaskady.
|
||||
|
||||
### Lokalne wyszukiwanie hybrydowe
|
||||
Gdy routing po indeksie/TLDR nie wystarcza, agent może połączyć kilka
|
||||
lokalnych sygnałów przed odpowiedzią:
|
||||
- dokładne wyszukiwanie tekstu przez `rg` dla komunikatów błędów, komend,
|
||||
flag, nazw plików, nazw hostów, identyfikatorów zgłoszeń i innych
|
||||
literalnych tokenów — również w `raw/inbox/`, więc materiał wrzucony
|
||||
godzinę temu i jeszcze nie zingestowany nadal może odpowiedzieć na pytanie
|
||||
(i sygnalizuje, że ingest jest zaległy)
|
||||
- dopasowania semantyczne/encyjne z tytułów stron, TLDR-ów, zakresów
|
||||
projektów i relacji w grafie
|
||||
- metadane świeżości i pewności, dzięki którym nieaktualne lub słabe strony
|
||||
są traktowane ostrożnie
|
||||
- rozszerzenie kontekstu wokół dopasowanej sekcji, aby odpowiedzi były
|
||||
osadzone w sąsiadujących nagłówkach i akapitach, a nie w samotnym urywku
|
||||
|
||||
Każdy sygnał tworzy własną listę rankingową, a listy są następnie łączone,
|
||||
zamiast rozstrzygania przez wybór ulubionego sygnału: każdy kandydat zbiera
|
||||
`weight / (k + rank)` zsumowane po listach, na których występuje, więc strona
|
||||
na trzecim miejscu w trzech listach wygrywa ze stroną pierwszą w jednej.
|
||||
`k` wynosi 10, celowo mniej niż zwykle cytowane 60 — 60 jest dostrojone do
|
||||
wyszukiwarek zwracających setki kandydatów i spłaszcza wszystkie wyniki do
|
||||
niemal identycznych wartości przy kilkunastu, które daje lokalna wiki.
|
||||
Zapytania o literalne tokeny podnoszą wagę listy dokładnych dopasowań,
|
||||
ponieważ żadne podobieństwo tytułu nie powinno wyprzedzić trafienia w dokładny
|
||||
ciąg, który ktoś wklejił.
|
||||
|
||||
Połączeni kandydaci są następnie deduplikowani według twierdzenia — strona
|
||||
wiki, plik z `raw/archive/`, który cytuje, i strona konektora wskazująca na
|
||||
nią to trzy trafienia dla jednego faktu, nie trzy źródła — i przerankowani w
|
||||
skali 0–10 według tego, jak dobrze odpowiadają na dosłownie zadane pytanie, a
|
||||
nie jak dobrze pasują do jego sformułowania. Ten sam agent, świadome drugie
|
||||
przejście, bez osobnego modelu.
|
||||
|
||||
Wynik jest wewnętrznie normalizowany jako pakiet dowodowy: ścieżka źródła,
|
||||
dopasowane twierdzenie, data/świeżość, pewność/jakość, wskazówki o relacjach
|
||||
lub zakresie oraz informacja, z których sygnałów każdy kandydat został
|
||||
połączony. Nie jest wymagany żaden serwer, baza wektorowa ani dedykowany
|
||||
klient.
|
||||
|
||||
### Zastrzeżenia w odpowiedziach
|
||||
Metadane, które wiki już śledzi, są podawane w samej odpowiedzi, a nie tylko
|
||||
sprawdzane przy jej budowaniu. Gdy strona stanowiąca podstawę odpowiedzi
|
||||
przekroczyła `freshness_window_days`, ma niską `confidence`/`quality`, opiera
|
||||
się na niezingestowanym materiale z `raw/inbox/` lub została sprawdzona
|
||||
względem zapisanego w pamięci indeksu konektora, a nie żywego źródła —
|
||||
odpowiedź mówi o tym obok twierdzenia, którego to dotyczy. Konflikty między
|
||||
dwiema aktywnymi stronami są ujawniane tak samo, nawet jeśli żadna nie ma
|
||||
jeszcze `superseded_by`. Zamyka to tryb awarii polegający na pewnej
|
||||
odpowiedzi *z* nieaktualnej strony bez przekazania tej informacji dalej.
|
||||
|
||||
### Wyszukiwanie ekspertów i właścicieli
|
||||
„Kto wie o X" i „kto jest właścicielem X" to bezpośrednie zapytania do grafu,
|
||||
a nie zgadywanie po pełnym tekście. Ingest zapisuje krawędzie
|
||||
`has_expertise_in`, gdy ktoś wykazuje się odpowiadaniem na pytania lub
|
||||
wyjaśnianiem decyzji w danym temacie, oraz krawędzie `owns` dla zadeklarowanej
|
||||
odpowiedzialności za system, obszar lub decyzję — oba wyłącznie na podstawie
|
||||
wykazanych dowodów, nigdy wnioskowane z obecności na spotkaniu czy ze
|
||||
stanowiska. Gdy krawędzi jeszcze nie ma, wyszukiwanie wraca do dowodów
|
||||
autorstwa i mówi, które z dwóch stanowiło podstawę odpowiedzi, bo domniemany
|
||||
ekspert to słabsze twierdzenie niż zapisany.
|
||||
|
||||
### Luki w zapytaniach
|
||||
Jeśli kaskada nie potrafi odpowiedzieć na pytanie, agent zapisuje lub proponuje
|
||||
krótki wpis w `wiki/query-gaps.md`: o co pytano, gdzie szukał i jakie
|
||||
najmniejsze źródło lub strona zamknęłaby lukę. Dzięki temu nieudane
|
||||
wyszukiwania stają się użytecznym sygnałem zapotrzebowania dla następnego
|
||||
ingestu, zamiast przepadać w historii czatu.
|
||||
|
||||
### Schemat frontmatteru strony
|
||||
Każda strona wiki używa frontmatteru YAML. Pole `type` jest wymagane; reszta
|
||||
jest opcjonalna:
|
||||
|
|
@ -121,7 +220,7 @@ retention: high|medium|low
|
|||
- **retention** — strony o niskim priorytecie są archiwizowane po 2× oknie
|
||||
świeżości
|
||||
|
||||
Sam `wiki/index.md` dodatkowo zawiera `kb_schema_version` (np. `"1.1"`),
|
||||
Sam `wiki/index.md` dodatkowo zawiera `kb_schema_version` (np. `"1.3"`),
|
||||
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ść.
|
||||
|
|
@ -129,9 +228,11 @@ zmian łamiących kompatybilność.
|
|||
### Ekstrakcja encji i graf wiedzy
|
||||
Podczas ingestu agent wydobywa typowane encje (osoby, projekty, biblioteki,
|
||||
koncepcje, systemy) i zapisuje je jako strony w `wiki/entities/`. Typowane
|
||||
relacje (`uses`, `depends_on`, `caused`, `contradicts`, `supersedes`) są
|
||||
zapisywane w `wiki/graph/edges.json`. Zapytania mogą przechodzić po grafie,
|
||||
aby odkrywać powiązane strony (np. „co zależy od Redis?").
|
||||
relacje są zapisywane w `wiki/graph/edges.json` — strukturalne (`uses`,
|
||||
`depends_on`, `caused`, `contradicts`, `supersedes`) oraz łączące osoby z
|
||||
tematami (`has_expertise_in`, `owns`). Zapytania mogą przechodzić po grafie,
|
||||
aby odkrywać powiązane strony (np. „co zależy od Redis?") albo bezpośrednio
|
||||
odpowiadać na „kto wie o X".
|
||||
|
||||
### Rekurencyjna konwencja indeksu i dziennika
|
||||
Każdy podkatalog `wiki/`, który grupuje wiele stron (`entities/`, `graph/`,
|
||||
|
|
@ -151,7 +252,16 @@ URL albo inny konektor — którego nie chcesz w pełni kopiować lokalnie:
|
|||
connector: sharepoint
|
||||
location: "https://contoso.sharepoint.com/sites/Finance/Shared Documents/Reports"
|
||||
description: "Wspólny folder raportów zespołu finansowego"
|
||||
refresh_interval_days: 7 # opcjonalne, domyślnie 30
|
||||
```
|
||||
`refresh_interval_days` dostraja częstotliwość per źródło — folder zmieniający
|
||||
się codziennie zasługuje na krótsze okno niż kwartalne archiwum, które prawie
|
||||
nie drgnie — i ustawia `freshness_window_days` nadawane generowanym stronom
|
||||
tego źródła. Zarówno „index external sources", jak i „Lint" raportują źródło
|
||||
zaległe względem tej wartości i mówią o ile, żeby użytkownik z dostępem tylko
|
||||
do odczytu wiedział, kogo zapytać, zamiast po cichu polegać na kopii sprzed
|
||||
trzech tygodni.
|
||||
|
||||
Powiedz „index external sources", a agent go przeskanuje, dopasowując
|
||||
`connector` do dowolnego żywego narzędzia dostępnego w danej sesji
|
||||
(połączonego narzędzia MCP do Microsoft 365/Google Drive, albo `WebFetch`
|
||||
|
|
@ -219,6 +329,9 @@ Okresowo (lub na żądanie) agent sprawdza kondycję wiki:
|
|||
istniejące encje
|
||||
- **Spójność indeksu/dziennika** — weryfikuje, czy każdy podkatalog ma
|
||||
index.md i czy żadna zmiana nie jest podwójnie logowana
|
||||
- **Częstotliwość konektorów** — oznacza konektorowe źródło, którego
|
||||
generowany indeks jest zaległy względem `refresh_interval_days`, wraz z
|
||||
informacją o ile
|
||||
- **Księga błędów (Error Book)** — zapisuje systemowe problemy wraz z
|
||||
przyczyną i naprawą
|
||||
|
||||
|
|
|
|||
2
VERSION
2
VERSION
|
|
@ -1 +1 @@
|
|||
1.1.0
|
||||
1.3.0
|
||||
|
|
|
|||
|
|
@ -2,6 +2,8 @@
|
|||
|
||||
Edge list and relationship data for the knowledge graph, keyed by entity page.
|
||||
|
||||
* `edges.json` - Typed relationships (`uses`, `depends_on`, `caused`, `contradicts`, `supersedes`) between entity pages. Created on the first ingest that extracts entities.
|
||||
* `edges.json` - Typed relationships between entity pages. Created on the first ingest that extracts entities.
|
||||
* Structural: `uses`, `depends_on`, `caused`, `contradicts`, `supersedes`.
|
||||
* People-to-topic: `has_expertise_in` (demonstrated ability to answer questions on a topic) and `owns` (declared responsibility for a system, area, or decision). These make "who knows about X" and "who owns X" a direct graph lookup rather than a full-text guess. Recorded only from demonstrated evidence, never inferred from attendance or job title.
|
||||
|
||||
*(No edges recorded yet — populated on the next ingest.)*
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
---
|
||||
kb_schema_version: "1.1"
|
||||
kb_schema_version: "1.3"
|
||||
---
|
||||
|
||||
# Knowledge Base Index
|
||||
|
|
@ -11,6 +11,8 @@ kb_schema_version: "1.1"
|
|||
| [Overview](overview.md) | High-level map of the knowledge base | Getting started, understanding the structure |
|
||||
| [Log](log.md) | Chronological record of root-level changes | Reviewing recent modifications |
|
||||
| [Error Book](error-book.md) | Known compilation errors and fixes | Debugging a bad ingest or lint issue |
|
||||
| [Projects](projects/index.md) | Optional local query scopes grouping related wiki pages, sources, libs, and graph areas | Narrowing search to a team, topic, client, system, or initiative |
|
||||
| [Query Gaps](query-gaps.md) | Questions the wiki could not answer yet, used to drive demand-driven ingest | Tracking failed searches, missing knowledge, future ingest targets |
|
||||
| [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 |
|
||||
|
||||
|
|
|
|||
24
wiki/log.md
24
wiki/log.md
|
|
@ -1,4 +1,28 @@
|
|||
# Wiki Change Log
|
||||
|
||||
## [2026-07-30 08:40] - [UPDATE]
|
||||
- **File Affected:** `wiki/index.md`
|
||||
- **Description:** Bumped `kb_schema_version` from `1.2` to `1.3` — a minor bump for the additive `has_expertise_in`/`owns` graph edge types. No existing field or convention changed meaning.
|
||||
- **Source:** Chat conversation implementing eight ideas drawn from Cerebras' "How We Built Our Knowledge Base".
|
||||
---
|
||||
|
||||
## [2026-07-30 08:38] - [UPDATE]
|
||||
- **File Affected:** `wiki/graph/index.md`
|
||||
- **Description:** Documented two new optional edge types, `has_expertise_in` and `owns`, alongside the existing structural ones, so "who knows about X" / "who owns X" become direct graph lookups. Both are evidence-only — never inferred from meeting attendance or job title.
|
||||
- **Source:** Chat conversation implementing eight ideas drawn from Cerebras' "How We Built Our Knowledge Base".
|
||||
---
|
||||
|
||||
## [2026-07-29 22:47] - [UPDATE]
|
||||
- **File Affected:** `wiki/index.md`
|
||||
- **Description:** Bumped `kb_schema_version` from `1.1` to `1.2` for the new optional project-scope and query-gap scaffold conventions.
|
||||
- **Source:** Chat conversation follow-up asking whether the wiki version was updated.
|
||||
---
|
||||
|
||||
## [2026-07-29 22:30] - [CREATE/UPDATE]
|
||||
- **File Affected:** `wiki/index.md`, `wiki/overview.md`, `wiki/projects/index.md`, `wiki/query-gaps.md`
|
||||
- **Description:** Added local-first project scope and query-gap scaffolds inspired by the Cerebras knowledge base concept while keeping the wiki file-based and agent-driven.
|
||||
- **Source:** Chat conversation comparing Cerebras knowledge base ideas to this local Cascade KB.
|
||||
---
|
||||
|
||||
All modifications to the local `wiki/` directory are recorded here
|
||||
in reverse chronological order (most recent first).
|
||||
|
|
|
|||
|
|
@ -26,6 +26,8 @@ When the same entity exists in multiple layers, the local version wins.
|
|||
│ └── inbox/ # Drop zone for unprocessed material
|
||||
├── tmp/ # Temporary files, caches (gitignored)
|
||||
├── wiki/ # Local structured wiki (agent-managed)
|
||||
│ ├── query-gaps.md # Failed or missing-answer questions for demand-driven ingest
|
||||
│ ├── projects/ # Optional local query scopes
|
||||
│ ├── entities/ # Typed entity pages
|
||||
│ └── graph/ # Edge lists and relationship data
|
||||
└── workload/ # Summaries of discussions and decisions
|
||||
|
|
@ -39,6 +41,13 @@ declares `kb_schema_version` for the bundle as a whole.
|
|||
See AGENTS.md for the full schema.
|
||||
|
||||
## Recursive Indexes
|
||||
`entities/` and `graph/` each carry their own `index.md` so navigation stays
|
||||
lazy — read `wiki/index.md` first, then only descend into a subdirectory
|
||||
index if its contents are relevant to the current task.
|
||||
`entities/`, `graph/`, and optional topic folders such as `projects/` each
|
||||
carry their own `index.md` so navigation stays lazy — read `wiki/index.md`
|
||||
first, then only descend into a subdirectory index if its contents are
|
||||
relevant to the current task.
|
||||
|
||||
## Local-First Retrieval Aids
|
||||
Project scope pages in `wiki/projects/` can group related sources so a query
|
||||
starts narrow before falling back to the full cascade. `wiki/query-gaps.md`
|
||||
records questions the wiki could not answer yet, turning failed searches into
|
||||
small ingest targets.
|
||||
|
|
|
|||
8
wiki/projects/index.md
Normal file
8
wiki/projects/index.md
Normal file
|
|
@ -0,0 +1,8 @@
|
|||
# Projects
|
||||
|
||||
Optional local query scopes. A project page groups related wiki pages,
|
||||
entity pages, raw/archive source paths, connector-backed libs, and graph
|
||||
areas so retrieval starts from the most relevant slice of the cascade.
|
||||
|
||||
*(No project scopes yet — create one when a topic, team, client, system, or
|
||||
initiative starts recurring often enough to deserve a default search scope.)*
|
||||
24
wiki/query-gaps.md
Normal file
24
wiki/query-gaps.md
Normal file
|
|
@ -0,0 +1,24 @@
|
|||
---
|
||||
type: log
|
||||
tldr: Local queue of questions the wiki could not answer yet, used to drive demand-driven ingest.
|
||||
confidence: 1.0
|
||||
quality: 0.8
|
||||
last_updated: 2026-07-29
|
||||
freshness_window_days: 30
|
||||
retention: medium
|
||||
---
|
||||
|
||||
# Query Gaps
|
||||
|
||||
Use this page for questions that the cascade could not answer from
|
||||
`wiki/`, `linked/`, or `libs/`. Each entry should stay short and point to
|
||||
the smallest missing source or page that would close the gap.
|
||||
|
||||
## Open
|
||||
|
||||
*(No query gaps recorded yet.)*
|
||||
|
||||
## Resolved
|
||||
|
||||
*(Move entries here after an ingest, page update, or connector index makes
|
||||
the answer available.)*
|
||||
|
|
@ -20,3 +20,38 @@
|
|||
|
||||
- User asked which ideas from the Cerebras knowledge base concept could be easily implemented in the current local wiki.
|
||||
- Re-read the current wiki scaffold and git status; identified low-effort, local-first ideas that fit Markdown files and CLI/agent workflows without requiring dedicated user software.
|
||||
|
||||
## 2026-07-29 22:44 CEST
|
||||
|
||||
- User asked to implement the selected local-first changes and update README/instruction files.
|
||||
- Added `wiki/projects/index.md` for optional project query scopes and `wiki/query-gaps.md` for durable missing-answer tracking.
|
||||
- Updated `wiki/index.md`, `wiki/overview.md`, and `wiki/log.md` to register the new scaffolds.
|
||||
- Updated `README.md`, `MANUAL.md`, `AGENTS.md`, `ckb-retrieve`, and `ckb-ingest` instructions to cover project scopes, local hybrid retrieval, evidence packets, context expansion, query-gap capture, and long-note distillation.
|
||||
|
||||
## 2026-07-29 22:47 CEST
|
||||
|
||||
- User asked whether the wiki version had been updated.
|
||||
- Confirmed it had not been bumped yet, then updated `wiki/index.md` from `kb_schema_version: "1.1"` to `"1.2"` and `VERSION` from `1.1.0` to `1.2.0`.
|
||||
- Updated README/AGENTS schema-version examples and logged the wiki schema bump in `wiki/log.md`.
|
||||
|
||||
## 2026-07-29 22:48 CEST
|
||||
|
||||
- User asked to commit changes and push to `origin`.
|
||||
- Began the `ckb-sync-changes` git-level workflow: pre-flight checks passed, `origin` was configured, and `git fetch origin` completed.
|
||||
|
||||
## 2026-07-29 22:59 CEST
|
||||
|
||||
- User asked which features in `AGENTS.md` could be moved into skills so they do not load every session.
|
||||
- Read `AGENTS.md`, listed existing skill files, and identified always-on invariants versus procedural or situational sections that are good skill candidates.
|
||||
|
||||
## 2026-07-29 23:06 CEST
|
||||
|
||||
- User asked to implement the `AGENTS.md` slimming changes.
|
||||
- Replaced `AGENTS.md` with a shorter always-loaded instruction file focused on directory contract, cascade priority, schema, skill routing, and non-negotiable rules.
|
||||
- Moved/kept procedural detail in owning skills: retrieval, ingest, external indexing, lint, sync, upgrade, and OKF export references.
|
||||
- Added schema-versioning policy to `ckb-upgrade` and bumped root `VERSION` from `1.2.0` to `1.2.1`; wiki schema remains `1.2`.
|
||||
|
||||
## 2026-07-29 23:13 CEST
|
||||
|
||||
- User asked to commit and push the `AGENTS.md` slimming changes.
|
||||
- Started `ckb-sync-changes`: pre-flight checks passed, `origin` is configured, no in-progress git operation was detected, and `git fetch origin` completed.
|
||||
|
|
|
|||
29
workload/2026-07-30_summary.md
Normal file
29
workload/2026-07-30_summary.md
Normal file
|
|
@ -0,0 +1,29 @@
|
|||
## 2026-07-30 08:05 CEST
|
||||
|
||||
- User pointed at a local copy of the Cerebras article saved to `tmp/How Cerebras Built Its Enterprise Knowledge Base.html` after two direct `WebFetch` attempts returned HTTP 500.
|
||||
- Converted it to plain text via `lynx -dump` into the session scratchpad and re-derived the concept list from the primary source, correcting details taken from secondary write-ups in the previous turn.
|
||||
- Re-listed the ideas not covered by this KB but compatible with a local, file-based, no-install design; excluded the pgvector/HNSW embeddings table, Socket Mode ingestion, CocoIndex chunking, and the hosted cross-encoder reranker as out of scope.
|
||||
|
||||
## 2026-07-30 08:20 CEST
|
||||
|
||||
- User asked which of those ideas could actually be implemented in the current wiki.
|
||||
- Read `.agents/skills/ckb-retrieve/SKILL.md` and `.agents/skills/ckb-ingest/SKILL.md` in full, plus the `source.yaml` schema in `ckb-index-external`, the graph edge-type vocabulary, and `.gitignore`'s per-user local-state precedent.
|
||||
- Found three items from the previous turn's list were already partly covered by the skills (high-signal excerpts in ingest Step 4, `rg` over `raw/archive/` in retrieve Step 2, contradiction-surfacing in retrieve Step 6) and narrowed those claims accordingly.
|
||||
- Concluded all ten are implementable without dedicated software: seven as prose-only edits to existing skills, three needing one new convention each (an expertise edge type, a `source.yaml` cadence field, a gitignored default-scope file). No implementation performed — assessment only.
|
||||
|
||||
## 2026-07-30 09:05 CEST
|
||||
|
||||
- User asked to implement the list, then chose all ten minus #5 (planning pass) and #10 (per-user default scope) — the two I'd advised against on value grounds. Eight items implemented.
|
||||
- `ckb-retrieve`: added `raw/inbox/` to the exact-token sweep, a new Step 4 (RRF-style fusion at `k = 10`, claim-level dedupe, explicit 0–10 rerank), an expertise/ownership graph lookup in Step 3, caveat surfacing in Step 7, and an edge case for the single-signal case. Renumbered old Steps 4–6 to 5–7.
|
||||
- `ckb-ingest`: replaced the loose "high-signal excerpt" guidance with a three-part acceptance test (rare term via `rg -c`, ~200 chars, corroborated later in the material) plus a rule to carry the parent heading; added `has_expertise_in`/`owns` edge recording, evidence-only.
|
||||
- `ckb-index-external`: added optional `refresh_interval_days` to `source.yaml` (default 30), wired it into the generated pages' `freshness_window_days` and into Step 4's overdue reporting for both access levels.
|
||||
- `ckb-lint`: validates `refresh_interval_days` and reports overdue connector indexes with how overdue, regardless of the user's access level; never re-indexes.
|
||||
- Chose `k = 10` rather than the usual `k = 60` for fusion, since 60 is tuned for hundreds of candidates and flattens scores at local-wiki scale. Recorded the reasoning inline in the skill so it isn't mistaken for a transcription error.
|
||||
- Bumped `kb_schema_version` 1.2 → 1.3 (additive edge types) and `VERSION` 1.2.1 → 1.3.0; logged both wiki changes in `wiki/log.md` per Rule B.
|
||||
- Found `README.pl.md`/`MANUAL.pl.md` were behind by more than the version string: five README sections and two MANUAL sections from the 2026-07-29 session had never been translated. Caught both up rather than layering today's changes onto an incoherent base. EN/PL section parity now 28/28 and 15/15.
|
||||
|
||||
## 2026-07-30 09:30 CEST
|
||||
|
||||
- User asked the reverse comparison: what this KB has that the Cerebras system does not.
|
||||
- Verified claimed absences by grepping the saved article text rather than asserting from memory — no hits for version/history/supersede/contradict/retention/archive/quality/confidence/entity/ontology/curate/stale/conflict; "graph" only as the HNSW citation, "decay" only as query-time age decay, "audit" once with no detail.
|
||||
- Framed the answer around the root asymmetry: Cerebras Knowledge is a read path over systems of record it doesn't own, while this KB is itself a system of record that authors and curates content. Noted honestly that the article is a blog post rather than a spec, and that several of this KB's curation features are only tractable at small scale.
|
||||
Loading…
Add table
Reference in a new issue