From c998489c9a79c9962511f6105a6f0ed2e553a69b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Kope=C4=87?= Date: Sun, 20 Sep 2026 17:59:14 +0200 Subject: [PATCH] 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) --- .../0001-opt-in-file-based-kb-modules.md | 78 ------------ wiki/decisions/0002-software-module-design.md | 113 ----------------- wiki/decisions/index.md | 3 +- wiki/decisions/log.md | 14 +-- wiki/error-book.md | 2 +- wiki/graph/edges.json | 13 +- wiki/log.md | 71 +++-------- wiki/overview.md | 2 +- wiki/query-gaps.md | 2 +- workload/2026-07-29_summary.md | 57 --------- workload/2026-07-30_summary.md | 29 ----- workload/2026-09-01_summary.md | 45 ------- workload/2026-09-02_summary.md | 16 --- workload/2026-09-20_summary.md | 114 ------------------ 14 files changed, 21 insertions(+), 538 deletions(-) delete mode 100644 wiki/decisions/0001-opt-in-file-based-kb-modules.md delete mode 100644 wiki/decisions/0002-software-module-design.md delete mode 100644 workload/2026-07-29_summary.md delete mode 100644 workload/2026-07-30_summary.md delete mode 100644 workload/2026-09-01_summary.md delete mode 100644 workload/2026-09-02_summary.md delete mode 100644 workload/2026-09-20_summary.md diff --git a/wiki/decisions/0001-opt-in-file-based-kb-modules.md b/wiki/decisions/0001-opt-in-file-based-kb-modules.md deleted file mode 100644 index 98b97de..0000000 --- a/wiki/decisions/0001-opt-in-file-based-kb-modules.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -type: decision -tldr: Optional KB capabilities ship as file-based modules under `.agents/modules//`, 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//` 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`. diff --git a/wiki/decisions/0002-software-module-design.md b/wiki/decisions/0002-software-module-design.md deleted file mode 100644 index c4569ae..0000000 --- a/wiki/decisions/0002-software-module-design.md +++ /dev/null @@ -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//` 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//` -(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/` → 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`. diff --git a/wiki/decisions/index.md b/wiki/decisions/index.md index 87541ee..da5c1b7 100644 --- a/wiki/decisions/index.md +++ b/wiki/decisions/index.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//`, 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 diff --git a/wiki/decisions/log.md b/wiki/decisions/log.md index f28e053..8f75e25 100644 --- a/wiki/decisions/log.md +++ b/wiki/decisions/log.md @@ -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//`, 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.)* diff --git a/wiki/error-book.md b/wiki/error-book.md index 43b80ea..4e7581d 100644 --- a/wiki/error-book.md +++ b/wiki/error-book.md @@ -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 diff --git a/wiki/graph/edges.json b/wiki/graph/edges.json index b283ec2..bd5a9ad 100644 --- a/wiki/graph/edges.json +++ b/wiki/graph/edges.json @@ -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": []} diff --git a/wiki/log.md b/wiki/log.md index 53f22a4..d5e5584 100644 --- a/wiki/log.md +++ b/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.)* diff --git a/wiki/overview.md b/wiki/overview.md index ddf8373..ca573b3 100644 --- a/wiki/overview.md +++ b/wiki/overview.md @@ -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 diff --git a/wiki/query-gaps.md b/wiki/query-gaps.md index 88b3c98..a0bd4a0 100644 --- a/wiki/query-gaps.md +++ b/wiki/query-gaps.md @@ -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 --- diff --git a/workload/2026-07-29_summary.md b/workload/2026-07-29_summary.md deleted file mode 100644 index 39344e8..0000000 --- a/workload/2026-07-29_summary.md +++ /dev/null @@ -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. diff --git a/workload/2026-07-30_summary.md b/workload/2026-07-30_summary.md deleted file mode 100644 index 927e233..0000000 --- a/workload/2026-07-30_summary.md +++ /dev/null @@ -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. diff --git a/workload/2026-09-01_summary.md b/workload/2026-09-01_summary.md deleted file mode 100644 index b20ad45..0000000 --- a/workload/2026-09-01_summary.md +++ /dev/null @@ -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//` (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). diff --git a/workload/2026-09-02_summary.md b/workload/2026-09-02_summary.md deleted file mode 100644 index 956f61a..0000000 --- a/workload/2026-09-02_summary.md +++ /dev/null @@ -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. diff --git a/workload/2026-09-20_summary.md b/workload/2026-09-20_summary.md deleted file mode 100644 index 2a73af0..0000000 --- a/workload/2026-09-20_summary.md +++ /dev/null @@ -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//`), 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/` (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.