diff --git a/dist-hermes/research/setup-wiki/README.md b/dist-hermes/research/setup-wiki/README.md index 7d2cedb..5ba64d8 100644 --- a/dist-hermes/research/setup-wiki/README.md +++ b/dist-hermes/research/setup-wiki/README.md @@ -25,7 +25,7 @@ Canonical layout reference: | Mode | Trigger | Action | |---|---|---| | **greenfield** | No `.wiki/` exists | Create the canonical layout from scratch. | -| **noop** | `.wiki/` already canon (all five canon files + four content dirs) | Report and exit — no writes. | +| **noop** | `.wiki/` already canon (all five canon files + six content dirs) | Report and exit — no writes. | | **migrate** | `.wiki/` exists with non-canon files (`SUMMARY.md`, `WORKFLOW.md`, `source/`) or missing canon files | Move legacy files (e.g. `source/*.md` → `concepts/*.md` via `git mv`), create missing canon files, drop a timestamped `.backup-*/` next to it. | Migration **does not auto-rewrite** existing concept content — it only moves @@ -45,10 +45,12 @@ job. ├── entities/ ← entity pages (people, services, modules) ├── concepts/ ← design decisions, recurring ideas ├── packages/ ← code packages -└── sources/ ← one summary per ingested source +├── sources/ ← one summary per ingested source +├── contradictions/ ← surfaced tensions worth tracking long-term +└── open-questions/ ← unresolved questions raised during ingest/query ``` -The four content directories each get a `.gitkeep` so git tracks them. +The six content directories each get a `.gitkeep` so git tracks them. ## Hard rules diff --git a/dist-hermes/research/setup-wiki/SKILL.md b/dist-hermes/research/setup-wiki/SKILL.md index bd343a2..f93f77c 100644 --- a/dist-hermes/research/setup-wiki/SKILL.md +++ b/dist-hermes/research/setup-wiki/SKILL.md @@ -1,7 +1,7 @@ --- name: setup-wiki -version: 1.0.0 -description: Creates or migrates a project's `.wiki/` to the canonical Karpathy LLM Wiki layout — `CLAUDE.md` schema, `index.md`, `log.md`, `overview.md`, `raw/README.md`, plus empty `entities/`, `concepts/`, `packages/`, `sources/`. Use when the user says "set up wiki", "init wiki", "настрой вики", "инициализируй вики", "create wiki", "migrate wiki to canon", "wiki сломана", "wiki layout broken", or whenever `using-wiki` detects a missing or non-canonical `.wiki/`. Two modes — greenfield (no wiki) and migrate (existing non-canonical layout). Confirmation gate before writing. Cross-platform. +version: 1.1.0 +description: Creates or migrates a project's `.wiki/` to the canonical Karpathy LLM Wiki layout — `CLAUDE.md` schema, `index.md`, `log.md`, `overview.md`, `raw/README.md`, plus empty `entities/`, `concepts/`, `packages/`, `sources/`, `contradictions/`, `open-questions/`. Use when the user says "set up wiki", "init wiki", "настрой вики", "инициализируй вики", "create wiki", "migrate wiki to canon", "wiki сломана", "wiki layout broken", or whenever `using-wiki` detects a missing or non-canonical `.wiki/`. Two modes — greenfield (no wiki) and migrate (existing non-canonical layout). Confirmation gate before writing. Cross-platform. --- # setup-wiki @@ -35,7 +35,7 @@ The procedure mutates the project's `.wiki/`. **Pause for explicit confirmation Inspect `.wiki/`: - **No `.wiki/`** → mode = `greenfield`. -- **`.wiki/` exists AND has all of:** `CLAUDE.md`, `index.md`, `log.md`, `overview.md`, `raw/README.md`, plus directories `entities/`, `concepts/`, `packages/`, `sources/` → mode = `noop` (already canon; report and exit). +- **`.wiki/` exists AND has all of:** `CLAUDE.md`, `index.md`, `log.md`, `overview.md`, `raw/README.md`, plus directories `entities/`, `concepts/`, `packages/`, `sources/`, `contradictions/`, `open-questions/` → mode = `noop` (already canon; report and exit). - **`.wiki/` exists but missing some canon files OR has non-canon files** (`SUMMARY.md`, `WORKFLOW.md`, `source/`) → mode = `migrate`. Report findings to the user as a short summary: @@ -56,7 +56,7 @@ Show the plan in one block: Will create .wiki/ with canonical layout: CLAUDE.md (schema), index.md, log.md, overview.md raw/README.md - entities/, concepts/, packages/, sources/ (with .gitkeep) + entities/, concepts/, packages/, sources/, contradictions/, open-questions/ (with .gitkeep) ``` **Migrate:** @@ -65,7 +65,7 @@ Will rename: source/*.md → concepts/*.md (via git mv when in a git repo, plain mv otherwise) Will create: CLAUDE.md, index.md, log.md, overview.md, raw/README.md - entities/, packages/, sources/ (with .gitkeep) + entities/, packages/, sources/, contradictions/, open-questions/ (with .gitkeep) Will delete: SUMMARY.md, WORKFLOW.md, raw/.gitkeep, source/ (after moves) Will not touch existing files in raw/ — they're immutable sources. @@ -101,6 +101,8 @@ The `using-wiki` skill enforces the workflow and file formats. This file overrid - `concepts/` — recurring ideas, design decisions, gotchas. - `packages/` — code packages this project produces or consumes. - `sources/` — one summary page per ingested external doc; carries `ingested:` and `raw_path:`. +- `contradictions/` — surfaced tensions between sources or pages worth tracking long-term; each page cross-links the affected entities/concepts/sources and carries a status (`open` / `resolved` / `accepted-divergence`). +- `open-questions/` — unresolved questions raised during ingest or query that the wiki cannot answer yet; each page cross-links the pages/sources that touch the question and carries a status (`open` / `answered` / `obsolete`). - `overview.md` — single project-wide overview. ## Naming @@ -137,6 +139,14 @@ Catalog of all wiki pages. One line per page, organized by type. Updated on ever ## Sources + + +## Contradictions + + + +## Open Questions + ``` @@ -190,7 +200,7 @@ For large or path-sensitive sources outside the repo, register them here: \`\`\` ``` -**Empty `.gitkeep`** in each of `entities/`, `concepts/`, `packages/`, `sources/` so git tracks the dirs. +**Empty `.gitkeep`** in each of `entities/`, `concepts/`, `packages/`, `sources/`, `contradictions/`, `open-questions/` so git tracks the dirs. ### Phase 4b — Migrate @@ -198,7 +208,7 @@ If migrate mode: combine creation (for missing canon files) with file moves (for ```bash # 1. Create missing directories -mkdir -p .wiki/concepts .wiki/entities .wiki/packages .wiki/sources +mkdir -p .wiki/concepts .wiki/entities .wiki/packages .wiki/sources .wiki/contradictions .wiki/open-questions # 2. Move source/* → concepts/* (use git mv if in a git repo) if git rev-parse --git-dir >/dev/null 2>&1; then @@ -215,8 +225,8 @@ rmdir .wiki/source 2>/dev/null # 3. Create missing canon files (CLAUDE.md, index.md, log.md, overview.md, raw/README.md) # using the templates from Phase 4a, but skip files that already exist. -# 4. Add .gitkeep to entities/, packages/, sources/ -touch .wiki/entities/.gitkeep .wiki/packages/.gitkeep .wiki/sources/.gitkeep +# 4. Add .gitkeep to entities/, packages/, sources/, contradictions/, open-questions/ +touch .wiki/entities/.gitkeep .wiki/packages/.gitkeep .wiki/sources/.gitkeep .wiki/contradictions/.gitkeep .wiki/open-questions/.gitkeep ``` For migrated `concepts/*.md` pages, **do not rewrite their content** — just prepend a minimal frontmatter if missing: @@ -242,7 +252,7 @@ Append a line to `log.md`: After writes, confirm: - All canon files exist: `CLAUDE.md`, `index.md`, `log.md`, `overview.md`, `raw/README.md`. -- Four content directories exist (with at least `.gitkeep` or content). +- Six content directories exist (`entities/`, `concepts/`, `packages/`, `sources/`, `contradictions/`, `open-questions/`) — with at least `.gitkeep` or content. - No leftover non-canon files (`SUMMARY.md`, `WORKFLOW.md`, `source/`). - For migrate mode: every migrated page has frontmatter with `type: concept`. @@ -255,7 +265,7 @@ Print final state: ``` ✅ Wiki ready at .wiki/. Mode: greenfield | migrate - Files: 5 canon + 4 dirs + N migrated concept pages + Files: 5 canon + 6 dirs + N migrated concept pages Backup (if migrate): .wiki/.backup-/ Next steps for the user: diff --git a/dist-hermes/research/using-wiki/README.md b/dist-hermes/research/using-wiki/README.md index f859dd2..09d9170 100644 --- a/dist-hermes/research/using-wiki/README.md +++ b/dist-hermes/research/using-wiki/README.md @@ -86,7 +86,7 @@ line to `log.md` with the findings. ```yaml --- title: Человекочитаемое имя -type: entity | concept | package | source | overview +type: entity | concept | package | source | contradiction | open-question | overview tags: [short, tokens] sources: [../sources/foo.md, ../sources/bar.md] updated: 2026-04-21 @@ -94,13 +94,16 @@ updated: 2026-04-21 ``` Source pages also carry `ingested: YYYY-MM-DD` and `raw_path: ../raw/...`. +Contradiction pages also carry `status: open | resolved | accepted-divergence` and `affects: [../entities/x.md, ../concepts/y.md]`. +Open-question pages also carry `status: open | answered | obsolete` and `touches: [../entities/x.md, ../sources/z.md]`. ### File naming - `kebab-case.md`, **Latin only**. Transliterate Cyrillic / non-Latin in filenames; keep the original title in H1 + frontmatter. - `entities/.md`, `concepts/.md`, `packages/.md` - (no `@org/` prefix), `sources/.md`. + (no `@org/` prefix), `sources/.md`, `contradictions/.md`, + `open-questions/.md`. ### `log.md` — append-only, grep-parseable diff --git a/dist-hermes/research/using-wiki/SKILL.md b/dist-hermes/research/using-wiki/SKILL.md index cd986db..64d1f26 100644 --- a/dist-hermes/research/using-wiki/SKILL.md +++ b/dist-hermes/research/using-wiki/SKILL.md @@ -1,6 +1,6 @@ --- name: using-wiki -version: 1.0.0 +version: 1.1.0 description: Policy skill for working with an existing `.wiki/` (Karpathy LLM Wiki pattern). Use when the user asks to ingest a document, answer from the wiki, lint/health-check it, or says "use project wiki", "обнови вики", "проверь вики", "запроси вики", "заингесть", "query the wiki". Also use when modifying any file under `.wiki/` — the workflow and formats below are mandatory, and project-specific conventions live in `.wiki/CLAUDE.md`. If `.wiki/` is missing or non-canonical, delegate to `setup-wiki` first (it has its own confirmation gate). Renamed from `wiki-maintainer` at v1.0.0. --- @@ -10,9 +10,9 @@ description: Policy skill for working with an existing `.wiki/` (Karpathy LLM Wi ## Prerequisites -This skill assumes the project has a canonical `.wiki/` layout: `CLAUDE.md` (schema), `index.md` (catalog), `log.md` (op log), `overview.md`, `raw/README.md`, and the four content directories `entities/`, `concepts/`, `packages/`, `sources/`. +This skill assumes the project has a canonical `.wiki/` layout: `CLAUDE.md` (schema), `index.md` (catalog), `log.md` (op log), `overview.md`, `raw/README.md`, and the six content directories `entities/`, `concepts/`, `packages/`, `sources/`, `contradictions/`, `open-questions/`. -If `.wiki/` is **missing**, or the layout is **non-canonical** (e.g. `SUMMARY.md` instead of `index.md`, or `source/` instead of `concepts/`/`sources/`) — invoke the `setup-wiki` skill first. It detects the situation (greenfield vs migrate) and creates or migrates the structure with its own confirmation gate. Only after `setup-wiki` finishes should this skill proceed with the operations below. +If `.wiki/` is **missing**, or the layout is **non-canonical** (e.g. `SUMMARY.md` instead of `index.md`, or `source/` instead of `concepts/`/`sources/`, or `contradictions/`/`open-questions/` directories are absent) — invoke the `setup-wiki` skill first. It detects the situation (greenfield vs migrate) and creates or migrates the structure with its own confirmation gate. Only after `setup-wiki` finishes should this skill proceed with the operations below. ## Three layers (do not blur) @@ -70,7 +70,7 @@ Append one line to `log.md` summarizing the findings. ```yaml --- title: Человекочитаемое имя -type: entity | concept | package | source | overview +type: entity | concept | package | source | contradiction | open-question | overview tags: [short, tokens] sources: [../sources/foo.md, ../sources/bar.md] updated: 2026-04-21 @@ -79,10 +79,14 @@ updated: 2026-04-21 Source pages also carry `ingested: YYYY-MM-DD` and `raw_path: ../raw/...`. +Contradiction pages also carry `status: open | resolved | accepted-divergence` and `affects: [../entities/x.md, ../concepts/y.md]`. + +Open-question pages also carry `status: open | answered | obsolete` and `touches: [../entities/x.md, ../sources/z.md]`. + ### File naming - `kebab-case.md`, **Latin only**. Transliterate Cyrillic / other scripts in filenames (`план переписывания` → `ozon-client-rewrite.md`). Keep the original title in the H1 and frontmatter. -- `entities/.md`, `concepts/.md`, `packages/.md` (no `@org/` prefix), `sources/.md`. +- `entities/.md`, `concepts/.md`, `packages/.md` (no `@org/` prefix), `sources/.md`, `contradictions/.md`, `open-questions/.md`. ### `log.md` — append-only, grep-parseable @@ -98,7 +102,7 @@ Parseable with: `grep "^## \[" .wiki/log.md | tail -20`. ### `index.md` -Catalog, not narrative. One line per page: `- [Title](path) — hook.` Sections by type (entities / concepts / packages / sources). Update on every ingest. +Catalog, not narrative. One line per page: `- [Title](path) — hook.` Sections by type (entities / concepts / packages / sources / contradictions / open-questions). Update on every ingest. ### Cross-references