Reset wiki to clean template scaffold
Empty the KB back to the shape ckb-init creates: remove decision records
D-0001 and D-0002, the single graph edge, all five workload summaries and
the generated outputs/okf/ tree, then restore the empty scaffold with
kb_schema_version held at 1.4.
The decisions status-vocabulary table is preserved verbatim, since
ckb-decide and ckb-lint both validate against it. Lint reports 0 findings.
Restore point for the pre-reset content: tag pre-reset-2026-09-20 (0c06cb6).
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
parent
0c06cb64ab
commit
c998489c9a
14 changed files with 21 additions and 538 deletions
|
|
@ -1,78 +0,0 @@
|
|||
---
|
||||
type: decision
|
||||
tldr: Optional KB capabilities ship as file-based modules under `.agents/modules/<name>/`, installed into the KB on request, rather than as native Claude Code plugins.
|
||||
status: accepted
|
||||
decided_on: 2026-09-20
|
||||
decided_by: Michał Kopeć
|
||||
affects: /wiki/index.md
|
||||
confidence: 0.9
|
||||
quality: 0.8
|
||||
last_updated: 2026-09-20
|
||||
freshness_window_days: 365
|
||||
retention: high
|
||||
---
|
||||
|
||||
# D-0001 — Optional KB capabilities ship as file-based modules, not native plugins
|
||||
|
||||
**Status:** Accepted · **Decided:** 2026-09-20 · **Deciders:** Michał Kopeć
|
||||
|
||||
## Context
|
||||
|
||||
The base KB ships fourteen `ckb-*` skills, all always loaded. Some capabilities
|
||||
are only useful to *some* knowledge bases — the first concrete case being a KB
|
||||
that documents software the user is building (see
|
||||
[[D-0002]] / [D-0002](/wiki/decisions/0002-software-module-design.md)). Adding
|
||||
those skills unconditionally would grow the always-loaded skill-description
|
||||
budget for every KB, including ones that will never need them.
|
||||
|
||||
Three mechanisms were on the table for making a capability opt-in. The KB is
|
||||
deliberately agent-agnostic: `AGENTS.md` is the source of truth and `CLAUDE.md`
|
||||
is a symlink to it (git mode `120000`), as is `.claude/skills` → `.agents/skills`.
|
||||
That symlink arrangement is a confirmed preference, and it means anything written
|
||||
to `.agents/skills/` is visible to Claude Code for free.
|
||||
|
||||
## Decision
|
||||
|
||||
Optional capabilities are packaged as **file-based modules** stored in
|
||||
`.agents/modules/<name>/` and installed into the KB on explicit request. A
|
||||
module may contribute skills (into `.agents/skills/`), directory scaffold, a
|
||||
routing block appended to `AGENTS.md`, and `.gitignore` rules. Installation is
|
||||
recorded in a root manifest listing the installed modules and their config;
|
||||
uninstalling reverses it.
|
||||
|
||||
## Rationale
|
||||
|
||||
A module is a property of *the knowledge base*, not of the machine or the agent
|
||||
reading it. File-based modules travel with a clone, so a cloned KB stays
|
||||
self-describing, and they work for any agent that reads `AGENTS.md` — not only
|
||||
Claude Code. Shipping module content outside `.agents/skills/` until install
|
||||
keeps the always-loaded skill budget flat for KBs that don't opt in.
|
||||
|
||||
## Consequences
|
||||
|
||||
- A `ckb-module`-style install/uninstall path is needed.
|
||||
- `ckb-init` should offer modules at bootstrap; `ckb-upgrade` must not delete
|
||||
module-installed skills it doesn't recognise upstream, and must also upgrade
|
||||
`.agents/modules/`.
|
||||
- `ckb-lint` gains validation of the module manifest.
|
||||
- Module skills are authored so they could *also* be published as a native
|
||||
Claude Code plugin later without a rewrite — this decision doesn't foreclose
|
||||
that, it just declines to make it the primary mechanism.
|
||||
- Because `.claude/skills` is a symlink, an installer writes `.agents/skills/`
|
||||
only; no duplicate copy to keep in sync.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
- **Always-shipped skills that self-gate on a flag** — no install step and
|
||||
trivially upgradeable, but every skill description stays in context for every
|
||||
KB regardless of relevance. Rejected: that budget degrades quietly.
|
||||
- **Native Claude Code plugin** (`.claude-plugin/plugin.json` + marketplace) —
|
||||
real enable/disable and no file copying, but serves only Claude Code, breaking
|
||||
the dual-headed `AGENTS.md`/`CLAUDE.md` contract, and installs per-machine
|
||||
rather than per-KB. Rejected as the primary mechanism, not ruled out as an
|
||||
additional distribution channel.
|
||||
|
||||
## Sources
|
||||
|
||||
Chat conversation, 2026-09-20 — design evaluation of a source-code/software KB
|
||||
mode. See `workload/2026-09-20_summary.md`.
|
||||
|
|
@ -1,113 +0,0 @@
|
|||
---
|
||||
type: decision
|
||||
tldr: The `software` module keeps code as gitignored plain clones in `src/`, runs OpenSpec at both KB-root and per-repo level with a hybrid vendor/depend split, and links the two spec levels with `implements`/`implemented_by`.
|
||||
status: accepted
|
||||
decided_on: 2026-09-20
|
||||
decided_by: Michał Kopeć
|
||||
affects: /wiki/decisions/0001-opt-in-file-based-kb-modules.md, /wiki/index.md
|
||||
confidence: 0.85
|
||||
quality: 0.8
|
||||
last_updated: 2026-09-20
|
||||
freshness_window_days: 365
|
||||
retention: high
|
||||
---
|
||||
|
||||
# D-0002 — Design of the opt-in `software` module
|
||||
|
||||
**Status:** Accepted · **Decided:** 2026-09-20 · **Deciders:** Michał Kopeć
|
||||
|
||||
## Context
|
||||
|
||||
Some knowledge bases document software the user is actively building. In that
|
||||
case the source code lives in `src/`, usually as one or more *independent* git
|
||||
repositories with their own remotes — a git repo inside a git repo. The user
|
||||
also wants OpenSpec-driven iterative development available in that mode.
|
||||
|
||||
This is the first concrete module under
|
||||
[[D-0001]] / [D-0001](/wiki/decisions/0001-opt-in-file-based-kb-modules.md),
|
||||
and four sub-questions had to be settled: how code is hosted, where specs live,
|
||||
whether OpenSpec's own workflow instructions are vendored or depended on, and
|
||||
how two spec levels avoid becoming two sources of truth.
|
||||
|
||||
## Decision
|
||||
|
||||
**Code hosting.** `src/<repo>/` holds plain clones, gitignored (`src/*`, as
|
||||
`libs/*` already is). No submodules. Because the code may be absent from a
|
||||
fresh clone, each repo also gets a durable `type: repository` entity page in
|
||||
`wiki/` recording its remote URL, default branch, language, build command,
|
||||
`src/` path, and owner — that page, not the clone, is the durable artifact.
|
||||
|
||||
**`src/` is not a cascade layer.** It is primary evidence, like `raw/archive/`:
|
||||
`ckb-retrieve` may open and cite it when verifying a claim, but it never answers
|
||||
"what is entity X", and `ckb-ingest` does not treat code as inbox material.
|
||||
|
||||
**Spec location — both levels.** OpenSpec runs at the KB root (cross-cutting
|
||||
capabilities spanning multiple `src/` repos) *and* inside each `src/<repo>/`
|
||||
(implementation specs that travel with the code in its own repo).
|
||||
|
||||
**Vendoring — hybrid.** The KB-root spec layer is served by a module-owned
|
||||
skill, because a KB-root `openspec/` is not a normal OpenSpec repo install (no
|
||||
code beneath it, no single repo it governs) and the module must own instructions
|
||||
for it regardless. The per-`src`-repo layer delegates to OpenSpec's own native
|
||||
install and instructions, and the module reports plainly when OpenSpec is
|
||||
missing rather than substituting its own workflow. The module additionally owns
|
||||
the bridge in both directions: an archived OpenSpec change becomes a
|
||||
`wiki/decisions/NNNN-*.md` record, and current specs sync into `type: spec`
|
||||
entity pages.
|
||||
|
||||
**Drift rule.** KB-level specs state *what* and *why* across repos; `src`-level
|
||||
specs state *how* a given repo implements it. The two are linked by
|
||||
`implements:` / `implemented_by:` frontmatter, which becomes graph edges.
|
||||
`ckb-lint` gains checks for KB-level specs with no implementer and `src`-level
|
||||
specs whose parent was archived or superseded.
|
||||
|
||||
## Rationale
|
||||
|
||||
Gitignored clones avoid embedded-repo warnings and keep code out of KB history,
|
||||
while each repo keeps pushing to its own origin; submodules would pin commits
|
||||
that go stale against daily work in `src/`. Specs at both levels reflect a real
|
||||
distinction — cross-repo contracts genuinely differ from per-repo implementation
|
||||
— and the hybrid vendoring split follows from that same distinction rather than
|
||||
splitting the difference: only the level OpenSpec doesn't natively serve is
|
||||
owned locally. The `implements`/`implemented_by` link exists specifically so the
|
||||
two-level arrangement produces a lint signal when the levels disagree, instead
|
||||
of two silently divergent truths.
|
||||
|
||||
## Consequences
|
||||
|
||||
- `.gitignore` gains `src/*` rules.
|
||||
- New frontmatter types `repository`, `component`, `spec`, and optional `repo:`,
|
||||
`commit:`, `spec_id:`, `implements:`, `implemented_by:` fields — a
|
||||
`kb_schema_version` bump to `1.5`, additive only.
|
||||
- Module skills needed: a code-mapping skill (`src/<repo>` → entity pages, with
|
||||
a recorded commit hash so staleness is detectable) and a KB-root OpenSpec +
|
||||
bridge skill.
|
||||
- `ckb-sync-changes` must never `git add` under `src/`, and should report each
|
||||
`src/` repo's dirty/ahead state separately.
|
||||
- `ckb-retrieve` gains code as a verification source; `ckb-lint` gains the src
|
||||
and spec-drift checks; OKF and Starlight exports exclude `src/`.
|
||||
- The module is unusable at the `src/` level until OpenSpec is installed
|
||||
separately — it is not on PATH as of this decision.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
- **Git submodules for `src/`** — code travels with the KB and is pinned to a
|
||||
commit, which is genuinely attractive for "what did the wiki describe at that
|
||||
point". Rejected for submodule friction on every sync and pins going stale.
|
||||
- **Specs only inside each `src/` repo** — OpenSpec's native case, nothing to
|
||||
own locally, but no home for contracts spanning several repos.
|
||||
- **Specs only at KB root** — one place to look, but specs stop travelling with
|
||||
the code they govern and fall out of the repo's own PR flow.
|
||||
- **Vendoring OpenSpec's workflow wholesale** — self-contained, works with
|
||||
nothing installed, tailorable to KB conventions. Rejected: it means
|
||||
maintaining a fork of an external workflow, and `ckb-upgrade` would have two
|
||||
upstreams to track.
|
||||
- **Depending on OpenSpec at both levels** — nothing to maintain, but leaves the
|
||||
KB-root layer with no instructions at all, since OpenSpec doesn't serve that
|
||||
case.
|
||||
|
||||
## Sources
|
||||
|
||||
Chat conversation, 2026-09-20 — design evaluation of a source-code/software KB
|
||||
mode, including the user's explicit choices on mechanism, code hosting, spec
|
||||
location, and vendoring. See `workload/2026-09-20_summary.md`.
|
||||
|
|
@ -7,8 +7,7 @@ Filenames are `NNNN-short-slug.md`, numbered sequentially from `0001`, and
|
|||
numbers are never reused: a decision that is reversed or superseded keeps its
|
||||
number and its page, and the newer decision points back at it.
|
||||
|
||||
* **[Accepted]** [D-0001 — Optional KB capabilities ship as file-based modules, not native plugins](0001-opt-in-file-based-kb-modules.md) — Optional KB capabilities ship as file-based modules under `.agents/modules/<name>/`, installed into the KB on request, rather than as native Claude Code plugins.
|
||||
* **[Accepted]** [D-0002 — Design of the opt-in `software` module](0002-software-module-design.md) — The `software` module keeps code as gitignored plain clones in `src/`, runs OpenSpec at both KB-root and per-repo level with a hybrid vendor/depend split, and links the two spec levels with `implements`/`implemented_by`.
|
||||
*(No decisions recorded yet — say "record a decision" to add the first one.)*
|
||||
|
||||
## Status vocabulary
|
||||
|
||||
|
|
|
|||
|
|
@ -7,16 +7,4 @@ absorbs a change.
|
|||
|
||||
Reverse chronological order, most recent first.
|
||||
|
||||
---
|
||||
|
||||
## [2026-09-20 00:00] - [CREATE]
|
||||
- **File Affected:** `wiki/decisions/0001-opt-in-file-based-kb-modules.md`, `wiki/decisions/0002-software-module-design.md`, `wiki/decisions/index.md`
|
||||
- **Description:** Recorded the first two decision records. D-0001 settles the mechanism for optional KB capabilities: file-based modules under `.agents/modules/<name>/`, installed on request, rather than native Claude Code plugins. D-0002 settles the design of the first such module (`software`): gitignored plain clones in `src/`, `src/` as evidence rather than a cascade layer, OpenSpec at both KB-root and per-repo levels, hybrid vendoring (own the KB-root layer, depend on OpenSpec per repo, own the bridge), and `implements`/`implemented_by` linking the two spec levels for drift detection. Both indexed; no `decided_by` entity page exists for Michał Kopeć yet.
|
||||
- **Source:** Chat conversation, 2026-09-20 — `ckb-decide`.
|
||||
---
|
||||
|
||||
## [2026-09-01 21:05] - [CREATE]
|
||||
- **File Affected:** `wiki/decisions/index.md`, `wiki/decisions/log.md`
|
||||
- **Description:** Created the decision-log scaffold: an index listing every decision by number with its status and one-line summary, the status vocabulary (proposed / accepted / rejected / superseded / reversed), and this log. No decisions recorded yet.
|
||||
- **Source:** Chat conversation requesting a decision log feature.
|
||||
---
|
||||
*(No entries yet.)*
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
type: error-book
|
||||
tldr: Table of known ingest/lint errors, root causes, and the constraints derived from them.
|
||||
last_updated: 2026-07-13
|
||||
last_updated: 2026-09-20
|
||||
---
|
||||
|
||||
# Error Book
|
||||
|
|
|
|||
|
|
@ -1,12 +1 @@
|
|||
{
|
||||
"version": 1,
|
||||
"last_updated": "2026-09-20",
|
||||
"edges": [
|
||||
{
|
||||
"from": "/wiki/decisions/0002-software-module-design.md",
|
||||
"to": "/wiki/decisions/0001-opt-in-file-based-kb-modules.md",
|
||||
"type": "affects",
|
||||
"note": "D-0002 is the first concrete module defined under D-0001's mechanism."
|
||||
}
|
||||
]
|
||||
}
|
||||
{"version": 1, "last_updated": "2026-09-20", "edges": []}
|
||||
|
|
|
|||
71
wiki/log.md
71
wiki/log.md
|
|
@ -1,60 +1,19 @@
|
|||
# Wiki Change Log
|
||||
|
||||
## [2026-09-20 00:00] - [CREATE]
|
||||
- **File Affected:** `wiki/decisions/` (D-0001, D-0002), `wiki/graph/edges.json`
|
||||
- **Description:** See `wiki/decisions/log.md` for decision-record changes on this date. Also created `wiki/graph/edges.json` with its first edge (D-0002 → D-0001, `affects`).
|
||||
- **Source:** Chat conversation, 2026-09-20 — `ckb-decide`.
|
||||
---
|
||||
|
||||
## [2026-09-01 21:05] - [CREATE]
|
||||
- **File Affected:** `wiki/decisions/` (directory)
|
||||
- **Description:** Created the decision-records directory — one numbered, append-only page per decision, recorded and queried by the new `ckb-decide` skill. Its own contents are logged in `wiki/decisions/log.md`.
|
||||
- **Source:** Chat conversation requesting a decision log feature.
|
||||
---
|
||||
|
||||
## [2026-09-01 21:05] - [UPDATE]
|
||||
- **File Affected:** `wiki/index.md`
|
||||
- **Description:** Added the Decisions routing row and a "Decision Records" section, and bumped `kb_schema_version` from `1.3` to `1.4` — a minor bump for the additive `decisions/` scaffold and the optional `status`/`decided_on`/`decided_by`/`affects`/`review_on` fields on `type: decision` pages. No existing field or convention changed meaning.
|
||||
- **Source:** Chat conversation requesting a decision log feature.
|
||||
---
|
||||
|
||||
## [2026-09-01 21:05] - [UPDATE]
|
||||
- **File Affected:** `wiki/overview.md`
|
||||
- **Description:** Documented `wiki/decisions/` in the directory tree, added a "Decision Records" section covering the append-only rule and the decision-specific frontmatter, and listed `decisions/` among the recursive indexes.
|
||||
- **Source:** Chat conversation requesting a decision log feature.
|
||||
---
|
||||
|
||||
## [2026-09-01 21:05] - [UPDATE]
|
||||
- **File Affected:** `wiki/graph/index.md`
|
||||
- **Description:** Documented two new optional edge types, `decided_by` (decision -> person) and `affects` (decision -> constrained entity), so "who decided X" and "what decisions touch Y" become direct graph lookups.
|
||||
- **Source:** Chat conversation requesting a decision log feature.
|
||||
---
|
||||
|
||||
- See wiki/decisions/log.md for decision-record changes on this date.
|
||||
|
||||
## [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).
|
||||
|
||||
Each entry uses 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.
|
||||
---
|
||||
```
|
||||
|
||||
Changes to pages under `wiki/decisions/` live in `wiki/decisions/log.md`
|
||||
instead, per the Recursive Index & Log Convention.
|
||||
|
||||
*(No entries yet.)*
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
type: overview
|
||||
tldr: High-level map of the cascade knowledge base's directory structure, frontmatter schema, and layering rules.
|
||||
last_updated: 2026-09-01
|
||||
last_updated: 2026-09-20
|
||||
---
|
||||
|
||||
# Knowledge Base Overview
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@ 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
|
||||
last_updated: 2026-09-20
|
||||
freshness_window_days: 30
|
||||
retention: medium
|
||||
---
|
||||
|
|
|
|||
|
|
@ -1,57 +0,0 @@
|
|||
## 2026-07-29 22:08 CEST
|
||||
|
||||
- Compared Cerebras' "How We Built Our Knowledge Base" concept against the current local Cascade KB scaffold.
|
||||
- Read `wiki/index.md`, `wiki/overview.md`, `wiki/entities/index.md`, and `wiki/graph/index.md`; found the wiki currently covers cascade layering, schema, lazy indexes, empty entity pages, and empty graph scaffolding.
|
||||
- User requested only a list of ideas not currently covered but compatible with a local-first wiki that does not require dedicated user software; no wiki implementation was performed.
|
||||
- Noted existing unsynchronized working-tree state from session start: deleted `.claude/skills` and typechanged `CLAUDE.md`.
|
||||
|
||||
## 2026-07-29 22:10 CEST
|
||||
|
||||
- User asked to commit changes.
|
||||
- Checked working-tree status before committing; planned to include the current tracked changes plus this workload summary in a single git commit.
|
||||
|
||||
## 2026-07-29 22:17 CEST
|
||||
|
||||
- User asked again to commit changes.
|
||||
- Checked working-tree status; found deletions for `CLAUDE.md`, `.claude/skills/export-okf/SKILL.md`, and `.claude/skills/sync-changes/SKILL.md`.
|
||||
- Planned to commit the current working tree, including this session note.
|
||||
|
||||
## 2026-07-29 22:23 CEST
|
||||
|
||||
- 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.
|
||||
|
|
@ -1,29 +0,0 @@
|
|||
## 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.
|
||||
|
|
@ -1,45 +0,0 @@
|
|||
## 2026-09-01 20:25 CEST
|
||||
|
||||
- Ran `ckb-sync-changes`: committed a local `workload/2026-07-29_summary.md` edit, merged 4 commits from `origin/main` (one conflict in that file, resolved by keeping the remote superset), pushed; `origin/main` now at `8174a54`.
|
||||
- Updated `.agents/skills/ckb-init/SKILL.md` so init can pull the template repo into a scratch folder instead of only copying from the local working tree:
|
||||
- New Step 3 "Resolve the template source" (shallow clone of the canonical repo or a user-supplied fork/mirror URL vs. the local working tree), with scratch-path guidance and an explicit rule against cloning into the target itself.
|
||||
- New Step 11 "Initialize the new KB's own git history (ask first)"; report step now names the template source and git-init outcome.
|
||||
- Fixed drift while there: skill list (`ckb-quiz` typo, added `ckb-retrieve`/`ckb-index-external`), `kb_schema_version` no longer hard-coded to 1.1, `wiki/projects/` and `wiki/query-gaps.md` added to the scaffold, `.gitignore` snapshot refreshed with the connector `libs/` rules.
|
||||
- Added clone-related edge cases (clone failure with no local fallback, clone-in-place request, target already a git repo, stale scratch dir).
|
||||
- Propagated the change to `AGENTS.md` skill routing table and `MANUAL.md`/`MANUAL.pl.md` (prose + "say this" tables).
|
||||
- Bumped root `VERSION` 1.3.0 → 1.4.0 (template/tooling layer); `wiki/index.md` `kb_schema_version` stays 1.3 — no wiki content contract change.
|
||||
|
||||
## 2026-09-01 20:35 CEST
|
||||
|
||||
- User asked for a review of the skill set with a proposed model per skill.
|
||||
- Reviewed all 13 `.agents/skills/ckb-*` skills (plus the 7 personal skills under `~/.claude/skills/`) and classified each by reasoning load vs. mechanical load.
|
||||
- Proposal: Opus 5 for `ckb-ingest`, `ckb-retrieve`, `ckb-upgrade`, `ckb-project-summary`, `ckb-teach-me`; Sonnet 5 for `ckb-index-external`, `ckb-lint`, `ckb-init`, `ckb-sync-changes`, `ckb-export-okf`, `ckb-onboard-me`, `ckb-quiz`; Haiku 4.5 for `ckb-export-starlight` (script-driven).
|
||||
- Noted that SKILL.md frontmatter carries only `name`/`description` here and Claude Code skills have no `model` field — model choice is per-session (`/model`) or per-subagent, so applying the proposal means either switching model before invoking or wrapping a skill in a subagent definition with `model:` frontmatter.
|
||||
- Also flagged: `ckb-export-okf` does its page transform by hand while `ckb-export-starlight` delegates to a Python script — the OKF one is the obvious candidate to scriptify (and would then drop to Haiku).
|
||||
- No files changed by this review.
|
||||
|
||||
## 2026-09-01 20:45 CEST
|
||||
|
||||
- User asked to remove the duplicate personal `quiz` skill and to scriptify the skills whose work is mechanical.
|
||||
- Deleted `~/.claude/skills/quiz/` (byte-identical to `ckb-quiz` apart from the `name:` field and the license footer); a copy was kept in the session scratchpad only.
|
||||
- Scriptified `ckb-export-okf`: added `.agents/skills/ckb-export-okf/scripts/export_okf.py` (stdlib-only, read-only outside its output dir) doing the whole transform — frontmatter remap, wikilink stripping, `/wiki/` link rewriting, index and log regeneration from the tree, plus an OKF conformance pass over its own output. `--check` validates into a temp dir without writing. Verified byte-identical across two runs.
|
||||
- Rewrote `ckb-export-okf/SKILL.md` around the script (run it, relay the report, distinguish `SOURCE ISSUE:` = fix the wiki from `NONCONFORMANT:` = fix the script), keeping the mapping table as reference documentation.
|
||||
- Scriptified the detection half of `ckb-lint`: added `.agents/skills/ckb-lint/scripts/lint_report.py` — strictly read-only, covering checks 1/2/3/4/6/7/8/10 across `wiki/` and every connector-backed `libs/<name>/` (reporting each one's `access:` level). Supersession (5), error-book (9), and every auto-fix-vs-report decision deliberately stay with the model. Added Step 0 to `ckb-lint/SKILL.md` and rewrote the mechanical checks to describe what the findings mean rather than how to detect them.
|
||||
- Tested the checker against a synthetic tree covering unparseable frontmatter, missing `type`, stale/low-confidence/archive-candidate pages, orphans, dangling graph edges, missing index entries, a change double-logged in root and subdirectory logs, and an invalid `source.yaml`. Against the real wiki it finds one genuine issue: `wiki/query-gaps.md` is 4 days past its 30-day freshness window.
|
||||
- Propagated to `README.md`/`README.pl.md` (OKF section now describes the script), `MANUAL.md`/`MANUAL.pl.md` (Lint section notes the read-only checker), and `ckb-init` (skill-set copy now names all three support scripts).
|
||||
- Bumped root `VERSION` 1.4.0 → 1.5.0 (template/tooling layer); wiki `kb_schema_version` stays 1.3 — no content contract change.
|
||||
- Decided against scriptifying anything else: `ckb-init`/`ckb-upgrade` are interactive and decision-heavy, and the rest (`ingest`, `retrieve`, `project-summary`, `teach-me`, `onboard-me`, `quiz`) are judgment work with no fixed ruleset to encode.
|
||||
|
||||
## 2026-09-01 21:10 CEST
|
||||
|
||||
- User asked for a decision-log feature: record decisions with who/when/supersession and query them back.
|
||||
- Designed decisions as their own page kind rather than entity pages, because a decision is a point-in-time record with a lifecycle, not a description that gets rewritten as understanding improves. Core rule: **decision pages are append-only** — a changed mind is a new decision superseding the old one, with the old page's context and rationale left intact.
|
||||
- Wiki layer: created `wiki/decisions/` with `index.md` (status vocabulary: proposed / accepted / rejected / superseded / reversed) and its own `log.md`. Pages are `NNNN-slug.md`, numbered from 0001, numbers never reused.
|
||||
- Schema: `type: decision` adds `status`, `decided_on`, `decided_by`, and optional `affects` / `review_on`; the existing `supersedes`/`superseded_by` pair carries decision history (must be set on both sides). Bumped `kb_schema_version` 1.3 → 1.4 (additive) and root `VERSION` 1.5.0 → 1.6.0.
|
||||
- New skill `ckb-decide` owns both halves: recording (collect facts, ask for gaps in one round rather than an interview, check for a decision it supersedes, allocate the number, write page, update index + graph edges + logs) and lookup (index first, read superseded chains as history, answer with who/when/status attached, never reconstruct an unrecorded decision).
|
||||
- `ckb-lint` now checks decision structure mechanically via `lint_report.py`: status vocabulary, `decided_on` where the status implies one, `decided_by` present (`unknown` counts), resolvable `affects` targets, two-sided supersession, `superseded`/`reversed` matched by a `superseded_by`, unique four-digit numbers, and overdue `review_on`. The semantic call — whether one decision genuinely replaces another — stays with the model.
|
||||
- `ckb-ingest` now routes decisions found in raw material to `ckb-decide`'s format, with explicit guardrails against filing a proposal as accepted or guessing a decider. `ckb-retrieve` gained `wiki/decisions/index.md` as cascade step 4 with a handoff rule.
|
||||
- Graph gained `decided_by` (decision → person) and `affects` (decision → constrained entity) edge types.
|
||||
- Docs updated in both languages (README/README.pl feature + skill sections, MANUAL/MANUAL.pl new §2.D walkthrough and "say this" table rows, ownership table row noting the append-only convention), plus `ckb-init` (scaffold + skill list). Also fixed five stale `cbk-quiz` path references left from the upstream rename.
|
||||
- End-to-end tested on a scratch copy: a sample decision record passes lint clean and exports to OKF conformantly. That test surfaced a real bug in `export_okf.py` — a Rule B log line naming a directory (`wiki/decisions/` (directory)) was being turned into a broken intra-bundle link; `files_to_links` now only linkifies entries that name an actual `.md` file.
|
||||
- Fixed a second bug in `lint_report.py`'s `check_graph`: graph edge endpoints are project-root-absolute per Rule C (`/wiki/entities/foo.md`), but the `known` set holds paths relative to `wiki/`, so every conformant edge was reported as pointing at a missing page. The candidate set now also tries the `/wiki/`-stripped form, matching what the decision-record check already did. Root `VERSION` 1.6.0 → 1.6.1 (patch).
|
||||
|
|
@ -1,16 +0,0 @@
|
|||
## 2026-09-02 — Research: can Plane (plane.so) replace Vikunja?
|
||||
|
||||
- User asked whether Plane could replace Vikunja, motivated by (a) preferring Plane's UI and (b) Plane bundling a wiki useful for requirements work.
|
||||
- KB had no prior content on either tool (`grep` over `wiki/ raw/ workload/ linked/ libs/` found nothing) — answered from external web research only, not from the cascade.
|
||||
- Key finding: the self-hosted **Community Edition** is a separate AGPL-3.0 codebase at ~parity with Cloud's *Free* tier, with **no Pro/Business features at all**. The features that motivate the switch are paid:
|
||||
- Workspace **Wiki** → Pro ($6/seat/mo)
|
||||
- **Nested pages** → Business ($13/seat/mo)
|
||||
- Work-item mentions in pages / convert text → work item → Business
|
||||
- **Recurring work items** → Business (Vikunja has these free)
|
||||
- Importers incl. CSV → Cloud/Commercial only (no migration path into CE)
|
||||
- Epics/initiatives, workflows/approvals, custom work-item types, SSO → paid
|
||||
- CE does include project-level Pages (unlimited), five layouts, cycles, modules, intake, estimates, REST API, webhooks, no seat limit.
|
||||
- Vikunja capabilities Plane lacks at any tier found: CalDAV (VTODO) two-way sync, Quick Add Magic.
|
||||
- Ops delta: Vikunja = single Go binary + SQLite, ~1 GB RAM. Plane = ~13 containers, 4 GB RAM minimum / 8 GB recommended, ~1.8 GB idle; CE has no auto-upgrade and documented upgrade breakage (makeplane/plane#8708) plus contradictory seat-limit docs (#9086).
|
||||
- Recommendation given: CE does not deliver the stated wiki benefit and is a net regression for personal task use; if the wiki is the real driver, either pay for Pro/Business, or keep Vikunja and pair it with a dedicated docs layer (this CKB, Outline, or BookStack).
|
||||
- No `wiki/` writes made — offered to record this as a decision (`ckb-decide`) or ingest it as entity pages if the user wants it durable.
|
||||
|
|
@ -1,114 +0,0 @@
|
|||
|
||||
## [2026-09-20] - Design evaluation: software/source-code KB module
|
||||
|
||||
- **Activity:** Evaluated options for making this KB optionally "about software
|
||||
I'm building" — `src/` holding one or more independent code repos, plus
|
||||
OpenSpec-driven iterative development, packaged as an opt-in module.
|
||||
- **Scope:** Read-only inspection of repo layout, `.agents/skills/`, `.gitignore`,
|
||||
`wiki/index.md`, `ckb-init`/`ckb-upgrade`/`ckb-lint`. No files changed.
|
||||
- **User decisions made this turn:**
|
||||
- Module mechanism: files-in-repo module (`.agents/modules/<name>/`), installed
|
||||
on request — not a native Claude Code plugin.
|
||||
- `src/` repos: plain clones, gitignored. No submodules.
|
||||
- Spec location: OpenSpec at *both* levels — KB root (cross-cutting, spans
|
||||
multiple `src/` repos) and inside each `src/<repo>` (travels with the code).
|
||||
- Confirmed preference: `CLAUDE.md` stays a symlink to `AGENTS.md`, and
|
||||
`.claude/skills` stays a symlink to `.agents/skills` (both already correct,
|
||||
tracked as git mode 120000).
|
||||
- **Still open:** whether the module vendors OpenSpec's own workflow skills or
|
||||
depends on an external OpenSpec install (hybrid recommended); schema bump to
|
||||
1.5 for `repository`/`component`/`spec` types.
|
||||
- **Housekeeping:** `workload/2026-09-02_summary.md` still untracked — suggest
|
||||
`ckb-sync-changes`.
|
||||
|
||||
## [2026-09-20] - Decisions D-0001 and D-0002 recorded
|
||||
|
||||
- **Activity:** Ran `ckb-decide`. Recorded the settled design as two decision
|
||||
records rather than one, so the module *mechanism* can be superseded
|
||||
independently of the *software module's* design (e.g. a later switch to
|
||||
submodules touches only D-0002).
|
||||
- **Files:** `wiki/decisions/0001-opt-in-file-based-kb-modules.md`,
|
||||
`wiki/decisions/0002-software-module-design.md`, `wiki/decisions/index.md`,
|
||||
`wiki/decisions/log.md`, `wiki/log.md`, `wiki/graph/edges.json` (created).
|
||||
- **Open:** `kb_schema_version` bump 1.4 → 1.5 not yet applied — it belongs with
|
||||
the module build, not the decision. No entity page exists for Michał Kopeć,
|
||||
so `decided_by` is plain text on both records.
|
||||
- **Not committed.** Say "sync changes" to push.
|
||||
|
||||
## [2026-09-20] - Built the module mechanism and the `software` module
|
||||
|
||||
- **Activity:** Implemented D-0001 and D-0002.
|
||||
- **New — core (always loaded):** `.agents/skills/ckb-module/SKILL.md` — install,
|
||||
list, uninstall. Owns the root `ckb.yaml` manifest, marker-wrapped patches to
|
||||
`AGENTS.md` and `.gitignore`, and the additive `kb_schema_version` bump.
|
||||
- **New — module payload (inert until installed):** `.agents/modules/software/`
|
||||
with `module.yaml`, `README.md`, `fragments/` (AGENTS routing block, gitignore
|
||||
snippet), `scaffold/` (src README, KB-root `openspec/`), and two skills —
|
||||
`ckb-code-map` (repo → `type: repository`/`component` pages, commit-stamped)
|
||||
and `ckb-spec` (KB-root specs, delegation to OpenSpec per repo, bridge to
|
||||
decisions/entities, four-part drift check).
|
||||
- **Edited core skills for module awareness:** `ckb-lint` (new check 11: stale
|
||||
code maps, spec drift, remote-less repos — report-only, skipped when no
|
||||
module installed), `ckb-sync-changes` (new Step 1b: never stage under `src/`,
|
||||
but do report each clone's state), `ckb-upgrade` (upgrade `.agents/modules/`;
|
||||
never delete a skill absent upstream without checking `ckb.yaml`), `ckb-init`
|
||||
(copy the module catalogue, install nothing).
|
||||
- **`AGENTS.md`:** new "Optional Modules" subsection in §1, module-schema note
|
||||
in §2, `ckb-module` routing row + rule in §3. `CLAUDE.md` inherits via symlink.
|
||||
- **`VERSION`:** 1.6.1 → 1.7.0 (template/tooling). `kb_schema_version` stays
|
||||
`1.4` — deliberately: 1.5 arrives only when a module requiring it is installed.
|
||||
- **Verified:** `.claude/skills` lists 15 skills including `ckb-module` and
|
||||
*excluding* `ckb-code-map`/`ckb-spec` — the opt-in isolation works. `ckb.yaml`
|
||||
absent = nothing installed. Lint clean apart from a pre-existing
|
||||
`query-gaps.md` freshness finding.
|
||||
- **Not done:** the `software` module is built but **not installed** here.
|
||||
- **Not committed.** Say "sync changes" to push.
|
||||
|
||||
## [2026-09-20] - OpenSpec user guides (EN + PL)
|
||||
|
||||
- **New:** `OPENSPEC.md` and `OPENSPEC.pl.md` — human-facing guides to adding
|
||||
OpenSpec and using it with this wiki, matching the existing
|
||||
README/MANUAL `.md` + `.pl.md` convention and cross-linked both ways.
|
||||
- **Verified against upstream docs, not written from memory:** Node 20.19.0+,
|
||||
`npm install -g @fission-ai/openspec@latest`, `openspec init/update/list/show/
|
||||
validate/archive/status/view`, and the `/opsx:propose|apply|archive` loop.
|
||||
- **Key finding worth the research:** `openspec init` writes into
|
||||
`.claude/skills/` and adds marker blocks to `AGENTS.md`/`CLAUDE.md`. In this
|
||||
repo `.claude/skills` → `.agents/skills` and `CLAUDE.md` → `AGENTS.md` are
|
||||
symlinks, so running `init` at the KB root would inject OpenSpec's per-repo
|
||||
files into the KB's own skill set and system prompt. Documented as a hard
|
||||
"never" in both guides *and* added as a rule inside `ckb-spec`, so the agent
|
||||
refuses it rather than running and cleaning up.
|
||||
- **Also:** README.md / README.pl.md now point at the guides; module README links
|
||||
them too.
|
||||
- **Not committed.** Say "sync changes" to push.
|
||||
|
||||
## [2026-09-20] - Added `ckb-reset` (destructive template reset)
|
||||
|
||||
- **New:** `.agents/skills/ckb-reset/SKILL.md` — empties the KB back to the
|
||||
scaffold `ckb-init` Step 8 defines, so a working KB can be turned back into a
|
||||
distributable template. Routed in `AGENTS.md` §3. Invocable as `/ckb-reset`.
|
||||
- **Safety design (the point of the skill):** git restore-point check first and a
|
||||
refusal to run on a dirty tree without override; six opt-in scope tiers with
|
||||
`linked/`, `libs/` and installed modules defaulting to *no*; a counted
|
||||
inventory shown *before* asking; a typed-phrase confirmation that is
|
||||
re-requested whenever scope changes; post-reset lint verification before
|
||||
reporting success; `src/` excluded unconditionally, even with confirmation.
|
||||
- **Deliberate exception to Rule D:** `ckb-reset` does not append a workload
|
||||
summary — it would be the first entry in a directory it just emptied. The skill
|
||||
says so in its report so it doesn't read as a bug.
|
||||
- **Fixed while here:** `wiki/graph/edges.json` was missing the `version` and
|
||||
`last_updated` keys the `ckb-init` scaffold specifies. Now conformant.
|
||||
- **Not committed.** Say "sync changes" to push.
|
||||
|
||||
## [2026-09-20] - Documented `ckb-reset` in both manuals
|
||||
|
||||
- **`MANUAL.md` / `MANUAL.pl.md`:** new subsection in §3 ("Starting over:
|
||||
resetting to a clean template" / "Zaczynanie od zera: reset do czystego
|
||||
szablonu") covering the five-stage safety flow, the six scope tiers, what is
|
||||
restored, what is never touched (`src/`, template layer), and the deliberate
|
||||
Rule D exception. Plus a row in each §8 quick-reference table, marked
|
||||
destructive.
|
||||
- **Placement rationale:** §3 "Keeping it tidy" rather than §1, because reset is
|
||||
a maintenance operation on an existing KB; §1 is about creating one.
|
||||
- **Not committed.** Say "sync changes" to push.
|
||||
Loading…
Add table
Reference in a new issue