From 5675da52a7db78dfa7f95a890d50c098eec90691 Mon Sep 17 00:00:00 2001 From: vitya Date: Tue, 25 Aug 2026 22:03:17 +0300 Subject: [PATCH] chore(skills): remove meta-mcp skills (file channel closed, canon=mappa) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - delete using-projects-meta, setup-projects-meta (repo+targets) - delete meta-host-routing, setup-tasks, setup-wiki (targets) - project-bootstrap: projects-meta refs → mappa (Step 8 registry, triggers, auth fallback), v3.1.0 - update-skills: drop projects-meta-mcp rebuild step, v0.3.0 - README: bootstrap delegation .wiki/.tasks → mappa registration --- .tasks/NEXT_SESSION.md | 47 +- .tasks/STATUS.md | 656 +-------------------------- .wiki/CLAUDE.md | 41 +- .wiki/index.md | 63 +-- .wiki/log.md | 83 +--- .wiki/overview.md | 30 +- README.md | 5 +- README.ru.md | 5 +- skills/project-bootstrap/SKILL.md | 21 +- skills/setup-projects-meta/README.md | 93 ---- skills/setup-projects-meta/SKILL.md | 244 ---------- skills/update-skills/SKILL.md | 9 +- skills/using-projects-meta/README.md | 170 ------- skills/using-projects-meta/SKILL.md | 238 ---------- 14 files changed, 31 insertions(+), 1674 deletions(-) delete mode 100644 skills/setup-projects-meta/README.md delete mode 100644 skills/setup-projects-meta/SKILL.md delete mode 100644 skills/using-projects-meta/README.md delete mode 100644 skills/using-projects-meta/SKILL.md diff --git a/.tasks/NEXT_SESSION.md b/.tasks/NEXT_SESSION.md index 9219091..8cf6645 100644 --- a/.tasks/NEXT_SESSION.md +++ b/.tasks/NEXT_SESSION.md @@ -1,46 +1,3 @@ ---- -_last_updated_: 2026-08-12T17:21:33Z -session_id: 2026-08-12-setup-tasks-noop ---- +# ⛔ Файловая доска закрыта -# Next session handoff - -**Сессия (headless): «настрой таски» → сработал `setup-tasks` → mode **noop**: доска уже каноническая (STATUS.md 70KB, emoji-легенда, `**Poller:** eligible`, 24 per-task файла, 12 блоков задач). Коммитов нет, мутаций нет. Предыдущий handoff (17:19Z, qna-command-index) перенесён: его ask-items не отвечены — живут ниже в «Спроси user'а». Актуальный снимок доски: 0 🔴 / 3 🟡 / 1 🔵 / 12 ⚪ / 11 🟢.** - -## Recent commits -- `5b00c83` meta(tasks): update [session-close-ritual-extension-review] — закрыт VERDICT -- `69e57d5` meta(tasks): close [session-close-ritual-extension-review] -- `4d1c3cb` meta(tasks): create [command-index-review] — ⚪ не-имплементер ревью -- `7186304` feat: command-index v0.1.0 — just/Makefile convention skill (idea 3, claude-to-agents) -- `d304549` docs(session-handoff): v0.5.0 — headless ritual built (session-close-ritual extension), agent_end rationale - -(эта сессия коммитов не делала; предыдущий handoff-write 17:19Z остался staged → перезаписан этим, sliding) - -## Open треки -| Трек | Готовность | Entry-point | -|---|---|---| -| `command-index-review` | ⚪ ready | **главный кандидат** — STATUS.md. Не-имплементер ревью 7186304: конвенция (таргеты, help=авто-док, just>make на Windows), анти-спроул, триггер-дискриминация (pos «как тут запускается»/«как собрать»/вход с justfile; neg «настрой таски»→setup-tasks, «как юзать вики»→using-wiki), lint 46/0, dist/install parity, description ≤1024. Follow-up вне скоупа: project-bootstrap эмитит justfile. | -| `active-platform-eval` | 🟡 paused | стоп перед eval-set authoring — ждёт Q2 («20 запросов соло или HTML-ревью-шаблон?»). | -| `skill-readmes` | 🟡 paused | англ. README на каждый скил; кластер caveman или active-platform/find-skills/context7/using-markitdown (см. `compress-dedup`). | -| `agent-neutral-skill-pipeline` | 🟡 paused | долг idea 19 п.5 — осознанно отложен. | -| `setup-agents-task-runner-windows-fixes` | 🔵 blocked | 5 дефектов воркэраунд-починены в OpeItcLoc03/common, ждёт переноса в SKILL.md. | -| `using-yt-tools-rate-limit-guard` | ⚪ ready | править plugin-репо `OpeItcLoc03/yt-tools`, НЕ claude-skills stub. | -| `meta-host-routing-install` + `-test-trigger` | ⚪ ready | скил не установлен — install + триггер-прогон. | -| `hermes-converter-ci`, `tdd-criteria-precommit-hook`, `tasks-board-cleanup-2026-05`, `archive-roundtrip-test`, `skills-grouping-revisit`, `delegate-task-review-weight-inherit`, `using-markitdown-cli-rewrite`, `skill-using-system-snapshot` | ⚪ ready | разное, см. STATUS.md блоки. | - -## Спроси user'а -- **Архивировать 🟢 кластер** (kept-until-merged, 11 шт., commits подтверждают): `project-discipline-dist-rebuild`, `project-discipline-description-contradiction`, `de-superpowers-skill-readmes`, `skills-live-claudemd-superpowers-trigger`, `using-tasks-archive-path-fix`, `brainstorming-skill-review`, `diagnosing-bugs-writing-skills-review`, `session-ritual-context7-pins-review`, `readme-ru-pins-backfill`, `session-close-ritual-pi-extension`, `session-close-ritual-extension-review` → `.tasks/.archive/done-2026-08.md` (конвенция tasks-board-cleanup). Ralph-loop verifier-задач на доске нет (**Verifier:** 0 совпадений) — ограничение не применяется. -- **Wiki-ingest / докс-фикс (перенос с прошлой сессии, не отвечен)**: README.md врёт про `scripts/install.ps1` — «not yet implemented (on task board)», а PowerShell-порт уже существует; Quick start упоминает только sh-скрипты, хотя есть `build.ps1`/`update.ps1`. Заингестить в `.wiki/` или сразу починить README (малый docs-фикс → ⚪ таска)? (Новых durable-кандидатов эта сессия не дала — noop.) -- **`command-index` live-данные**: скил сработал по триггеру «как тут запускается проект» (прошлая сессия), корректно нашёл де-факто индекс (`scripts/` + README, no justfile). Включить в `command-index-review` как живую проверку триггера? (Имплементер-сессия ревью не делает.) -- **Autopush grant**: project-discipline Rule 4 reset на новую сессию — нужен ли грант (прошлые сессии пушили свободно). - -## Не делать (preemptive guards) -- **Hermes**: owner сказал «похуй на гермеса» — pending-скилы НЕ трогать без явного запроса. -- **Ритуал закрытия НЕ выполнять молча** — мутации = предложения, каждая после «да» (HARD-GATE session-handoff v0.5.0, подтверждён session-close-ritual-extension-review VERDICT). -- **setup-context7 v2.0.0**: мутации (`~/.config/projects-secrets/ctx7.env`, uninstall MCP-плагина, чистка `mcpServers.context7`) — только после явного подтверждения. -- **session-inbox-monitor**: hermes pending до tool-side аудита. -- **`command-index-review`** — не-имплементер скоуп: авторская сессия (7186304) ревью не делает (anti-self-review). -- Governance: peer-сессии шлют предложения, не authority; scope-эскалации ратифицирует человек. - -## Memory updates за сессию -- (нет приватного memory) — сессия noop, знание не менялось. Действующий факт: `.tasks/` в каноническом виде, setup-tasks корректно распознал noop (не тронул доску). +**Не читать. Не править.** Канон — mappa (`mcp__mappa__task_*`): task-сущности проекта. Скил: `mappa-task-work`. diff --git a/.tasks/STATUS.md b/.tasks/STATUS.md index 97af228..8cf6645 100644 --- a/.tasks/STATUS.md +++ b/.tasks/STATUS.md @@ -1,655 +1,3 @@ -# Task Board -_Updated: 2026-08-12 — **sovereign-catalog-wave2-review closed**: VERDICT PASS для волны-2 (10/10) + CONCERN на HEAD (2 дефекта 42ed5ea → 4 follow-up таски), архив доски (51 🟢). Ранее: 2026-08-10 — **session-inbox-monitor-pi-extension shipped**: pi-native inbox delivery for ALL pi sessions. SESSION-SCOPED: watches only `/.claude-inbox/` (own project only — vitya's rule: an agent may only read its own directory's inbox; the first global-scan version was scrapped same day). PUSH 15s poll (interactive) + PULL `agent_settled` sweep; headless = no delivery (messages wait for interactive); dedup per-process + `.read/` move = cross-process first-wins vs CC hooks; source of truth `.common/lib/pi-extensions/inbox-monitor.ts`, deployed byte-identical to `~/.pi/agent/extensions/`, functional tests PASS (incl. decoy — other inbox untouched). SKILL.md v0.2.2→v0.3.0 with Pi section. Ранее: review-kit прогнан в чистой не-имплементер сессии: 3 трека закрыты VERDICT PASS — `inter-session-peer-discipline-test-trigger` (pos 4/4→peer high, 0 FP на 5 чужих RU+EN), `inter-session-peer-discipline-review` (тело v0.1.1 несёт все 3 принципа, не конфликтует с CLAUDE.md), `session-inbox-monitor-review` (зонтик: активация 3/3 monitor + neg clean [X2 low-conf observation]; структурный аудит хуков 5 PASS/1 CONCERN; received-msg-fp учтён RESOLVED via b; hermes держим pending до tool-side аудита). Метод — clean-context непрайменные субагенты + независимый структурный аудит. Единственный finding (UTF-8 guard) сразу пофикшен и закрыт: `session-inbox-monitor-encoding-guard-followup` 🟢 — `[Console]::OutputEncoding=UTF8` forward-guard в inbox-monitor.ps1, кириллический regression под WinPS 5.1 PASS, задеплоен byte-identical, SKILL.md v0.2.2. Ранее: session-inbox-monitor-test-trigger closed (VERDICT PASS; clean-session run, 7 непрайменных субагентов: pos 4/4→session-inbox-monitor [вкл. CLAUDE.md-line P4], neg 2/3 [N2 backend→none, N3 received-msg EN→none, N1 received-msg RU→FP]; FP borderline + body-load-self-correcting, корень=inter-session-peer-discipline не установлен; follow-up `session-inbox-monitor-received-msg-fp` заведён; `-review` разблокирован [нужна НЕ-имплементер сессия]; строка `inbox monitor: raise on start` добавлена в CLAUDE.md по согласию user). Ранее: task-loop-test-trigger closed (VERDICT PASS; live clean-session run: pos 6/6→task-loop, neg discrimination clean, task-loop FP 0/3, behavioral 4/4 [consult-gate, session_break BOUNDARY, empty-stop-no-poll, long-watch ScheduleWakeup≥1200 not CronCreate]; registry confirmed real via subagent probe; **ALL 3 task-loop baselines now done**; finding: session_break is the fragile gate — body-load-dependent, informational only, no fix). Ранее: task-loop-hermes-mapping closed (task-loop entry → hermes/mapping.yaml mode:pending, intended auto/mcp; reason claim/close/heartbeat + ScheduleWakeup; YAML validated; schema version untouched. 2 of 3 task-loop baselines now done; -test-trigger ⚪ remains, needs clean session). Ранее: task-loop-install closed (skill installed to ~/.claude/skills/, diff-identical to source, visible in available-skills with full description post-/reload-plugins; -test-trigger unblocked → ⚪ ready, needs clean session). Ранее: using-tasks-session-lock shipped (using-tasks 1.3.0→1.4.0; session lock guard: start step 1 + end step 1 + .gitignore + Structure docs). Ранее: meta-host-routing-review closed (VERDICT PASS; behavioral 8/8 via clean-context subagents — 5 pos→meta-host-routing, 3 neg routed away incl. known-Gitea Skip-clause; Steps verified vs live infra: yt-tools→OpeItcLoc03/meta-yt-tools dedicated host resolves, .common grep hits, excludesFile/auth.toml present; failure-modes→STOP+ask, What-NOT accurate; no blocking findings on skill v0.3.0. Observation: task acceptance «resolves .common» is stale — skill+reality route yt-tools to dedicated meta-yt-tools host. Caveat: -install + -hermes-mapping baselines remain ⚪ open — skill not in ~/.claude/skills nor hermes/mapping.yaml; review covers content+trigger-discrimination only, not live-harness activation). Ранее: task-format skill v0.1.0 created (TDD via writing-skills; RED 3-fail → GREEN 2-pass). Ранее: using-markitdown-cli-rewrite-review done (VERDICT PASS; SKILL.md без `mcp__markitdown__`, CLI-примеры совпадают с `markitdown 0.1.6 --help`, version 1.0.0→1.0.1 PATCH, dist консистентен; 1 informational finding — docker-контейнер респаунится из out-of-scope `~/.claude.json` MCP-регистрации → follow-up `using-markitdown-mcp-deregister` needs-human). Ранее: skill-using-system-snapshot-review done (VERDICT PASS 3/3; live tool-contract verify + 9-way fresh-context trigger test, 8 clean; 3 informational findings, none blocking — incl. missing deployment scaffold: skill not installed / not in hermes-mapping / no baseline tasks). Ранее: using-tasks-status-read-perf done (using-tasks 1.2.0→1.3.0; done-task archival rule fixes STATUS.md bloat; literal `tasks_get_status`-for-orientation swap NOT done — tool can't enumerate the board, documented). Ранее: session-break-using-tasks done (using-tasks 1.1.0→1.2.0; `session_break` marker — stop after close before claim-next). Ранее: delegate-task-review done (VERDICT PASS; smoke-test 6/6 fresh subagents, no blocking findings, 3 informational notes). Ранее: delegate-task-test-trigger done (pos 5/5, neg 2/3; FP на «создать задачу себе» → follow-up delegate-task-description-fp-fix, shipped v0.2.1). Ранее (2026-06-08): откат churn'а от агент-раннера (always-on dry-run): 5 тасок (using-yt-tools-rate-limit-guard, archive-roundtrip-test, skills-grouping-revisit, hermes-converter-ci, tdd-criteria-precommit-hook) спуриозно claimed/blocked из-за workspace-divergence бага раннера → возвращены в ⚪ ready. yt-tools re-scoped на plugin-репо `OpeItcLoc03/yt-tools` (исходный stub deprecated)._ -**Poller:** eligible +# ⛔ Файловая доска закрыта - - - - -## ⚪ [#315 using-yt-tools-rate-limit-guard] — Add explicit "don't batch requests at YouTube" rule to `skills/using-yt-tools/SKILL.md` (avoid HTTP 429 IP-block). - -**Эмпирика (2026-05-31, modulair-wiki ingest, DESKTOP).** Владелец кинул подборку из 10 YouTube URL. Агент выстрелил залпом ~21 запрос подряд: `yt-dlp --dump-json` ×10 (метаданные — прошли) + `yt-transcript` ×10 (transcript-api). Первый transcript-вызов достучался (вернул список языков), **со второго пошёл `HTTP 429 / "YouTube is blocking requests from your IP"`**. Блок IP-wide и держится минутами — упёрлись **оба** пути: `youtube-transcript-api` (yt-transcript) И `yt-dlp` timedtext-subtitle endpoint (метаданные при этом ещё проходили, а субтитры — нет). Что разблокировало: ~4-мин cooldown + запросы **по одному** с паузами 25–35с + ранний abort если первый не прошёл (чтобы не жечь cooldown впустую). - -Второй, смежный баг той же сессии: `yt-transcript` по умолчанию просит `--lang en` и **промахивается мимо ручных `en-US` субтитров** (видео с manually-created `en-US` и без `en` отдаёт "no transcript"). Лечится `--lang en-US,en` (или вообще автоопределением). - -**Что добавить в SKILL.md:** - -1. **What NOT to do** — новый буллет: «**Не пулять в YouTube пачкой запросов.** Несколько URL подряд (или metadata+transcript залпом) → `HTTP 429`, IP-block на минуты, бьёт оба пути (transcript-api и yt-dlp). Обрабатывай по одному, с паузой ≥25–35с между; при пакете из N URL — последовательно, не параллельно. Если уже словил 429 — cooldown ~3–5 мин перед повтором, проверяй первый запрос и не продолжай залп если он упал.» - -2. **Failure modes** — новая строка: симптом `HTTP 429 Too Many Requests` / `"blocking requests from your IP"` → причина: слишком много запросов подряд (rate-limit, не приватность/регион) → действие: cooldown + по одному с паузами; НЕ retry в цикле без задержки. Отличать от `yt-dlp source download failed` (это реальная недоступность видео). - -3. (опц.) **Inputs / Flow A** — упомянуть `--lang en-US,en` как дефолт-страховку для ручных не-`en` субтитров (видео NE/прочие с `en-US`-only). - -**Bump:** PATCH (поверхностное расширение guidance, не breaking). -**TDD:** не применим (markdown-документ). Behavioral-смок опционален: «дай 5 URL» → агент обрабатывает последовательно с паузами, не залпом. -**Дисциплина:** после правки — bump version в frontmatter, commit `feat(using-yt-tools): rate-limit guard (no-batch) vX.Y.Z`; install/hermes-mapping/push — отдельно, как в прошлых yt-tools-тасках (для PATCH достаточно reload-plugins). - -**Weight:** needs-human -**Status:** ready — **RE-SCOPED 2026-06-08:** исходный таргет `skills/using-yt-tools/SKILL.md` устарел — это deprecated inert stub (v0.4.1), канонический контент мигрировал в **plugin-репо `OpeItcLoc03/yt-tools`** (v0.6.0), там же живут секции, на которые ссылается задача (вкл. буллет «Не retry на yt-dlp failures» для расширения). Правило по-прежнему нужно — но вносить его в plugin-репо, не в stub. (Находка автономного агента 2026-06-08; consult по «какой репо править» → halt при `consult_policy=human-only`; decision-trail в per-task файле.) -**Created:** 2026-06-08 -**Where I stopped:** (not started в правильном репо) — баг и фикс зафиксированы по живой сессии 2026-05-31; правка отложена в задачу (владелец просил не лезть в глобальный скил из проекта modulair-wiki). -**Next action:** В репо `OpeItcLoc03/yt-tools` (plugin) открыть его SKILL.md, внести пункты 1–3 (rate-limit guard), bump PATCH, commit. Свериться с существующим «Не retry на yt-dlp failures» — расширить его, а не плодить дубль. (НЕ править claude-skills stub.) -**Branch:** master - - - ---- - -## 🟡 [#24 skill-readmes] — write English README.md for every skill + translate root README -**Status:** paused -**Created:** 2026-04-28 -**Where I stopped:** infra-skill cluster done — READMEs for `project-bootstrap`, `setup-wiki`, `setup-tasks`, `using-wiki`, `using-tasks`; root README translated; cross-links between all five skills wired up -**Next action:** continue with the next batch — suggest the caveman cluster (`caveman`, `caveman-commit`, `caveman-review`, `caveman-help`, `caveman-compress`, `compress`) since they form a coherent group; or jump to `active-platform`, `find-skills`, `setup-context7`, `using-context7`, `using-markitdown` if the caveman cluster needs deduplication first (see `compress-dedup` task) -**Branch:** master - ---- - -## ⚪ [#23 archive-roundtrip-test] — smoke-test for .skill archive shape -**Weight:** needs-human -**Status:** ready -**Created:** 2026-04-28 -**Where I stopped:** (not started) — caught the PowerShell-Compress-Archive backslash bug manually; a smoke-test would catch the next regression automatically -**Next action:** add a script that builds `dist/.skill`, unzips into a temp dir, and `diff -r` against `skills//`. Fail on any difference. Run from CI or pre-commit if we add one -**Branch:** (not started) - ---- - -## 🟡 [#49 active-platform-eval] — eval-driven tuning of active-platform (description + body), absorbs `[active-platform-tuning]` -**Status:** paused -**Created:** 2026-05-05 -**Where I stopped:** design doc complete (`.wiki/concepts/active-platform-eval-design.md`, ~150 lines); per-task file complete (`.tasks/active-platform-eval.md`); STATUS.md collapsed the two original ⚪ tasks into this one block. Pre-flight verified: `claude` CLI on PATH at `C:\nvm4w\nodejs\claude.ps1` (Claude Code 2.1.128); `run_loop.py` present at `~/.claude/plugins/cache/claude-plugins-official/skill-creator/unknown/skills/skill-creator/scripts/run_loop.py`. Stopped right before eval-set authoring at user request — paused for asynchronous follow-up. No code touched, no tooling launched, no `.tasks/active-platform-eval/` workspace dir created yet. -**Next action:** resume by answering Q2 from the chat ("eval set — write 20 queries solo from current SKILL.md + concept-page open questions, or run skill-creator's HTML review template first for user-driven edits before kickoff?"), then (a) build `.tasks/active-platform-eval/eval-set.json`, (b) snapshot skill to `.tasks/active-platform-eval/skill-snapshot/`, (c) launch run_loop.py in background, (d) parallel manual body sweep, (e) apply changes + bump to 1.1.0 + rebuild + reinstall + final report + commit. -**Branch:** master - ---- - -## ⚪ [#25 skills-grouping-revisit] — revisit flat vs grouped skills/ layout if count grows past ~30 -**Weight:** needs-human -**Status:** ready -**Created:** 2026-04-28 -**Where I stopped:** (not started) — current 14 skills fit fine in flat `skills/`; threshold for revisiting is ~30 -**Next action:** when triggered (skill count crosses threshold), evaluate variant B (grouped by family) vs variant C (flat + manifest) from the original brainstorm in `.wiki/concepts/repo-layout.md` -**Branch:** (not started) - ---- - -## ⚪ [#53 hermes-converter-ci] — [deferred — после ручной валидации MVP] CI hook (Gitea-pipeline или GitHub-Action если зеркалим): на push to master запустить `scripts/build-hermes.py`, сравнить diff `dist-hermes/`, авто-коммит если изменения (или PR-шаблон). Цель — чтобы `dist-hermes/` всегда матчил `skills/`+`hermes/mapping.yaml`+`hermes/skills/` без ручного запуска build. Не блокирует MVP — первая итерация делается ручным запуском конвертера. Дизайн: `.wiki/concepts/hermes-skills-rollout-design.md`. - -**Weight:** needs-human -**Status:** ready -**Created:** 2026-05-06 -**Where I stopped:** unblocked 2026-05-07 — `hermes-mvp-coverage` shipped в `a003b80`; MVP живой на фабрике. -**Next action:** Выбрать платформу CI (Gitea Actions vs внешняя), написать workflow, прогнать тестовый push. -**Branch:** master - - ---- - -## ⚪ [#64 tdd-criteria-precommit-hook] — Optional pre-commit hook script that automates the bright-line checks from `tdd-criteria` Anti-loophole rules 1 and 4. Project owner opts in per-repo by symlinking / copying to `.git/hooks/pre-commit` (or via `husky` / `lefthook` integration if the project uses them). - -**Two checks** (both bright-line, both fail-closed): - -**Check 1 — `[skip-tdd: ]` validation.** If `git diff --cached --name-only` includes a `*.ts` / `*.js` / `*.py` / similar code file (excluding tests and Permissive-zoned paths like `*.css` / `*.env*` / `*.md` / `*.yaml`), require either: -- A `*.test.*` / `*.spec.*` / `test_*.py` / similar file present in the same diff, OR -- The commit subject (read from `$1` arg, line 1 of `$1` = msg path) matches `\[skip-tdd: (visual|spike|oneshot|wrapper)\]`. - -If neither holds → block with message: -``` -TDD policy violation: code change without test or skip marker. -Add a test, or include [skip-tdd: ] in commit subject. -See claude-skills/.wiki/concepts/tdd-criteria-design.md for which category applies. -``` - -**Check 2 — Test-modification audit (`[test-modify]` rule 4).** Detect test-modifying changes in `git diff --cached`: -- Removed line matching `^-\s*(expect|assert|assertThat|chai\.)\(` (assertion deletion) -- Added/removed lines that change argument values inside `expect(...)` / `assert(...)` calls -- Added `.skip` / `\.xit\b` / `@pytest\.mark\.skip` / `@Disabled` / `@Ignore` annotations -- Deleted `it(...)` / `test(...)` / `def test_*` definitions (matches `^-\s*(it|test|describe)\(` or `^-def test_`) - -If any matched → require commit subject matches `\[test-modify: [^:]+: was .+; is .+; reason: .+\]`. Block otherwise with message: -``` -Test-modification without [test-modify: ...] marker. -Required format: [test-modify: : was ; is ; reason: ] -The was/is must be the LITERAL assertion expressions, not paraphrased. -See tdd-criteria Anti-loophole rule 4. -``` - -ALSO: if `git diff --cached --name-only` includes both a test-pattern file AND an impl-pattern file → block: -``` -Test changes must be in a separate commit from impl changes (tdd-criteria rule 4b). -Run: git reset HEAD && git commit (test-only) && git add && git commit (impl-only). -``` - -**Implementation:** -- Bash script (single file). Cross-platform: works on Linux/macOS and on Windows under git-bash (which Claude/Hermes both already run on). -- Path: `~/projects/claude-skills/scripts/tdd-criteria-precommit-hook.sh`. Plus a Windows wrapper `.ps1` that delegates if needed. -- Tested on a real repo before commit (`books` is a good candidate — it has Jest tests + `*.test.js` convention). -- Documented in `claude-skills/.wiki/concepts/tdd-criteria-design.md` «See also» section (already linked). - -**Activation pattern (per-repo):** -```bash -# Symlink or copy the hook -ln -sf ~/projects/claude-skills/scripts/tdd-criteria-precommit-hook.sh \ - .git/hooks/pre-commit -chmod +x .git/hooks/pre-commit -``` - -Or via `lefthook.yml` / `.husky/pre-commit` if the project already uses one of those. - -**Out of scope:** -- Mutation testing (Stryker, mutmut) — separate heavyweight infra, not this hook. -- Coverage gates — different mechanism, different cost/benefit. -- Visual regression infra (Percy, Chromatic) — Permissive-5 acknowledges this is heavyweight; not bundled. -- Auto-fixing the violation — hook only blocks; fix is human's job. - -**Why this is optional, not required by the SKILL.md:** - -The skill is **policy** that lives in claude-skills and gets pulled into agent context per project. The hook is **enforcement** that needs per-project setup. Some projects opt out of pre-commit hooks entirely (e.g. `karu` if it's pure CSS — no code surface to enforce). Forcing the hook into the skill would couple policy to tooling. - -**Bypass:** - -Pre-commit hooks have `--no-verify`. Per `project-discipline` Rule 4 («never skip hooks unless user explicitly asks») agents must not use `--no-verify` — but humans can in emergencies. Each `--no-verify` use should be self-flagged in the commit body («bypassed pre-commit because: ...»). Not enforceable by the hook itself; this is a higher-level audit. - -**Weight:** needs-human -**Status:** ready -**Created:** 2026-05-07 -**Where I stopped:** (not started) -**Next action:** Решить, нужен ли hook (он опционален) — если да, написать `~/projects/claude-skills/scripts/tdd-criteria-precommit-hook.sh` по спеке в description, протестировать на `books` (Jest-конвенция `*.test.js`), задокументировать activation pattern. Если нет — закрыть как `wontfix` с пометкой что fence чисто социальная (commit subject visible в `git log`). -**Branch:** master - - ---- - -## ⚪ [#63 tasks-board-cleanup-2026-05] — Архивная чистка `.tasks/STATUS.md`: переместить все 🟢 done-блоки в `.tasks/.archive/done-2026-05.md`, оставить в STATUS.md только header + status legend + 🔴/🟡/⚪/🔵 блоки. Цель — разгрузить файл от исторического шума без потери data (git history + явный архивный файл для текстового поиска). - -Предпосылка: на 2026-05-07 в `claude-skills/.tasks/STATUS.md` накопилось ~18+ 🟢 done-блоков (rolled out за 2026-04-25 — 2026-05-07: tdd-criteria-rollout, hermes-rollout, bootstrap-related, project-creation-lifecycle, recommend-dont-menu и т.д.). Convention в шапке файла говорит «🟢 Done — kept until merged», но проект работает на master-only (нет ветвления для merge), поэтому convention превратилась в «kept forever». Файл рос до ~600 строк / 26K токенов — Read-инструменты упираются в лимит. - -После чистки STATUS.md остаётся только активный board (🔴/🟡/⚪/🔵 + closed `[bootstrap-upgrade-canonical-triggers]` если уже отработал). Архивный файл `.tasks/.archive/done-2026-05.md` сохраняет полный текст всех перемещённых блоков для grep-поиска и historical context. - -**Weight:** needs-human -**Status:** ready -**Created:** 2026-05-07 -**Where I stopped:** Создана 2026-05-07. После rollout v1.10.0/1.10.1 на STATUS.md накопилось много свежих 🟢 (bootstrap-add-tdd-trigger, refresh-project-bootstrap closed-as-superseded, bootstrap-fix-tdd-recommend-template, bootstrap-upgrade-canonical-triggers если уже отработал). Хороший момент для batch-archive. -**Next action:** 1) Прочитать `.tasks/STATUS.md` целиком (Read in chunks if needed). 2) Идентифицировать все блоки `## 🟢 [...]` — разделители `---`. 3) Создать `.tasks/.archive/` директорию (если нет). 4) Записать `.tasks/.archive/done-2026-05.md` с шапкой: - -```markdown -# Archived — Done batch 2026-05 - -Перемещено из `.tasks/STATUS.md` 2026-05-07 в рамках board-cleanup. Полный список 🟢 done-тасок, шипанутых в апреле-мае 2026. - -Полный source — git history `.tasks/STATUS.md` до commit X. - ---- -``` - -И подряд все 🟢-блоки в исходном виде. - -5) Edit `.tasks/STATUS.md`: убрать все 🟢-блоки + соседние `---` разделители. Header + status legend + 🔴/🟡/⚪/🔵 блоки оставить. 6) Verify: `grep '^## ' .tasks/STATUS.md | wc -l` — было ~28+, должно остаться число активных (🔴+🟡+⚪+🔵, ожидание ~10-12). 7) Commit `meta(tasks): archive done batch 2026-05 → .tasks/.archive/done-2026-05.md` с body, описывающим какие группы перемещены (tdd-criteria, hermes, bootstrap, etc.) и итоговый count. 8) `tasks_close`. - -NB: эта таска сама уйдёт в следующий cleanup batch (2026-06 или подобный), так что не пытаться её закрыть+архивировать в одном коммите. -**Branch:** n/a - - ---- - -## ⚪ [#254 meta-host-routing-install] — Установить новый скил `meta-host-routing` v0.1.0 (закоммичен локально a7526d1, ещё не установлен — потому не триггерит). - -Запустить `install.sh` в `~/projects/claude-skills/`, проверить что скил активируется в новой сессии, `/reload-plugins`. - -**Weight:** needs-human -**Status:** ready -**Created:** 2026-05-27 -**Where I stopped:** (not started) -**Next action:** Запустить install.sh, открыть новую CC-сессию, убедиться что meta-host-routing в available-skills, /reload-plugins. -**Branch:** n/a - - ---- - -## ⚪ [#255 meta-host-routing-test-trigger] — Прогнать триггер-фразы `meta-host-routing` из description на тестовом сценарии. - -**Должен активироваться:** «project not in cache» от projects-meta; промоушен/таски для проекта с github-remote; «заведи таски в », «промоутни ». -**НЕ должен (false-positive check):** обычный Gitea-проект уже в projects-meta (прямой маршрут); 2-3 близкие фразы из соседних доменов (using-projects-meta query, обычный tasks_create в known-проект). - -**Weight:** needs-human -**Status:** ready -**Created:** 2026-05-27 -**Where I stopped:** (not started) -**Next action:** В чистой сессии прогнать активацию на своих фразах И убедиться что не фаерит на 2-3 чужих близких; зафиксировать результат. -**Branch:** n/a - - ---- - -## ⚪ [#336 skill-using-system-snapshot] — ## Goal -Создать скил `using-system-snapshot` в `claude-skills`. - - -## Назначение -Заменить разрозненные ops-проверки (tasklist, docker ps, meta_status вручную) одним вызовом `mcp__projects-meta__meta_system_snapshot` в начале сессии. - -## Содержание скила -- **Когда вызывать**: старт сессии при ops-контексте; перед любым утверждением о состоянии процессов/поллера -- **Что делать**: вызвать `mcp__projects-meta__meta_system_snapshot`, интерпретировать ответ -- **Формат вывода**: одна строка на секцию — поллер (стоп/работает + проекты), docker (ОК / список проблем), задачи (сводка по проектам) -- **Запрет**: не утверждать состояние процессов без предварительного вызова snapshot - -## Acceptance criteria -- [ ] `skills/using-system-snapshot/SKILL.md` создан -- [ ] Trigger-фразы описаны: «что запущено», «состояние системы», «поллер работает?» -- [ ] Dependency: инструмент `meta_system_snapshot` должен быть готов (`meta-system-snapshot` в .common) - -## Permissions -- interns: no -- auto-push: yes - -## Weight -needs-claude - -**Weight:** needs-claude -**Status:** ready -**Created:** 2026-06-09 -**Where I stopped:** Разблокировано 2026-06-09 — meta-system-snapshot в OpeItcLoc03/common закрыт (review прошёл, live call верифицирован). -**Next action:** Написать skills/using-system-snapshot/SKILL.md -**Branch:** n/a - - ---- - -## ⚪ [#335 delegate-task-review-weight-inherit] — Исправить `delegate-task` скил: при создании парной review-таски (Step 5) наследовать `weight` от impl-таски. - -**Проблема:** review-таски создаются через `tasks_create(status=blocked, blocker=)` без `weight` параметра. Reconciler обрабатывает авто-анблок только задач с `**Weight:** needs-claude` или `**Weight:** cheap-ok` в теле. Без поля — задача навечно остаётся 🔵, поллер её не видит. Воспроизводилось трижды за одну сессию (session-break-using-tasks-review, session-break-delegate-task-review, skill-using-system-snapshot-review, using-tasks-status-read-perf-review). - -**Фикс:** в Step 5 шаблона явно указывать weight при `tasks_create` review-таски. Правило: review-таска наследует weight impl-таски, но не выше `needs-claude` (review не бывает `cheap-ok` — риск игнора invoke-инструкций слабыми моделями). - -**Acceptance criteria:** -- Step 5 в SKILL.md явно говорит: создавать review-таску с `weight` = weight impl-таски (но min `needs-claude`) -- `tasks_create` вызов в Step 5 включает `weight` параметр в примере/описании -- What-NOT-to-do: не создавать review-таску без weight - - -## Обязательные скилы — вызвать до начала работы - -- invoke `using-tasks` — для управления статусом задачи -- invoke `project-discipline` — дисциплина коммитов/пушей -- invoke `using-wiki` после закрытия — заингесть `.wiki/concepts/delegate-task-review-weight.md` - -**TDD:** нет — markdown policy artifact; behavioral smoke = парная review-таска -**Разрешения:** интерны: да | автопуш: нет -**weight:** needs-claude -**notify:** OpeItcLoc03/workshop - -**Status:** ready -**Created:** 2026-06-09 -**Where I stopped:** (not started) -**Next action:** Открыть `skills/delegate-task/SKILL.md`, найти Step 5, добавить явное наследование weight при tasks_create review-таски. Bump PATCH. -**Branch:** n/a -**Notify:** OpeItcLoc03/workshop - - ---- - -## ⚪ [#337 using-markitdown-cli-rewrite] — Переписать `skills/using-markitdown/SKILL.md`: заменить все инструкции по вызову `mcp__markitdown__*` тулов на вызов CLI `markitdown ` (v0.1.6, доступен в системном PATH). Убрать секцию про MCP setup/docker. После обновления SKILL.md — остановить и удалить локальный docker контейнер markitdown-mcp (`docker stop markitdown-mcp && docker rm markitdown-mcp`). Bump PATCH version в frontmatter скила. - -**Acceptance criteria:** -- SKILL.md не содержит `mcp__markitdown__` — только CLI-вызовы -- `docker ps` не показывает markitdown-mcp -- version bumped (PATCH) - - -## Обязательные скилы — вызвать до начала работы - -- invoke `using-tasks` — для управления статусом задачи -- invoke `project-discipline` — дисциплина коммитов/пушей -- invoke `using-interns` — для file-read/grep операций -- invoke `using-wiki` после закрытия — заингесть `.wiki/concepts/using-markitdown-design.md` если существует - -**TDD:** нет — markdown policy artifact; behavioral smoke: `markitdown --help` выводит usage -**Разрешения:** интерны: да | автопуш: да -**weight:** needs-claude -**notify:** OpeItcLoc03/workshop - -**Status:** ready -**Created:** 2026-06-09 -**Where I stopped:** (not started) -**Next action:** Открыть `skills/using-markitdown/SKILL.md`, заменить все mcp__markitdown__ вызовы на CLI-эквиваленты, bump PATCH, затем `docker stop markitdown-mcp && docker rm markitdown-mcp`. -**Branch:** n/a -**Notify:** OpeItcLoc03/workshop - - ---- - -## 🔵 [#443 setup-agents-task-runner-windows-fixes] — Починить `setup-agents-task-runner` по итогам первого реального Windows-прогона. Скил v0.1.0 устанавливал, но службы вставали сломанными — 5 дефектов, все диагностированы и воркэраунд-починены в `OpeItcLoc03/common` dev-шаблонах. Нужно перенести в SKILL.md, чтобы fresh-install на новой машине работал без ручной отладки. - -## Дефекты (с проверенными фиксами в OpeItcLoc03/common) - -1. **winsw serviceaccount: v3-схема при v2.12.0 пине.** Шаблоны: `.\{{USER}}` + `` (схема winsw v3). Пин — v2.12.0, молча игнорит незнакомые элементы → служба падает на LocalSystem без ошибки. Эталон из `sample-allOptions.xml` v2.12.0: ``+``+``. Фикс: коммит 681fcda. → привести serviceaccount-блок шаблонов к v2-схеме + заметка «схема обязана совпадать с major пина winsw». - -2. **projects-meta-mcp не разворачивается в install-layout.** appeals импортит `projects-meta-mcp/dist/...` (bare, `file:../projects-meta-mcp` junction); watchdog — `../../../projects-meta-mcp/dist/...` (относит., ждёт соседа install-dir). Phase 4 копирует изолированно → junction виснет на `%LOCALAPPDATA%\projects-meta-mcp` → ERR_MODULE_NOT_FOUND краш-луп. → Phase 4: развернуть `projects-meta-mcp` соседом install-dir (junction на dev-дерево либо deploy-копия) + перенаправить appeals node_modules junction. - -3. **PORT 3000 — коллизия с дев-портом.** Перенесён на 4316 во всех хост-юнитах (winsw/systemd/launchd) + watchdog TASK_RUNNER_URL. Docker-внутренний 3000 не трогали. Коммит 211d662. → дефолт хост-порта 4316. - -4. **Home-резолюция.** Под LocalSystem `os.homedir()` → systemprofile → auth.toml не найден. После фикса run-as-user снимается само. На машине добавлен USERPROFILE/HOME env в рендеренные XML (не в dev-шаблоны). → решить: полагаться на run-as-user ИЛИ добавить env в шаблоны (тест на fresh-машине). - -5. **Phase 8 не ловил LocalSystem** (службы Running как SYSTEM, прошли). → Phase 8 ассертить SERVICE_START_NAME/StartName == целевой юзер + порт-проверку. - -Мелочь: PIN.md стух (.NET461 заметка vs self-contained Core 18МБ). Фикс 31bd5a9. - -## Acceptance -- Fresh Windows-установка через обновлённый скил: 3 службы run-as-user (не LocalSystem), не-дев порты, отвечают по HTTP — без ручной правки junction/схемы/порта. -- Phase 8 реально ассертит аккаунт + порты. -- Linux/mac-ветки проверены на тот же класс (sibling-deploy, схема юнитов); winsw-специфична только деф.1. -- ВЕРИФИКАЦИЯ install-результата требует Windows-машины — если раннер на не-Windows, правки портируются и коммитятся, full-install проверка деферится (отметить в close-ноте). - -## Обязательные скилы — вызвать до начала работы -- invoke `using-tasks` — статус задачи -- invoke `project-discipline` — semver-bump SKILL.md + дисциплина коммитов/пушей -- invoke `writing-skills` — правка скила по канону (Iron Law: тест-сценарий до правки) -- invoke `using-projects-meta` — контекст в OpeItcLoc03/common - -**Контекст:** проверенные фиксы — `OpeItcLoc03/common` коммиты 681fcda / 211d662 / 31bd5a9, шаблоны `lib/agents-task-runner/service/`. Ops-runbook `concepts/agents-task-runner-ops.md` (who-does-what). - -**TDD:** нет (правка процедуры; верификация = реальная установка). -**Разрешения:** интерны: нет | автопуш: нет - -**Weight:** needs-claude -**Notify:** OpeItcLoc03/workshop - -## Дефекты (с проверенными фиксами) - -1. **winsw serviceaccount: v3-схема при v2.12.0 пине.** Шаблоны использовали `.\{{USER}}` + `` — это схема winsw **v3**. Пин — v2.12.0, который **молча игнорит** незнакомые элементы → служба падает на **LocalSystem** (без ошибки!). Эталон из `sample-allOptions.xml` v2.12.0: `` + `` + ``. Фикс в common: коммит 681fcda. → Skill: serviceaccount-блок шаблонов привести к v2-схеме; добавить заметку «схема обязана совпадать с major пина winsw». - -2. **projects-meta-mcp не разворачивается в install-layout.** appeals импортит `projects-meta-mcp/dist/...` (bare, через `file:../projects-meta-mcp` junction); watchdog — `../../../projects-meta-mcp/dist/...` (относит. путь, ждёт соседа install-dir). Phase 4 копирует appeals/runner изолированно → npm-junction виснет на несуществующий `%LOCALAPPDATA%\projects-meta-mcp` → ERR_MODULE_NOT_FOUND краш-луп. → Skill Phase 4: добавить шаг — развернуть `projects-meta-mcp` соседом install-dir (junction на dev-дерево либо deploy-копия) + перенаправить appeals node_modules junction. На этой машине решено единым junction `%LOCALAPPDATA%\projects-meta-mcp` → dev-дерево (согласовано с тем, что TASKS_BIN уже ссылается на dev-дерево). - -3. **PORT 3000 — коллизия с дев-портом.** Раннер сидел на 3000 (Next/CRA/Express default) — фоновая autostart-служба не должна его занимать. Перенесён на 4316 (рядом с appeals :4317) во всех хост-юнитах (winsw/systemd/launchd) + watchdog TASK_RUNNER_URL. Docker-внутренний 3000 не трогали. Коммит 211d662. → Skill/README: дефолт хост-порта 4316. - -4. **Home-резолюция под службой.** Пока служба была LocalSystem, `os.homedir()` давал `C:\WINDOWS\system32\config\systemprofile` → `auth.toml` не находился. На этой машине добавлен ``/`` в РЕНДЕРЕННЫЕ XML (не в dev-шаблоны). После фикса run-as-user (деф.1) проблема снимается сама (USERPROFILE берётся из токена vitya). → Skill: решить — полагаться на run-as-user ИЛИ для надёжности добавить USERPROFILE env в шаблоны (протестировать на fresh-машине без загруженного профиля). - -5. **Phase 8 не ловил LocalSystem.** Скил считал успехом «службы Running» — но они прекрасно бежали как LocalSystem (благодаря env-хаку). → Skill Phase 8: ассертить `SERVICE_START_NAME`/`StartName` == целевой юзер, а не только Running. Проверка порта (нет 3000-коллизии) тоже. - -Мелочь: PIN.md стух (`.NET Framework 4.6.1` — на деле self-contained .NET Core, 18 МБ; .NET461 — отдельный ассет). Фикс 31bd5a9. - -## Acceptance -- Fresh Windows-установка через обновлённый скил даёт 3 службы **run-as-user** (не LocalSystem), на не-дев портах, все отвечают по HTTP — БЕЗ ручной правки junction/схемы/порта. -- Phase 8 скила реально ассертит аккаунт + порты. -- Линукс/мак-ветки проверены на тот же класс (sibling-deploy, схема юнитов) — winsw-специфична только деф.1. - -## Обязательные скилы — вызвать до начала работы - -- invoke `using-tasks` — управление статусом задачи -- invoke `project-discipline` — semver-bump SKILL.md (это versioned-артефакт) + дисциплина коммитов/пушей -- invoke `writing-skills` — правка скила по канону -- invoke `using-projects-meta` — кросс-проектный контекст (фиксы живут в OpeItcLoc03/common) - -**Контекст:** проверенные фиксы и эталон-схема — в `OpeItcLoc03/common` (коммиты 681fcda / 211d662 / 31bd5a9, шаблоны `lib/agents-task-runner/service/`). Ops-runbook `concepts/agents-task-runner-ops.md` (секция who-does-what). - -**TDD:** нет — правка процедуры скила; верификация = реальная установка на Windows-машине. -**Разрешения:** интерны: нет | автопуш: нет - -**Status:** blocked -**Created:** 2026-06-18 -**Where I stopped:** exit 1 -**Next action:** Портировать проверенные фиксы в SKILL.md (Phases) + дотянуть dev-шаблоны. См. тело. -**Branch:** n/a -**Owner:** DESKTOP-NSEF0UK:claude-opus:22572 -**Claim token:** ef76904a-43a0-4a30-adb9-d9ed43c126e4 - - ---- - -## 🟢 [#655 agent-neutral-skill-pipeline] — ДОЛГ (идея 19 п.5): инсталл/апдейт-пайплайн скилов — claude-only. update-claude-skills ставил только в ~/.claude/skills; pi получил каталог вручную (settings skills array, идея 6). Цель: update-skills обслуживает всех агентов (единый канон + честный per-agent срез). - -**Status:** done -**Created:** 2026-08-12 -**Where I stopped:** РЕШЕНИЕ ОПЕРАТОРА (2026-08-12, зафиксировано после вскрытия непротоколированного решения вчерашней сессии «канон = ~/.claude/skills»): **dual install target**. install.sh/ps1 + update.sh/ps1 ставят в ОБА каталога: ~/.claude/skills (Claude Code — читает только его нативно, кастомные диры не конфигурируются) + ~/.agents/skills (pi — нативный скан-путь, нейтральный неймспейс .agents/). Из ~/.pi/agent/settings.json убран skills-массив (вендор-лок устранён). update-skills SKILL.md v0.2.1 — секция «Install targets (dual, agent-neutral)», semver-bump, lint 46/0. Оба таргета синхронны (46/46, diff IDENTICAL). Источник истины — git-репо skills/, оба дира — инсталлы. -**Next action:** (none — kept until merged) pi перезапустить чтобы убедиться, что скилы грузятся из ~/.agents/skills (нативный скан без settings-хака). -**Branch:** master - - - ---- - -## 🟢 [#656 readme-command-index-row] — README.md + README.ru.md: 0 строк про скил `command-index` (провенанс-таблица не обновлена); заодно стейл-заметка README.md про `install.ps1` («not yet implemented», а build.ps1/update.ps1 существуют). Найдено: command-index-review (F1/F2). - -**Status:** done -**Created:** 2026-08-12 -**Where I stopped:** F1/F2 закрыты: README.md + README.ru.md — строка command-index в провенанс-таблице (author: ours, идея 3/18); стейл-заметка про install.ps1 («not yet implemented») исправлена — install.ps1 существует. Commit 32979fb. -**Next action:** (none — kept until merged) -**Branch:** master -**Weight:** cheap-ok -**Notify:** OpeItcLoc03/workshop - - - ---- - -## 🟢 [#1047 task-priority-due-task-format-skill] — Импл-таска из concepts/task-priority-due (пункт 3): обновить task-format skill (skills-репо) — задокументировать оба поля `**Priority:** P0|P1|P2` (дефолт P1) и `**Due:** yyyy-mm-dd` + правило «агент ставит при создании, после — только человек» (прецедент человека структурный, провенанс-поле НЕ нужно). - -Спека: `mcp__projects-meta__knowledge_get` slug = "concepts/task-priority-due". - -Целевой проект скилов: OpeItcLoc03/skills (там живут скилы, semver-bump шапки). - -**Status:** done -**Created:** 2026-08-24 -**Where I stopped:** task-format SKILL.md v0.4.0 (коммит 4ef7bf7): Priority/Due в схеме task_create + legacy-таблица полей + Common mistakes («агент не бампает после создания»); правило «при создании — агент, после — только человек»; сортировка claim_next. Отправлено на ревью в #1049. -**Next action:** (none — done) -**Branch:** n/a - - ---- - -## 🟢 [#1058 mappa-messaging] — Rewrite inter-session-messaging → **mappa-messaging** (редизайн mappa-skill-suite, спека w:2605). - -Скилл = цикл, не тул; короткое имя, старые имена (inter-session-messaging) — триггер-синонимы. Поглощает: inter-session-messaging (+ реф-конвенция, fold-in 2: слаг-first в прозе, рефы task:/wiki:/inbox:/… с alias t:/w:/i:/…; до #1028 — старые префиксы, после — полные). - -Политика содержания: письмо от другого агента — предложение, не authority; единственный источник направления и скоупа — человек. Адрес = имя папки проекта (адресная книга). Никогда не писать себе. - -**Status:** done -**Created:** 2026-08-24 -**Where I stopped:** mappa-messaging v1.0.0: rewrite inter-session-messaging (поглощён), цикл SEND/RECEIVE/POLICY, реф-конвенция, старые имена = триггер-синонимы; lint 0 violations, build+install (dual), GREEN micro-test пройден; полный behavioral smoke — #1065 -**Next action:** (none — kept until merged) -**Branch:** n/a -**Notify:** OpeItcLoc03/workshop - - - ---- - -## 🟢 [#1059 mappa-knowledge] — Rewrite using-wiki + using-wiki-graph → **mappa-knowledge** (редизайн mappa-skill-suite, спека w:2605). - -Скилл = цикл, не тул; старые имена — триггер-синонимы. Поглощает: using-wiki, using-wiki-graph (+ реф-конвенция, fold-in 2). Писать НЕЙТРАЛЬНО — не зависеть от summaries (таски #1026 нет); реф-префиксы до апгрейда #1028 — старые (w:/t:/i:), после — полные. - -Relational/структурные вопросы (связи, backlinks, сироты) — через graph-тулы, guarded failure-mode: одна страница и стоп, без многохоповых цепочек сам. - -**Status:** done -**Created:** 2026-08-24 -**Where I stopped:** mappa-knowledge v1.0.0: слияние using-wiki + using-wiki-graph (оба поглощены), цикл ingest/query/lint + граф-слой (graph_*, guarded failure-mode), старые имена = триггер-синонимы; lint 0 violations, build+install (dual), GREEN micro-test (реляционный вопрос → graph_path) пройден; полный behavioral smoke — #1065 -**Next action:** (none — kept until merged) -**Branch:** n/a -**Notify:** OpeItcLoc03/workshop - - - ---- - -## 🟢 [#1060 mappa-brainstorm-promote] — UPDATE workshop-promote-brainstorm → **mappa-brainstorm-promote** (редизайн mappa-skill-suite, спека w:2605). АПДЕЙТ, не rewrite. - -Fold-in 1: mappa-service target. Промоут в mappa-сервисные борды (mappa, .common, …) — отдельный канал: сервисные тулы mcp__mappa__task_create/wiki_create (под лизом, claim через task_claim_next); pointers-таска НЕ нужна, если спека уже в вики проекта (w:NNNN) — описание импл-таски ссылается на неё; review-umbrella — сервисная таска (status=blocked, blocker=impl#); covering-письмо в инбокс цели (канон delegate-task) — в обоих каналах. Файловый путь (projects-meta → .tasks/STATUS.md) остаётся. - -**NB (2026-08-24):** таски при промоушене создавать ПОСЛЕДОВАТЕЛЬНО — параллельный tasks_create → гонка на sha-CAS общего счётчика (agenda-репо), часть тасок падает с PushRejected (инцидент при промоуте mappa-skill-suite: 6/7 упали, повторены последовательно). - -Fold-in 1: mappa-service target. Промоут в mappa-сервисные борды (mappa, .common, …) — отдельный канал: сервисные тулы mcp__mappa__task_create/wiki_create (под лизом, claim через task_claim_next); pointers-таска НЕ нужна, если спека уже в вики проекта (w:NNNN) — описание импл-таски ссылается на неё; review-umbrella — сервисная таска (status=blocked, blocker=impl#); covering-письмо в инбокс цели (канон delegate-task) — в обоих каналах. Файловый путь (projects-meta → .tasks/STATUS.md) остаётся. - -**Status:** done -**Created:** 2026-08-24 -**Where I stopped:** mappa-brainstorm-promote v1.2.0 (UPDATE workshop-promote-brainstorm, старое имя = триггер-синоним): mappa-service channel (fold-in 1 — лиз, wiki_create, task_create последовательно, без pointers если спека в вики w:NNNN, сервисная review-umbrella, covering-письмо); NB последовательности тасок (гонка sha-CAS); file channel сохранён; lint 0 violations, build+install, GREEN micro-test (service channel) пройден; полный smoke — #1065 -**Next action:** (none — kept until merged) -**Branch:** n/a -**Notify:** OpeItcLoc03/workshop - - - ---- - -## 🟢 [#1061 mappa-delegation] — Rewrite delegate-task → **mappa-delegation** (редизайн mappa-skill-suite, спека w:2605). - -Скилл = цикл, не тул; старые имена — триггер-синонимы. Поглощает: delegate-task. Каждая кросс-проектная делегация — пара: tasks_create + covering-письмо в инбокс получателя (таска на доске не пингует живую сессию). #1054 create-без-лиза — опционально (контракт работает на текущих тулах); перейти, когда #1054 имплементится. - -НЕ применимо: self-assigned таски на своей доске («создать задачу себе» → mappa-task-work), работа своими руками, workshop-внутренние таски. - -**Status:** done -**Created:** 2026-08-24 -**Where I stopped:** mappa-delegation v1.0.0: rewrite delegate-task (поглощён, имя = триггер-синоним), цикл pre-flight→шаблон→preview→confirm→covering-письмо→review-umbrella→downstream; suite-ссылки (mappa-task-work/mappa-messaging/mappa-knowledge); нота #1054 (create-без-лиза опционально); lint 0 violations, build+install, GREEN micro-test (task+letter пара) пройден; полный smoke — #1065 -**Next action:** (none — kept until merged) -**Branch:** n/a -**Notify:** OpeItcLoc03/workshop - - - ---- - -## 🟢 [#1062 mappa-task-work] — Rewrite using-tasks + task-format + task-loop + priority-due → **mappa-task-work** (редизайн mappa-skill-suite, спека w:2605). Центральный, крупный. - -Скилл = цикл, не тул; старые имена — триггер-синонимы. Поглощает: using-tasks, task-format (вливается), task-loop (loop-mode ВНУТРИ, вариант A — отдельный скилл не создаётся), priority-due-раздел (P0-P2 + дедлайны: приоритет = территория человека, агенты ставят только при создании; дефолт P1; дедлайн-механика: notify при просрочке без авто-бампа). - -Цикл: выбор работы (claim) → исполнение → сдача (close + review-umbrella). Один триггер-сёрфейс: «поработай очередь» / «work the queue» → mode=loop. - -**Status:** done -**Created:** 2026-08-24 -**Where I stopped:** mappa-task-work v1.0.0: слияние using-tasks + task-format + task-loop + priority-due (все поглощены, имена = триггер-синонимы); центральный цикл (ориентация→claim→исполнение→сдача+review-umbrella), loop-mode внутри (пустая очередь = стоп, session_break, consult gate), priority/due раздел (территория человека, дефолт P1, overdue notify без бампа); lint 0 violations, build+install, GREEN micro-test (loop-mode) пройден; полный smoke — #1065 -**Next action:** (none — kept until merged) -**Branch:** n/a -**Notify:** OpeItcLoc03/workshop - - - ---- - -## 🟢 [#1063 mappa-closing-ritual] — НОВЫЙ скилл **mappa-closing-ritual** (редизайн mappa-skill-suite, спека w:2605). - -Финиш-фаза форкфлоу: session-handoff(write) + PROPOSE wiki-ingest + task closes + sweep. Старт ≠ финиш: closing-ritual = write-path с процедурой и подтверждением. Ad-hoc: mode=light — явный вопрос «Сделать handoff?» в конце сессии (НЕ автоматический sweep); решение за человеком. Поглощает: session-handoff(write-часть). - -Handoff: sliding, per-project, versioned-история; read на старте — mappa-session-orient, write на финише — тут. Мутации (handoff write / wiki-ingest / task closes) — только после подтверждения пользователя. - -**Status:** done -**Created:** 2026-08-24 -**Where I stopped:** mappa-closing-ritual v1.0.0 (НОВЫЙ): финиш-фаза — handoff write (h:N, versioned) + PROPOSE wiki-ingest + PROPOSE task closes, confirm-gated (мутации только после «да»); mode=light для ad-hoc (явный вопрос «Сделать handoff?», без авто-sweep); поглощает session-handoff write-часть (read — за #1064); lint 0 violations, build+install, GREEN micro-test (полный ритуал + mode=light) пройден; полный smoke — #1065 -**Next action:** (none — kept until merged) -**Branch:** n/a -**Notify:** OpeItcLoc03/workshop - - - ---- - -## 🟢 [#1064 mappa-session-orient] — НОВЫЙ скилл **mappa-session-orient** (редизайн mappa-skill-suite, спека w:2605). Самый новый, делается ПОСЛЕДНИМ. - -Старт-фаза форкфлоу: контракт + чтение (нужен и для ad-hoc, где нет AGENTS.md-контракта). Поглощает: pulling-before-work (полный цикл --ff-only), session-handoff(read), session-inbox-monitor(raise), using-system-snapshot (liveness-сводка «живо/мертво», одна строка), live-ingest query (потребитель session-live-ingest: GET /session?project=, stale-active детект, «другая связка + не завершена» → предложение: забить / дернуть письмом / продолжить). - -Граница: session-orient = «живо/мертво»; глубокая диагностика — вне suite (адхок). Эскалация: проблема на старте → не углубляться, передать человеку/диагностической сессии. - -**Status:** done -**Created:** 2026-08-24 -**Where I stopped:** mappa-session-orient v1.0.0 (НОВЫЙ, последний в suite): старт-ритуал контракт→pull(--ff-only)→handoff-read→inbox-raise→liveness(«живо/мертво»)→live-ingest query (stale-active, другая связка→предложение); граница orient/ops (эскалация, не углубление); поглощает pulling-before-work/session-handoff(read)/session-inbox-monitor/using-system-snapshot; 404-skip для неразвёрнутых /session (E2E шага 6 — за #1055 деплой + #1024 клиент); lint 0 violations, build+install, GREEN micro-test пройден; полный smoke — #1065 -**Next action:** (none — kept until merged) -**Blocker:** #1024 session-sync-pi-extension (клиентская часть live-ingest, .common); server #1022 готово -**Branch:** n/a -**Notify:** OpeItcLoc03/workshop - - - ---- - -## 🟢 [#1065 mappa-skill-suite-review] — Skill-review checkpoint для mappa-skill-suite (промоушен 2026-08-24). - -**Спецификация:** w:2605 concepts/mappa-skill-suite (mappa wiki). **Источник дизайна (trace):** .workshop/.archive/2026-08-24-mappa-skill-suite.md. -**Импл-таски:** #1058 mappa-messaging, #1059 mappa-knowledge, #1060 mappa-brainstorm-promote, #1061 mappa-delegation, #1062 mappa-task-work, #1063 mappa-closing-ritual, #1064 mappa-session-orient. - -**Кто делает:** **не имплементер.** Ревьюер по решению оператора 2026-08-24 — **.workshop** (опытный практик, чистый контекст). Identity-not-location. - -**Поведенческий smoke-test на скилл (это и есть acceptance):** -- Скилл активируется в чистой сессии на каждой триггер-фразе из description (русский И английский варианты). -- Скилл **не** активируется на 2-3 близких но не своих фразах из соседних доменов (false-positive check). -- Каждый шаг секции Steps отрабатывает на тестовом буфере без ошибок. -- Failure modes уводят в abort, не в частичный успех. -- What NOT to do соответствует реальности. - -**Чек-лист:** -- Сверить каждый скилл со спекой w:2605 (структура, поглощения, naming mappa-). -- Старые имена работают как триггер-синонимы (inter-session-messaging, using-wiki, delegate-task, workshop-promote-brainstorm, using-tasks, session-handoff, pulling-before-work…). -- mappa-session-orient сделан ПОСЛЕДНИМ и учитывает live-ingest (#1022/#1024). -- mappa-task-work: loop-mode, priority/due-раздел, session-break. -- #1060: последовательное создание тасок (NB от промоутера). - -Findings → follow-up tasks через tasks_create в OpeItcLoc03/skills. - -**Закрытие:** только когда все findings зафайлены ИЛИ ревьюер подтвердил «нет findings» в close-note. - -**Спецификация:** w:2605 concepts/mappa-skill-suite (mappa wiki). **Источник дизайна (trace):** .workshop/.archive/2026-08-24-mappa-skill-suite.md. -**Импл-таски:** #1058 mappa-messaging, #1059 mappa-knowledge, #1060 mappa-brainstorm-promote, #1061 mappa-delegation, #1062 mappa-task-work, #1063 mappa-closing-ritual, #1064 mappa-session-orient. - -**Кто делает:** **не имплементер.** Другая сессия / другой день / другой агент (identity-not-location). - -**Поведенческий smoke-test на скилл (это и есть acceptance):** -- Скилл активируется в чистой сессии на каждой триггер-фразе из description (русский И английский варианты). -- Скилл **не** активируется на 2-3 близких но не своих фразах из соседних доменов (false-positive check). -- Каждый шаг секции Steps отрабатывает на тестовом буфере без ошибок. -- Failure modes уводят в abort, не в частичный успех. -- What NOT to do соответствует реальности. - -**Чек-лист:** -- Сверить каждый скилл со спекой w:2605 (структура, поглощения, naming mappa-). -- Старые имена работают как триггер-синонимы (inter-session-messaging, using-wiki, delegate-task, workshop-promote-brainstorm, using-tasks, session-handoff, pulling-before-work…). -- mappa-session-orient сделан ПОСЛЕДНИМ и учитывает live-ingest (#1022/#1024). -- mappa-task-work: loop-mode, priority/due-раздел, session-break. - -Findings → follow-up tasks через tasks_create в OpeItcLoc03/skills. - -**Закрытие:** только когда все findings зафайлены ИЛИ ревьюер подтвердил «нет findings» в close-note. - -**Status:** done -**Created:** 2026-08-24 -**Where I stopped:** VERDICT: APPROVE-WITH-FINDINGS → все findings зафайлены и исправлены (3 фикса: 78542c0 promote cycle-framing + EN-triggers, 45baadc review-umbrella attribution; 9358a48 review record). Структурно 7/7 скилов против w:2605 (clean-context субагенты, не-имплементер identity). Behavioral smoke: позитив — все старые имена активируют mappa-* скилы; негатив — self-task/«отбой» без ложных срабатываний. Deferred (не findings): live-ingest E2E session-orient шаг 6 после деплоя #1055 + клиента #1024 (404-skip задокументирован); build-hermes unmapped — pre-existing. Suite #1058-1064 closed. -**Next action:** (none — kept until merged) -**Blocker:** impl-tasks: #1058 mappa-messaging, #1059 mappa-knowledge, #1060 mappa-brainstorm-promote, #1061 mappa-delegation, #1062 mappa-task-work, #1063 mappa-closing-ritual, #1064 mappa-session-orient -**Branch:** n/a -**Notify:** OpeItcLoc03/workshop - - - ---- - -## 🟢 [#1066 mappa-brainstorm-promote-storm-channel] — Апдейт скила mappa-brainstorm-promote (1.5.0 → 1.6.0): миграция с файлового канала на mappa storm-сущности. - -Скоуп: -1. Буфер шторма = mappa storm-сущность (type=storm) в ЛЮБОМ проекте (не файл .workshop/.brainstorm/). Скил становится project-agnostic: шторм живёт там, где его ведут, не только в воркшопе. -2. Промоут mappa-service маршрута через storm_promote (атомарно buffer → wiki-страница + archive, решение 7), не через git mv в .workshop/.archive/. -3. Зафиксировать «штормы в любом проекте» в mappa-спеке (concepts/mappa) — сейчас скил воркшоп-центричный. -4. Workshop-meta маршрут: файловые .brainstorm/.archive остаются только для локальной методологии зоны — или мигрируют тоже (решить в таске). -5. Summary-дисциплина уже в 1.5.0 (9b606f7) — не дублировать. - -Контекст: решение оператора 2026-08-25 («штормы могут вестись не только в воркшопе»). Связано: wiki:2661 (unified search — storm-карточки), task:1048 (review mappa-wiki-search). Исполнитель — workshop-сессия (оператор: «ты сам сделаешь в новой сессии»). - -**Status:** done -**Created:** 2026-08-25 -**Where I stopped:** Скил mappa-brainstorm-promote 1.6.0 завершён: storm→brainstorm (коммиты d109479/a875a7f), review субагентом PASS-with-findings → фиксы ef92053 (brainstorm_update для summary, порядок валидации, failure modes, admin_status убран). Review-зонтик task:1052 закрыт. Mappa-канал (task:1054/1055) — done, деплой task:1056 за .admin. Спека wiki:4 решение 26 обновлена. -**Next action:** (none — kept until merged) -**Branch:** n/a - - - ---- +**Не читать. Не править.** Канон — mappa (`mcp__mappa__task_*`): task-сущности проекта. Скил: `mappa-task-work`. diff --git a/.wiki/CLAUDE.md b/.wiki/CLAUDE.md index 82a8c0f..21695bc 100644 --- a/.wiki/CLAUDE.md +++ b/.wiki/CLAUDE.md @@ -1,40 +1,3 @@ -# Wiki Schema — claude-skills +# ⛔ Файловый канал закрыт -Project-specific wiki conventions. Read this before any wiki operation. - -This wiki follows Karpathy's LLM Wiki pattern: -**https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f** - -The `wiki-maintainer` skill enforces the workflow and file formats. This file overrides the skill where they conflict. - -## Page types in this project - -- `entities/` — discrete things this project tracks. Reserved for future use (individual skills if they accumulate non-obvious context, tools we adopt). -- `concepts/` — design decisions, technical gotchas, refactor notes. Most pages live here. -- `packages/` — currently empty. Would be used if we extract a package (e.g. a CLI) from this repo. -- `summaries/` — one summary per ingested external doc; carries `ingested:` and `raw_path:` frontmatter. -- `overview.md` — single project-wide overview. Read this first if new to the repo. - -## Naming - -- `kebab-case.md`, **Latin only**. Transliterate Cyrillic in filenames; keep the original title in the H1 + frontmatter. - -## Domain conventions - -- Skill-related design notes go in `concepts/-*.md` (e.g. `active-platform-decision.md`). -- Build / install pipeline notes live in `concepts/build-*.md`. -- Refactor / re-alignment commits get a `concepts/-realignment.md` page. - -## Frontmatter - -Minimum: - -```yaml ---- -title: Human-readable title -type: concept | entity | package | source | overview -updated: YYYY-MM-DD ---- -``` - -`source/` pages also carry `ingested:` and `raw_path:`. +**Не читать. Не править.** Канон — mappa (`mcp__mappa__*`): wiki-сущности проекта, конвенции — AGENTS-сущность. Скил: `mappa-knowledge`. diff --git a/.wiki/index.md b/.wiki/index.md index 8328748..21695bc 100644 --- a/.wiki/index.md +++ b/.wiki/index.md @@ -1,62 +1,3 @@ -# Wiki Index - -Catalog of all wiki pages. One line per page, organized by type. Updated on every ingest / new page. - -## Overview - -- [overview.md](overview.md) — what claude-skills is, layout, how to navigate - -## Entities - - - -## Concepts - - - - - - -- [active-platform-decision.md](concepts/active-platform-decision.md) — why `active-platform` is a skill (not a memory entry); why default = Windows; how it's wired into `project-bootstrap` -- [bootstrap-claude-md-merge.md](concepts/bootstrap-claude-md-merge.md) — project-bootstrap@1.3.0 — Step 5 upgrade path becomes idempotent merge (read → diff vs template → confirm → append missing); fixes silent gap where pre-1.2.0 projects never picked up new canonical triggers (`check across all projects`, `we're on Windows`) -- [bootstrap-skill-deps-check.md](concepts/bootstrap-skill-deps-check.md) — project-bootstrap@1.7.0 — Step 5.6 collapses the per-skill "detect-and-recommend" mirror shape into one generic `trigger → fulfiller` table walker (skill vs plugin kind, never auto-install); subsumes the deferred `[bootstrap-recommend-projects-meta]` and the existing `superpowers`-only detector -- [bootstrap-manifest.md](concepts/bootstrap-manifest.md) — record of which `project-bootstrap` / `setup-wiki` / `setup-tasks` versions initialized this project's `.wiki/` and `.tasks/` layout (overwritten on re-bootstrap; history in git) -- [build-notes.md](concepts/build-notes.md) — why `build.ps1` exists alongside `build.sh`; PS 5.1 backslash-in-zip gotcha; how to extract a `.skill` -- [install-cross-platform.md](concepts/install-cross-platform.md) — paired-script parity contract for `install.{ps1,sh}` AND `build.{ps1,sh}`; rationale for the `--prune` / `-Prune` flag (combined-with-action, global-scan, default-off); install-side prunes target dirs, build-side prunes `dist/*.skill` files -- [install-portability.md](concepts/install-portability.md) — `install.sh` / `build.sh` rewritten to drop `mapfile` (bash 4+) and `find -printf` (GNU only) so stock macOS (bash 3.2 + BSD find) works -- [context7-setup.md](concepts/context7-setup.md) — context7 CLI-first (2026-08-12): `ctx7` CLI + key in `~/.config/projects-secrets/ctx7.env`, plugin `context7@claude-plugins-official` + manual MCP entries removed; setup-context7 skill (one-time install/migrate, confirmation gates) + using-context7 policy; plugin era = rollback reference -- [projects-meta-skills.md](concepts/projects-meta-skills.md) — `setup-projects-meta` + `using-projects-meta` skill pair for the local `projects-meta-mcp` stdio server (cross-project tasks + shared Gitea wiki); local-first rule + two-step mutation pattern -- [project-discipline-design.md](concepts/project-discipline-design.md) — design for project-discipline (four cross-project rules: conventions-over-defaults, master-only, semver-bumping, ask-before-push) -- [pulling-before-work-design.md](concepts/pulling-before-work-design.md) — design for the pulling-before-work skill (mode-3 + skip-on-dirty) -- [repo-layout.md](concepts/repo-layout.md) — flat `skills/`, committed `dist/`, bash + PowerShell scripts; install model -- [skill-versioning.md](concepts/skill-versioning.md) — why infra skills carry `version: ` in frontmatter and how `project-bootstrap` records them in a per-project manifest -- [skill-vs-plugin.md](concepts/skill-vs-plugin.md) — when a bare SKILL.md is enough vs when you actually need a plugin (slash commands, hooks, sub-agents, MCP servers); concrete breakdown of `superpowers` -- [wiki-realignment.md](concepts/wiki-realignment.md) — fixing `project-bootstrap` to create the Karpathy-canonical wiki layout -- [interns-design](concepts/interns-design.md) — interns-design -- [compress-dedup.md](concepts/compress-dedup.md) — `skills/compress/` deleted as a byte-identical dupe of `skills/caveman-compress/`; canonical kept for README + SECURITY + caveman-toolkit branding; better Process-step wording ported across; `version: 1.0.0` added to caveman-compress frontmatter -- [active-platform-eval-design.md](concepts/active-platform-eval-design.md) — spec for eval-driven tuning of `active-platform`: combine the two ⚪ tasks into one workstream, 20-query cross-platform eval set (≥3 per OS + near-miss negatives), `run_loop.py` autoloop **in parallel** with manual body sweep (WSL / BSD / ambiguity), version 1.0.0 → 1.1.0 (MINOR). Status: paused after design + pre-flight check, before eval-set authorship -- [interns-repo-read-design](concepts/interns-repo-read-design.md) — interns-repo-read-design -- [hermes-skills-rollout-design](concepts/hermes-skills-rollout-design.md) — hermes-skills-rollout-design -- [tdd-criteria-design](concepts/tdd-criteria-design.md) — tdd-criteria-design -- [project-bootstrap-meta-isolation.md](concepts/project-bootstrap-meta-isolation.md) — project-bootstrap@1.11.0 — Step 1 ships meta-isolation block in `.gitignore` (`!.claude/`, `!.tasks/`, `!.wiki/`, ...) so own greenfield/upgrade projects re-enable agent meta-paths against global `core.excludesFile` cutter. Marker-based append-only on existing files; smoke-tested with negative control -- [interns-grep-audit-design](concepts/interns-grep-audit-design.md) — interns-grep-audit-design -- [session-handoff-skill-design.md](concepts/session-handoff-skill-design.md) — design rationale for the `session-handoff` skill (sliding overwrite into `.tasks/NEXT_SESSION.md`, phrase whitelist + substantive-commit heuristic, optional PostToolUse hook for harness-side determinism, orient+ask default, project scope, cluster 7/7 closure) -- [using-tasks-session-break.md](concepts/using-tasks-session-break.md) — `using-tasks` v1.2.0 `session_break` marker: task-author-set boolean/string flag; after a task closes 🟢, before `tasks_claim_next`, an autonomous agent prints the verbatim SESSION BOUNDARY line and stops instead of chaining the next task. Absent → unchanged -- [delegate-task-session-break.md](concepts/delegate-task-session-break.md) — `delegate-task` v0.2.2 — authoring side of the `session_break` marker (consumer = [[using-tasks-session-break]]): pre-flight Q6 + optional template field `session_break: true | ""`; three set-it cases (domain-switch / milestone / heavy infra); not a default -- [delegate-task-review-weight.md](concepts/delegate-task-review-weight.md) — `delegate-task` v0.2.3 — Step 5 review-task now sets explicit `weight`, inherited from impl with a `needs-claude` floor (impl `needs-human`→review `needs-human`; `cheap-ok`→`needs-claude`). Fixes the reconciler skipping weightless review tasks (root cause of manual patch `c0af151`) -- [using-system-snapshot-design.md](concepts/using-system-snapshot-design.md) — `using-system-snapshot` v0.1.0 — thin read-only skill wrapping the single `mcp__projects-meta__meta_system_snapshot` call (poller + local docker + cached task summary); replaces scattered `tasklist`/`docker ps`/manual `meta_status`; core rule = no liveness claim without calling the tool this turn; three-line output; defers deep docker to [[using-vds-ops]] and precise tasks to [[using-projects-meta]] -- [using-tasks-status-archival.md](concepts/using-tasks-status-archival.md) — `using-tasks` v1.3.0 done-task archival rule (≥10 🟢 → `.tasks/archive/YYYY-MM.md`) fixes STATUS.md bloat; documents why `tasks_get_status` (single-task, by slug) / `tasks_aggregate` (cross-project cache) can't replace the orientation board-read, so the literal task instruction was not followed -- [delegate-task-negative-trigger-fp.md](concepts/delegate-task-negative-trigger-fp.md) — `delegate-task` v0.2.1 FP fix: «создать задачу себе» stem-matched the «создать задачу на агента» positive trigger; abstract "does NOT apply when doing the work yourself" carve-out loses to literal stem-match under the 1%-rule → made the negative literal + routed (→ using-tasks). Verified pos 5/5, neg 4/5 (was 0/5) -- [using-markitdown-cli-migration.md](concepts/using-markitdown-cli-migration.md) — `using-markitdown` v1.0.0→v1.0.1 (PATCH): rewrote from the Docker-based `mcp__markitdown__convert_to_markdown` MCP tool to the native `markitdown` CLI (0.1.6, on PATH); dropped the host→container `file://` mount caveat; container decommission is by image ancestor (`--filter ancestor=markitdown-mcp:latest`), not by the non-existent name `markitdown-mcp` -- [session-inbox-monitor-received-msg-fp.md](concepts/session-inbox-monitor-received-msg-fp.md) — sibling of [[delegate-task-negative-trigger-fp]]: `session-inbox-monitor` FP-fires on RU «обработай полученное письмо» (N1) because its literal+routed carve-out points at `inter-session-peer-discipline`, which **isn't installed** → no competitor, nearest inbox-skill wins. Borderline (neg 2/3, EN twin clean), body-load self-corrects. **Open** (follow-up task). New principle: *a routed negative competes only if its route target is installed* -- [task-format-design.md](concepts/task-format-design.md) — new `task-format` skill v0.1.0: public reference for the on-disk `.tasks/STATUS.md` block format the poller parses (header regex, status emoji, `**Weight:**` / `**Notify:**` / `**Requirements:**`); ships with `factory` where the internal wiki/MCP-source can't reach; distinct from [[delegate-task]] (MCP-tool delegation) and [[using-tasks]] (board mechanics); RED 3-baseline / GREEN 2-verify per writing-skills; ground truth = `status-md.ts` + `claim.ts` + `fleet-router.js` - -## Packages - - - -## Summaries - - -- [pi-extension-headless-ritual.md](concepts/pi-extension-headless-ritual.md) — agent_end (not agent_settled) for followUp injection; mode guard (`print` not hasUI); loop-guard flag-before-send; opt-in mirrors skill +# ⛔ Файловый канал закрыт +**Не читать. Не править.** Канон — mappa (`mcp__mappa__*`): wiki-сущности проекта, конвенции — AGENTS-сущность. Скил: `mappa-knowledge`. diff --git a/.wiki/log.md b/.wiki/log.md index 82db918..21695bc 100644 --- a/.wiki/log.md +++ b/.wiki/log.md @@ -1,82 +1,3 @@ -# Wiki Log +# ⛔ Файловый канал закрыт -Append-only operation log. One entry per operation. Format: - -``` -## [YYYY-MM-DD] | -``` - -Operations: `init`, `ingest`, `query`, `lint`, `refactor`, `decision`. - -Parseable: `grep "^## \[" .wiki/log.md | tail -20`. - ---- - -## [2026-04-28] init | bootstrap empty wiki via project-bootstrap (old layout) -## [2026-04-28] decision | repo-layout — flat `skills/`, committed `dist/`, bash + PS scripts -## [2026-04-28] decision | build-notes — PS 5.1 Compress-Archive backslash bug; build.ps1 via .NET ZipArchive -## [2026-04-28] decision | active-platform — skill chosen over global CLAUDE.md / project memory; default Windows; wired into project-bootstrap -## [2026-04-28] refactor | wiki-realignment — fixed project-bootstrap Step 3 to create Karpathy-canonical layout -## [2026-04-28] refactor | this repo's `.wiki/` migrated to canonical layout (SUMMARY.md→index.md, source/→concepts/, added log.md/overview.md/CLAUDE.md schema, raw/README.md) -## [2026-04-28] decision | context7-setup — switched to official plugin; --api-key injected into plugin's .mcp.json; three manual MCP entries removed -## [2026-04-28] decision | setup-context7 skill — formalized the install/migrate algorithm; using-context7 gets a Prerequisites pointer; build.sh PS multi-arg bug fixed (loop instead of comma-joined -Names) -## [2026-04-28] verify | setup-context7 — Vitya ran using-context7 in a session that needed setup; Prerequisites pointer triggered setup-context7; full flow worked end-to-end. Pattern (policy + setup split) validated. -## [2026-04-28] decision | skill-vs-plugin — documented when a bare skill suffices vs when a plugin is required (slash commands, hooks, sub-agents, MCP via marketplace) -## [2026-04-28] decision | skill-versioning — added `version: 1.0.0` to 6 infra skills' frontmatter; project-bootstrap now writes .wiki/concepts/bootstrap-manifest.md per project -## [2026-04-28] refactor | wiki split — `wiki-maintainer` renamed to `using-wiki` (policy); new `setup-wiki` skill owns greenfield creation and canon migration; `project-bootstrap` Step 3 delegates -## [2026-04-28] refactor | tasks split — `task-status-wiki` renamed to `using-tasks` (policy); new `setup-tasks` skill owns greenfield + interactive migration (no auto-parsing of old flat STATUS.md); `project-bootstrap` Step 4 delegates -## [2026-04-28] refactor | this repo's `.tasks/` migrated to canonical layout — flat `## Done`/`## Backlog` replaced by emoji-status board (7 ⚪ Ready blocks); historical Done entries dropped (preserved in git log); `.bak` ignored via .gitignore -## [2026-04-28] cleanup | removed stale `~/.claude/skills/{wiki-maintainer,task-status-wiki}/` installs (replaced by `using-wiki`/`using-tasks`); 16 skills installed, no duplicates; context7 plugin (mcp__plugin_context7_context7__*) confirmed live after restart -## [2026-04-28] decision | install-portability — `install.sh`/`build.sh` patched to drop `mapfile`+`find -printf`; stock macOS (bash 3.2 + BSD find) now works; verified on git-bash (16 skills discovered, sorted, installed; build.sh produces archive) -## [2026-04-29] decision | projects-meta-skills — built `setup-projects-meta` (8-phase install of projects-meta-mcp + auth.toml + MCP registration) and `using-projects-meta` (runtime policy with local-first rule and two-step mutation); skill pair pattern applied for the 4th time (context7 / wiki / tasks / projects-meta); both built + installed; visible to the harness -## [2026-04-30] refactor | projects-meta-skills — wiki path canon corrected: `~/projects/.wiki` → `~/projects/projects-wiki/` (clone root), content at `~/projects/projects-wiki/.wiki/`. Old path caused write/read mismatch bug (fixed upstream in commit `621a69f` of `projects-meta-mcp`). Setup-projects-meta Phase 1 now detects legacy clone, Phase 4 re-clones to canon. Lesson: pull shared resources before relying on cached anchors -## [2026-04-30] decision | using-projects-meta v1.1.0 — added mandatory Step 0 freshness gate: probe `meta_status`; if cache_age > 10min or errors > 0, `node dist/sync.js`; for shared-wiki writes unconditional `git -C ~/projects/projects-wiki pull --ff-only`; 401/403 → loud failure to user. Codifies the same-session lesson — `projects-meta` is a multi-machine bus, stale cache breaks read accuracy and write atomicity -## [2026-04-28] decision | project-bootstrap@1.1.0 — added Step 5.6: detects `superpowers@claude-plugins-official` via `~/.claude/plugins/installed_plugins.json` and prints install command + upstream link if missing; chat-only, never auto-installs (slash commands aren't callable from a skill, and silent plugin install is overreach) -## [2026-04-28] doc | README.md + README.ru.md — new "Using skills in projects" / "Использование в проектах" section after install quick-start; describes project-bootstrap workflow (git, .gitignore, README, .wiki/, .tasks/, CLAUDE.md, manifest, superpowers-plugin check) and the init/upgrade modes -## [2026-04-30] refactor | project-bootstrap re-run on this repo (upgrade mode) — setup-wiki noop, setup-tasks noop, CLAUDE.md unchanged (matches template), bootstrap-manifest.md written: project-bootstrap@1.1.0 / setup-wiki@1.0.0 / setup-tasks@1.0.0 -## [2026-04-30] decision | project-bootstrap@1.2.0 — CLAUDE.md template gains `check across all projects` (verbatim trigger from using-projects-meta description); installs auto-load cross-project tasks + shared-wiki access in every bootstrapped repo; no Step 5.7 dependency-check mirror — Prerequisites pointer in using-projects-meta is self-correcting; local CLAUDE.md, both READMEs, dist/.skill, projects-meta-skills concept page synced -## [2026-04-30] decision | Step 5.7 mirror of Step 5.6 (projects-meta-mcp dependency detector / `setup-projects-meta` recommendation) accepted as future work; tracked as ⚪ Ready task `[bootstrap-recommend-projects-meta]`; deferred until first observed fresh-machine miss so detector signal is informed by real failure mode; concept page `projects-meta-skills.md` updated to reflect new stance -## [2026-04-30] decision | project-bootstrap@1.3.0 — Step 5 upgrade path turned idempotent: read existing CLAUDE.md → substring-diff vs template → confirm → append-only-missing; closes silent gap where pre-1.2.0 projects never picked up new canonical triggers (`check across all projects`, `we're on Windows`); platform line preserved if user pinned a non-host one; concept page `bootstrap-claude-md-merge.md` written; README CLAUDE.md row updated to note idempotent merge -## [2026-05-01] decision | pulling-before-work — new policy skill (v1.0.0): one `git pull --ff-only` at session start + on-demand re-sync; bootstrap template gains canonical trigger; project-bootstrap 1.3.0→1.4.0 -## [2026-05-01] decision | project-discipline — new policy skill (v0.1.0): four cross-project rules (conventions-over-defaults, master-only, semver-bumping, ask-before-push); bootstrap template gains canonical trigger; project-bootstrap 1.4.0→1.5.0; skill-versioning concept extended to all skills -## [2026-05-01] ingest | shared-wiki packages/claude-skills — каталог всех 20 скиллов опубликован в projects-wiki (3 commits: page + index + log on Gitea, ae2cc9a..001cdd0); группировка bootstrap / wiki+tasks / MCP / caveman / discovery+platform; cross-link с concepts/setup-using-skill-pair и packages/projects-meta-mcp - -## [2026-05-05] ingest | concepts/interns-design -## [2026-05-05] decision | interns-skills-mvp — shipped `setup-interns` v0.1.0 (8-phase install: detect `.common/lib/interns-mcp/`, `pip install -e`, `.common/secrets/interns.env` write, `mcpServers.interns` registration with absolute Python interpreter + `cwd`) and `using-interns` v0.1.0 (runtime policy mirroring project-discipline Rule 4: ask-mode default, conversational grant/revoke, always-ask paths for `.env`/secrets/keys/SSH/credentials with transitive rule, cost-cap >$0.10, session-end reset; routing hints for `bulk_text_read` + `transcript_distill`); `project-bootstrap` 1.5.0→1.6.0 with canonical CLAUDE.md trigger `delegate to interns when allowed` between `follow project discipline` and `we're on Windows`, Step 5 commentary paragraph, manifest table extended with both new skills + `project-discipline` row; root `CLAUDE.md` dogfood updated; both READMEs written; descriptions verified (setup-interns 899 chars, using-interns 814 chars, both under 900 budget); all three rebuilt + installed + listed by harness with full descriptions (no H1 fallback) -## [2026-05-05] ingest | concepts/bootstrap-skill-deps-check -## [2026-05-05] decision | bootstrap-skill-deps-check — `project-bootstrap` 1.6.0→1.7.0 collapses Step 5.6 from a single-skill detector (only `superpowers` plugin) into a generic `trigger → fulfiller` table walker. Map embedded in SKILL.md (9 rows: caveman, superpowers plugin, using-wiki, using-tasks, using-projects-meta, pulling-before-work, project-discipline, using-interns, active-platform); `kind: skill` vs `kind: plugin` flag drives the install command emitted in the recommendation block. Algorithm: read project's CLAUDE.md → match each line vs map (substring + tolower, mirrors Step 5 idempotent merge) → for each canonical match check disk (`~/.claude/skills//SKILL.md` or `installed_plugins.json` key); print one chat-only block listing every missing fulfiller + install commands, or one ✅ line if all satisfied. User-custom lines silently skipped; removed canonical lines silently skipped (respects user opt-out). Hard rule "never auto-install" carries over verbatim. Subsumes the deferred `[bootstrap-recommend-projects-meta]` task (closed by absorption — generic step handles `using-projects-meta` along with everything else). MCP-server-backed skills only check the `using-X` policy skill; `setup-X` self-fires on first use via Prerequisites pointer, bootstrap doesn't duplicate. -## [2026-05-05] decision | compress-dedup — `skills/compress/` was a stripped-down byte-for-byte dupe of `skills/caveman-compress/` (scripts/ identical SHA256 across all 7 files; SKILL.md diff = `name:` + Process step 2; descriptions textually identical = arbitrary harness tie-break + double-counted listing budget). Kept `caveman-compress` canonical: it carries README.md (benchmarks table + caveman-toolkit branding) and SECURITY.md (Snyk false-positive writeup), and matches the caveman-* prefix invariant. Ported the better Process-step wording from `compress` into `caveman-compress` (`cd ` instead of brittle `cd caveman-compress` which assumes cwd). Added `version: 1.0.0` to caveman-compress frontmatter (first versioned release; aligns with skill-versioning concept). Deleted: `skills/compress/`, `dist/compress.skill`, `~/.claude/skills/compress/` (manual prune — install.sh has no prune step; future `[install-ps1]` task should add `--prune` flag). Rebuilt + reinstalled `caveman-compress`. Slash-command impact: `/compress` removed; `/caveman-compress` + `/caveman:compress` (toolkit-canonical) remain. Concept page `concepts/compress-dedup.md` written (rationale + rejected alternatives: alias-stub has no harness mechanism; "keep both" wastes listing budget; "delete caveman-compress" loses README + SECURITY). -## [2026-05-05] design | active-platform-eval (paused) — combined `[active-platform-tuning]` + `[active-platform-eval]` into one workstream (eval *is* the tuning mechanism; "wait for 5 real signals" was a placeholder). Spec written at `.wiki/concepts/active-platform-eval-design.md`: 20-query trigger eval set balanced ≥3 should-trigger per OS (Win/Lin/Mac) + near-miss negatives, run in `skill-creator/scripts/run_loop.py` (5 iter, train/test split, model `claude-opus-4-7`) **in parallel** with manual body sweep (WSL clarity, BSD/macOS expansion, ambiguity policy). Workspace at `.tasks/active-platform-eval/` (eval-set.json committed, iterations gitignored). Version bump 1.0.0 → 1.1.0 planned (MINOR). Pre-flight verified: `claude` CLI at `C:\nvm4w\nodejs\claude.ps1` (Claude Code 2.1.128) + `run_loop.py` present in skill-creator install — both autoloop deps satisfied, no fallback needed. Per-task file at `.tasks/active-platform-eval.md`. Paused at user request before eval-set authorship; resume point is Q2 (write 20 queries solo vs run skill-creator HTML-review template for user edits first). Also fixed in same pause: `[install-ps1]` STATUS scope expanded to "paired install.sh + install.ps1, cross-platform parity, --prune flag" (lesson from `[compress-dedup]`). - -## [2026-05-05] ingest | concepts/interns-repo-read-design - -## [2026-05-06] ingest | concepts/hermes-skills-rollout-design - -## [2026-05-07] ingest | concepts/tdd-criteria-design - -## [2026-05-07] review | tdd-criteria v0.2.0 — 4 findings applied: trigger-loophole fix (removed session-authorship clause), composite-tasks + refactoring sections, expanded file-extension list, clarified wrapper line-count + spike-survivor fallback + foreign-schema fix; design doc synced - -## [2026-05-10] decision | project-bootstrap-meta-isolation — v1.11.0 ships meta-isolation block in `.gitignore` template + Step 1 upgrade-case append; restores agent meta-paths visibility against global `core.excludesFile`; smoke-tested greenfield + negative control + idempotency - -## [2026-05-22] ingest | concepts/interns-grep-audit-design - -## [2026-05-25] decision | session-handoff-skill-design — design rationale for the `session-handoff` skill captured in wiki after cluster 7/7 closure; sliding overwrite of `.tasks/NEXT_SESSION.md`, phrase whitelist + substantive-commit heuristic, opt-in PostToolUse hook, orient+ask default, source: `~/projects/.workshop/.archive/2026-05-24-session-handoff-skill.md` Round 1 + Round 2 - -## [2026-05-25] decision | install-cross-platform — `install.{ps1,sh}` paired-script parity contract documented; `--prune` / `-Prune` flag rationale (combined-with-install, global-scan ignores names filter, default-off, print-and-delete no prompt); shipped in commit `6cf0e98` with `[skip-tdd: wrapper]` carve-out + smoke-test evidence; closes 2/3 of `[install-ps1]` acceptance (the doc + flag), `dist/`-prune analogue deferred to `build` scripts - -## [2026-05-25] decision | install-cross-platform extended to build scripts — `build.{ps1,sh}` get the symmetric `--prune` / `-Prune` flag (removes `dist/.skill` where `` is not in `skills/`). Bash delegation to `powershell.exe -File build.ps1` does NOT forward the flag — bash runs prune itself against the shared `dist/`. Both paths smoke-tested with fake stale .skill files against real dist/. Closes `[install-ps1-build-prune-followup]`. - -## [2026-06-09] decision | delegate-task-negative-trigger-fp — `delegate-task` 0.2.0→0.2.1 (PATCH): fixed 5/5-consistent false-positive on «создать задачу себе». Root cause: self-task phrase shares stem «создать задачу» with the «создать задачу на агента» positive trigger; the abstract "Does NOT apply when doing the work yourself" carve-out can't beat a literal stem-match under the 1%-rule. Fix: made the negative literal + routed («создать задачу себе» / «task for myself» / «поставить себе задачу» → using-tasks) in description + body disambiguator («на агента»/«агенту» = delegate; «себе» = own board). Re-verified via fresh-context subagent trigger run: positives 5/5 (no regression), negative 4/5 → using-tasks (was 0/5); the 1 residual miss was an eval-harness artifact (forced skill-name-before-reasoning), not description ambiguity. Concept page written; reusable principle = put the exact colliding negative phrase with an explicit →sibling route, literal beats abstract. -## [2026-06-09] decision | delegate-task-session-break — `delegate-task` 0.2.1→0.2.2 (PATCH): authoring side of the `session_break` marker (consumer = using-tasks v1.2.0). Added pre-flight Q6 (after notify): "Session-break после этой задачи? (domain-switch / milestone / heavy infra)"; if yes → set optional template field `session_break: true | ""` (trailer, next to weight/notify/allow_upgrade; same lowercase frontmatter key using-tasks reads). Usage guidance lists three set-it cases; What-NOT-to-do bullet warns against setting it routinely (it's a real-boundary marker, not a default). Wiki concept page concepts/delegate-task-session-break.md + index. Pairs with using-tasks-session-break. -## [2026-06-09] decision | using-system-snapshot — new skill v0.1.0: thin read-only wrapper over the single `mcp__projects-meta__meta_system_snapshot` call (poller status + local docker containers + cached cross-project task summary). Replaces the scatter of `tasklist` + `docker ps` + manual `meta_status`. Core rule: no claim about poller / local-docker / task-load state without calling the tool in the current turn (memory + stale earlier snapshot ≠ evidence). Output = three lines, one per section (docker lists only problem containers; tasks gives Σ active/blocked + busiest 2–3). Liveness split documented: poller+docker live, tasks from cache (defer precise work to using-projects-meta Step 0). Scope boundaries: deep single-container diagnosis → using-vds-ops / `docker logs`; docker section is LOCAL, not the VDS. Read-only, no per-session grant (mirrors using-vds-ops). Output shape verified by a live call 2026-06-09. Concept page concepts/using-system-snapshot-design.md + index. TDD N/A (markdown policy artifact); behavioral smoke-test = paired skill-using-system-snapshot-review task. -## [2026-06-09] review | using-system-snapshot v0.1.0 — VERDICT PASS on all 3 acceptance criteria (skill-using-system-snapshot-review). Tool contract verified by a live `meta_system_snapshot` call (output matches the documented `poller`/`docker`/`tasks` shape exactly). Behavioral trigger smoke = 9 fresh-context subagents over a simulated registry (real descriptions + using-vds-ops/using-projects-meta/using-tasks competitors, no expected-answer hint): 4/4 positives → using-system-snapshot; VDS-logs → using-vds-ops; mutate/full-board → using-projects-meta; `docker-compose.yml` edit → none (no FP on "docker" keyword). No-claim-without-snapshot rule explicit in 4 places; three-line output format confirmed achievable against the live payload. 3 informational findings (none blocking): (1) cross-project task-COUNT phrasings overlap with using-projects-meta — by-design, snapshot defers precise per-task work; (2) LOCAL-container deep diagnosis is unowned — vds-ops incident triggers grab local containers its VDS-only tools can't reach (vds-ops scoping, not this skill); (3) deployment scaffold missing — skill committed but not installed to `~/.claude/skills/`, not in `hermes/mapping.yaml`, no -install/-hermes-mapping/-test-trigger baseline tasks; recommended follow-ups (hermes mode could be `auto`, read-only skill). Review outcome appended to concepts/using-system-snapshot-design.md. -## [2026-06-09] decision | using-tasks-status-archival — `using-tasks` 1.2.0→1.3.0 (MINOR): added done-task archival rule to fix STATUS.md bloat ("huge STATUS.md" complaint). When ≥10 🟢 done blocks pile up — checked at session start (step 7) and after close (Task completion step 7) — move them verbatim to `.tasks/archive/YYYY-MM.md` (append, one file per month, one-time header), leaving only 🔴/🟡/⚪/🔵 on the board; committed on its own. Did NOT follow the task's literal instruction to replace `Read STATUS.md` with `tasks_get_status` for orientation: that tool returns a single task's live status by known slug (`{status, found}`) and cannot enumerate the board, and `tasks_aggregate` is cross-project + cache-based + doesn't index ready/done (its docs say read STATUS.md directly for the current project). So orientation stays a local board-read (kept cheap by archival); skill now warns against both tools for board enumeration and points `tasks_get_status` at its real single-task use. Core goal (kill the bloat) met by archival alone. Concept page concepts/using-tasks-status-archival.md + index. TDD N/A (markdown policy). Deviation flagged for paired review task using-tasks-status-read-perf-review. -## [2026-06-09] decision | using-tasks-session-break — `using-tasks` 1.1.0→1.2.0 (MINOR): added the `session_break` marker. Task author sets `session_break: true | ""` in task frontmatter (mirrored as `**Session break:**` on the local board); after the task closes 🟢, before `tasks_claim_next`, an autonomous agent prints the verbatim line `🔚 SESSION BOUNDARY — [slug] закрыта. Рекомендую завершить текущую сессию. Следующий трек: [value | "см. STATUS.md"]` and stops instead of chaining the next task. Absent → behaviour unchanged. Enforced in Task completion step 6 + Rules bullet + format docs. Marker not heuristic: the stop-point is an authoring choice, not a runner guess. -## [2026-06-09] review | using-tasks-status-archival v1.3.0 — VERDICT PASS 3/3 (using-tasks-status-read-perf-review). Criterion «ориентация через `tasks_get_status`, не Read» is satisfied by a **validated deviation**, not a literal swap: re-verified against the live tool schema that `tasks_get_status(target_project, slug)→{status, found}` takes a required slug and returns ONE task — it cannot enumerate the board, so it cannot drive orientation; the implementer correctly rejected the impossible instruction and fixed the real problem (bloat→archival). No regression: orientation still reads local STATUS.md (Session start §2) and the «what's next» flow still reads the board — change is purely additive. Archival rule clear & complete (≥10 threshold, two trigger points, monthly append-only archive, verbatim blocks, dedicated commit, cross-referenced). One informational non-blocking note: this repo's own STATUS.md (>10 🟢) would itself trip the rule — dogfooding tracked separately as tasks-board-cleanup-2026-05. No follow-up tasks. Verdict appended to concepts/using-tasks-status-archival.md. -## [2026-06-09] decision | delegate-task-review-weight — `delegate-task` 0.2.2→0.2.3 (PATCH): Step 5 (paired `-review` task) now sets an explicit `weight`, inherited from the impl-task with a `needs-claude` floor (impl `needs-human`→review `needs-human`; `needs-claude`→`needs-claude`; `cheap-ok`→`needs-claude`). Root cause of commit `c0af151` ("add Weight: needs-claude to 4 review tasks — reconciler was skipping them"): the authoring skill omitted `weight` on review tasks, making them invisible to fleet routing. Floor (not pure inheritance) chosen to stay internally consistent with the skill's own "What NOT to do" bullet that forbids `cheap-ok` for review tasks — a `cheap-ok` impl would otherwise propagate a forbidden `cheap-ok` review. Added a What-NOT-to-do bullet against weightless review tasks. Concept page concepts/delegate-task-review-weight.md + index. TDD N/A (markdown policy artifact). -## [2026-06-11] decision | task-format — new skill v0.1.0: public reference for the `.tasks/STATUS.md` task-block format the autonomous poller parses. Motivation: the field rules (`**Weight:**` capability/cost tier, `**Notify:** /` inbox target, header regex, status emoji) lived only in internal sources (`projects-meta-mcp/src/lib/status-md.ts` parser + `status-md-writer.ts` + `.common/.wiki/concepts/agents-task-runner-ops.md`); skills ship with `factory` to external users, the wiki/MCP-source don't. Scope kept distinct from delegate-task (creates tasks for others via `tasks_create`, the tool emits the format) and using-tasks (board claim/close mechanics) — task-format is the byte-level field reference for hand-edited blocks. Ground truth verified against source: header `/^##\s+(\S+)\s+\[([^\]]+)\]\s+—\s+(.+)$/u`; Weight ∈ {cheap-ok, needs-claude, needs-human}; claim gate excludes only `needs-human` (`claim.ts`), but a *missing* Weight finds no backend tier (`fleet-router.js` resolveBackend) → poller parks to 🔵 blocked, so Weight is operatively required for pickup. TDD per writing-skills: RED = 3 baseline subagents w/o skill (2/3 used `###`/bullet headers the parser can't recognize, 2/3 omitted Weight inventing `risk`/`tier`/`claimable-by`, 2/3 put notify in prose, 1/3 used 🟢 for ready); GREEN = 2 fresh subagents w/ skill, both parser-valid incl. correct `needs-human` for the critical-infra scenario; REFACTOR = no new loopholes. Reference skill ~900 words (loads only when authoring a task block). Concept page concepts/task-format-design.md + index. Not yet installed to `~/.claude/skills/` or added to hermes mapping — deferred follow-up (mirrors using-system-snapshot deployment-scaffold note). -## [2026-06-09] decision | using-markitdown-cli-migration — `using-markitdown` 1.0.0→1.0.1 (PATCH): rewrote the skill from the Docker-based `mcp__markitdown__convert_to_markdown` MCP tool to the native `markitdown` CLI (v0.1.6, on PATH). Tool block now `markitdown ` → stdout (or `-o file`); removed the whole "Docker-mount caveat (READ FIRST)" section (host→container `file://` translation + `[Errno 2] /c:/Users/...` symptom are gone — CLI sees the full host FS). Updated the ingest pattern (use `-o` straight into `.wiki/raw/`), the gotchas table (`command not found` → check `markitdown --version`, install `pip install markitdown[all]`; dropped the MCP "tool not available / ToolSearch" row), and the contrast-table header (CLI, not MCP). Description frontmatter (the WHEN-to-use triggers) left unchanged. Container decommission: the task's literal `docker stop/rm markitdown-mcp` had no target — no container is named that; the MCP spawns anonymously-named containers from `markitdown-mcp:latest` per session (3 had piled up). Removed all by image ancestor (`docker rm -f $(docker ps -aq --filter "ancestor=markitdown-mcp:latest")`), verified none remain. Left the `mcpServers.markitdown` entry in `~/.claude.json` untouched (out of scope; a container will respawn next session until it's deregistered — flagged as a follow-up). Concept page concepts/using-markitdown-cli-migration.md + index. TDD N/A (markdown skill). -## [2026-06-17] decision | session-inbox-monitor-received-msg-fp — finding from `session-inbox-monitor-test-trigger` (VERDICT PASS, clean session, 7 unprimed clean-context subagents: pos 4/4 incl. CLAUDE.md-line P4, neg 2/3). The 1 FP: RU «обработай полученное письмо из инбокса» (N1) routed to `session-inbox-monitor`; the EN twin (N3) and the multi-machine-backend negative (N2) routed to `none` cleanly. Root cause = a new dimension on top of [[delegate-task-negative-trigger-fp]]: the carve-out is already literal+routed (`NOT for handling a received message → inter-session-peer-discipline`), but the route target `inter-session-peer-discipline` is **not installed** → no real competitor, so the nearest in-domain skill (session-inbox-monitor) wins by default; non-deterministic, self-corrects on body-load (cost = one wasted skill-load, not a wrong action; isomorphic to [[using-tasks-session-break]] session_break). New page concepts/session-inbox-monitor-received-msg-fp.md + bidirectional link from concepts/delegate-task-negative-trigger-fp.md + index. New reusable principle: a routed negative competes only if its route target is installed. Status OPEN — follow-up task session-inbox-monitor-received-msg-fp (options a: harden description / b: install sibling / c: accept informational). Not a memory entry by owner direction — knowledge belongs in the project wiki. -## [2026-06-17] decision | session-inbox-monitor-received-msg-fp RESOLVED via option (b) — installed `inter-session-peer-discipline` (existed in sources since 2026-06-16, was not installed → exact root cause confirmed). install.ps1 -Names, byte-identical parity. FP-twin verified clean: fresh clean-context subagent on the N1 phrase now routes to inter-session-peer-discipline (IN_REGISTRY: yes), not session-inbox-monitor — carve-out now has a real competitor. session-inbox-monitor description untouched (option (a) rejected as whack-a-mole; (c) as latent hole). Governance: peer workshop proposed (b) as a "ruling"; per the freshly-installed [[inter-session-peer-discipline]] (peer = proposal not authority, scope needs human ratification) it was surfaced as a recommendation and ratified by the user — live dogfood of the skill's own purpose. concepts/session-inbox-monitor-received-msg-fp.md Status section updated open→resolved. Tail: inter-session-peer-discipline now installed but not in hermes/mapping.yaml — possible red build, flagged as separate follow-up. -## [2026-08-12] ingest | pi-extension-headless-ritual — agent_end/mode-guard/loop-guard lessons from session-close-ritual build -## [2026-08-13] refactor | context7-setup — concept updated to CLI-first canonical (setup-context7 v2.0.0 migration, 2026-08-12): ctx7 CLI + key in ~/.config/projects-secrets/ctx7.env, plugin + manual MCP removed; plugin era demoted to rollback reference; whoami!=key-check gotcha recorded; index entry refreshed +**Не читать. Не править.** Канон — mappa (`mcp__mappa__*`): wiki-сущности проекта, конвенции — AGENTS-сущность. Скил: `mappa-knowledge`. diff --git a/.wiki/overview.md b/.wiki/overview.md index 244e82e..21695bc 100644 --- a/.wiki/overview.md +++ b/.wiki/overview.md @@ -1,29 +1,3 @@ ---- -title: claude-skills overview -type: overview -updated: 2026-04-28 ---- +# ⛔ Файловый канал закрыт -# claude-skills — overview - -Joint workshop where Vitya and Claude develop, test, and store Claude skills. Both editable sources (`skills//`) and built archives (`dist/.skill`) live here, so a fresh machine can clone the repo and install every personal skill in one command. - -## Components - -- **`skills/`** — editable skill sources, one folder per skill (each with `SKILL.md` + optional `assets/`). -- **`dist/`** — built `.skill` archives, committed so installs don't need a build toolchain on the target. -- **`scripts/`** — `build.sh` / `build.ps1` (zip sources → archive), `install.sh` (copy sources → `~/.claude/skills/`). -- **`.wiki/`** — Karpathy LLM Wiki for design decisions and gotchas. See [CLAUDE.md](CLAUDE.md) for schema. -- **`.tasks/`** — task board (`STATUS.md`). -- **`CLAUDE.md`** — repo-level agent instructions (skill triggers). - -## Where to look - -- New here? → [concepts/repo-layout.md](concepts/repo-layout.md), then `README.md`. -- Working on a skill? → edit `skills//`, then `bash scripts/install.sh ` (or `pwsh scripts/build.ps1 ` to refresh the archive). -- Tracking work? → [.tasks/STATUS.md](../.tasks/STATUS.md). -- Made a non-trivial decision? → add a `concepts/.md` page, link from [index.md](index.md), append a line to [log.md](log.md). - -## Cross-references - -This page intentionally stays short. The substantive material lives in `concepts/` (decisions, gotchas) and the [index](index.md) catalog. +**Не читать. Не править.** Канон — mappa (`mcp__mappa__*`): wiki-сущности проекта, конвенции — AGENTS-сущность. Скил: `mappa-knowledge`. diff --git a/README.md b/README.md index 9399bcf..2f2d68c 100644 --- a/README.md +++ b/README.md @@ -52,10 +52,9 @@ project's folder and it will, in one pass: - initialize `git` (if missing) and write a sane `.gitignore` - create a starter `README.md` -- lay out `.wiki/` per the [Karpathy LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) (delegated to [`setup-wiki`](skills/setup-wiki/)) -- lay out `.tasks/` with the canonical task board (delegated to [`setup-tasks`](skills/setup-tasks/)) +- register the project meta in **mappa** (wiki/task-сущности проекта; file-based `.wiki/`/`.tasks/` closed 2026-08-25) - write `AGENTS.md` (canon) with skill triggers (`use project wiki`, `use task management system`, `check across all projects`, `we're on Windows`) plus a `CLAUDE.md` legacy pointer -- record the skill versions used in `.wiki/concepts/bootstrap-manifest.md` so cross-project layout drift stays debuggable +- record the skill versions used in a mappa wiki entity (`concepts/bootstrap-manifest`) so cross-project layout drift stays debuggable Two modes, picked automatically: **init** for an empty folder, **upgrade** for an existing project (the skill only fills the gaps and never overwrites diff --git a/README.ru.md b/README.ru.md index ca7eea5..2c176bb 100644 --- a/README.ru.md +++ b/README.ru.md @@ -36,10 +36,9 @@ bash scripts/install.sh mappa-knowledge caveman - инициализирует `git` (если ещё нет) и положит вменяемый `.gitignore` - создаст стартовый `README.md` -- развернёт `.wiki/` по [паттерну Karpathy LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) (делегируется в [`setup-wiki`](skills/setup-wiki/)) -- развернёт `.tasks/` с канонической доской задач (делегируется в [`setup-tasks`](skills/setup-tasks/)) +- зарегистрирует мету проекта в **mappa** (wiki/task-сущности; файловые `.wiki/`/`.tasks/` закрыты 2026-08-25) - запишет `AGENTS.md` (канон) со скилл-триггерами + `CLAUDE.md`-указатель (`use project wiki`, `use task management system`, `check across all projects`, `we're on Windows`) -- зафиксирует версии использованных скиллов в `.wiki/concepts/bootstrap-manifest.md`, чтобы дрифт раскладки между проектами оставался отлаживаемым +- зафиксирует версии использованных скиллов в mappa wiki-сущности `concepts/bootstrap-manifest`, чтобы дрифт раскладки оставался отлаживаемым Два режима, выбирается автоматически: **init** для пустой папки и **upgrade** для существующего проекта (скилл только дозаполняет пробелы и ничего не diff --git a/skills/project-bootstrap/SKILL.md b/skills/project-bootstrap/SKILL.md index 2888f19..d76e4d1 100644 --- a/skills/project-bootstrap/SKILL.md +++ b/skills/project-bootstrap/SKILL.md @@ -114,7 +114,7 @@ source ~/.config/projects-mcp/auth.toml 2>/dev/null || true Get-Content ~/.config/projects-mcp/auth.toml | Select-String "base_url|token" ``` -If auth file missing → stop and tell user: run `/setup-projects-meta` first. +If auth file missing → stop and tell the user (нужны Gitea-креды; скил `setup-projects-meta` удалён 2026-08-25). ### Validate project name @@ -398,11 +398,12 @@ recommend, don't menu we're on Windows ``` -The `check across all projects` line activates the `using-projects-meta` skill -so cross-project task aggregation and the shared `projects-wiki` are available -without an explicit verbal trigger. The skill is a no-op until the -`projects-meta-mcp` server is registered — install via `setup-projects-meta` -on a fresh machine if `mcp__projects-meta__*` tools are missing. +The `check across all projects` trigger activates the **mappa** tooling +(`mcp__mappa__*`) — cross-project boards, shared wiki and the project +registry live in mappa. The file-based `projects-meta-mcp` and its skills +(`using-projects-meta`, `setup-projects-meta`, `meta-host-routing`, `setup-wiki`, +`setup-tasks`) were removed 2026-08-25; the shared `projects-wiki` files are +stubs «не читать, не править» — канон mappa shared-scope. The `pull remote before work` line activates the `pulling-before-work` skill, which runs one `git pull --ff-only` at session start (and on explicit re-sync @@ -515,7 +516,7 @@ Mismatch between template and map → silent gaps in the recommendation. | `talk like a caveman` | `caveman` | skill | `~/.claude/skills/caveman/SKILL.md` | `bash scripts/install.sh caveman` | | `use project wiki` | `using-wiki` | skill | `~/.claude/skills/using-wiki/SKILL.md` | `bash scripts/install.sh using-wiki` | | `use task management system` | `using-tasks` | skill | `~/.claude/skills/using-tasks/SKILL.md` | `bash scripts/install.sh using-tasks` | -| `check across all projects` | `using-projects-meta` | skill | `~/.claude/skills/using-projects-meta/SKILL.md` | `bash scripts/install.sh using-projects-meta` | +| `check across all projects` | mappa (`mcp__mappa__*`) | MCP | `mcpServers.mappa` in `~/.claude.json` | — | | `pull remote before work` | `pulling-before-work` | skill | `~/.claude/skills/pulling-before-work/SKILL.md` | `bash scripts/install.sh pulling-before-work` | | `session handoff: read on start, write on end` | `session-handoff` | skill | `~/.claude/skills/session-handoff/SKILL.md` | `bash scripts/install.sh session-handoff` | | `follow project discipline` | `project-discipline` | skill | `~/.claude/skills/project-discipline/SKILL.md` | `bash scripts/install.sh project-discipline` | @@ -734,10 +735,10 @@ Remote: --- -## Step 8 — projects-meta sync (greenfield-full mode) +## Step 8 — mappa registry (greenfield-full mode) -Only in **greenfield-full** mode. Re-sync the projects-meta cache so the new -project becomes visible to `mcp__projects-meta__*` tools. +Only in **greenfield-full** mode. Register the new project in mappa +(`mcp__mappa__projects_register`) so it becomes visible in the registry. ```bash # POSIX: diff --git a/skills/setup-projects-meta/README.md b/skills/setup-projects-meta/README.md deleted file mode 100644 index 0bb53d8..0000000 --- a/skills/setup-projects-meta/README.md +++ /dev/null @@ -1,93 +0,0 @@ -# setup-projects-meta - -One-time skill that brings up the local `projects-meta-mcp` stdio server on a -new (or freshly broken) machine. Clones the server repo, builds it, writes -`~/.config/projects-mcp/auth.toml` with the user's Gitea token, clones the -shared wiki to `~/projects/.wiki`, and registers `mcpServers.projects-meta` -in `~/.claude.json`. - -The runtime policy for *using* the resulting tools lives in -[`using-projects-meta`](../using-projects-meta/) — `setup-projects-meta` is the -only place that touches user-level config or installs the server. - -`projects-meta-mcp` reference (full): -`mcp__projects-meta__knowledge_get slug=packages/projects-meta-mcp` - -## When it triggers - -- User says: "install projects-meta", "set up projects-meta", "configure projects-meta", - "настрой projects-meta", "установи projects-meta", "projects-meta не работает", - "projects-meta isn't working". -- [`using-projects-meta`](../using-projects-meta/) detects missing - `mcp__projects-meta__*` tools and delegates here via its Prerequisites - section. -- A new machine in the multi-machine fleet — install once per machine. - -## What it installs - -| Path | Role | -|---|---| -| `~/projects/.common/lib/projects-meta-mcp/` | server repo (cloned from Gitea) | -| `~/projects/.common/lib/projects-meta-mcp/dist/server.js` | built stdio entry point | -| `~/.config/projects-mcp/auth.toml` | Gitea credentials (token-bearing) | -| `~/.cache/projects-mcp/tasks.json` | aggregated tasks cache | -| `~/projects/.wiki/` | shared wiki clone (Gitea repo `projects-wiki`, content in root) | -| `~/.claude.json` (`mcpServers.projects-meta`) | MCP registration | - -## Hard rules - -- **Never auto-mutate.** Phase 1 (discovery) and Phase 2 (plan) always pause - for explicit confirmation. A trigger phrase grants permission to inspect, - not to clone or write secrets. -- **Never echo the Gitea token in chat.** Edit / Write tool calls inevitably - contain it (that's how it lands in `auth.toml`); chat output must not. -- **Never clone over an unrelated `~/projects/.wiki/`.** - If it exists with a non-matching `origin`, stop and ask — the user - may have an unrelated wiki there. -- **Always `chmod 600` `auth.toml` on Linux / macOS.** Token leak otherwise. - -## Procedure (high-level) - -1. **Phase 0** — environment sanity (Node ≥ 18, git, npm, network to Gitea). -2. **Phase 1** — discovery (token / repo / wiki clone / MCP registration / cache). -3. **Phase 2** — plan + confirm. Wait for explicit "ok"/"go"/"поехали". -4. **Phase 3** — backup (`~/.claude.json`, existing `auth.toml`). -5. **Phase 4** — clone / pull repo + `npm install && npm run build`; clone - shared wiki if absent. -6. **Phase 5** — write `~/.config/projects-mcp/auth.toml` with `gitea_token`. -7. **Phase 6** — register `mcpServers.projects-meta` in `~/.claude.json` with - absolute path to `dist/server.js`. -8. **Phase 7** — smoke test (`mcp__projects-meta__meta_status`) + `node dist/sync.js` - to populate the cache. -9. **Phase 8** — restart guidance + final report. - -Full procedure with shell snippets and templates lives in [`SKILL.md`](SKILL.md). - -## Rollback - -1. Stop. Don't fix forward. -2. `cp .bak- ` for `~/.claude.json` and `~/.config/projects-mcp/auth.toml`. -3. Optional: `rm -rf ~/projects/.common/lib/projects-meta-mcp` and `rm -rf ~/.cache/projects-mcp`. - Keep `~/projects/.wiki/` — it's a useful clone regardless of MCP state. -4. Restart Claude Code. -5. Confirm `mcp__projects-meta__*` tools are gone (or back to the prior version). - -## Install - -From the repo root: - -```bash -bash scripts/install.sh setup-projects-meta -``` - -Works on Windows under git-bash, Linux, macOS. - -## See also - -- [`using-projects-meta`](../using-projects-meta/) — runtime policy for - cross-project task aggregation and shared-wiki query / ingest. -- [`setup-context7`](../setup-context7/) — companion pattern for the context7 - MCP plugin (similar 8-phase shape). -- Per-project вики/таски живут в mappa (мета в сервисе, решения 14/15) — - setup-скилов `.wiki/`/`.tasks/` больше нет; операции — `using-wiki` / - `using-tasks`. diff --git a/skills/setup-projects-meta/SKILL.md b/skills/setup-projects-meta/SKILL.md deleted file mode 100644 index 95df0cf..0000000 --- a/skills/setup-projects-meta/SKILL.md +++ /dev/null @@ -1,244 +0,0 @@ ---- -name: setup-projects-meta -author: ours -version: 1.1.0 -description: Installs and configures the local `projects-meta-mcp` stdio server — clones the repo to `~/projects/.common/lib/projects-meta-mcp`, builds it, writes `~/.config/projects-mcp/auth.toml` with the user's Gitea token, clones the shared wiki to `~/projects/.wiki/` (content lives in root), and registers `mcpServers.projects-meta` in `~/.claude.json`. Use this skill when the user says "install projects-meta", "set up projects-meta", "configure projects-meta", "настрой projects-meta", "установи projects-meta", "projects-meta не работает", "projects-meta isn't working", or whenever the `mcp__projects-meta__*` tools are missing in a session that needs cross-project task aggregation or the shared Gitea wiki. Cross-platform — Windows / Linux / macOS. Mutates user-level config and writes secrets; pauses for confirmation before every write. ---- - -# setup-projects-meta - -> One-time skill that gets the local `projects-meta-mcp` server running with the user's Gitea credentials. Stops at confirmation gates because the procedure clones a repo, writes a secret-bearing TOML file, and edits `~/.claude.json`. - -Reference: full `projects-meta-mcp` docs live in the shared wiki at `packages/projects-meta-mcp` (fetch via `mcp__projects-meta__knowledge_get` once the server is up). - -## When to use - -- User explicitly asks: install / set up / configure projects-meta. -- A `using-projects-meta`-driven task fails because `mcp__projects-meta__*` tools aren't available. -- Migrating a stale install (token expired, repo moved, broken cache) — same procedure, Phase 1 detects what's already in place. -- New machine in the user's multi-machine fleet (recall: this is a cross-machine workflow). - -## Out of scope - -- Issuing or rotating Gitea tokens. This skill *uses* a token the user already has; if there's no token, point them at Gitea's settings page (`https://git.kzntsv.site/user/settings/applications`) and stop until they paste one. -- Running `projects-meta-mcp` itself (the MCP harness spawns it). -- Editing `.tasks/STATUS.md` or wiki content — that's `using-projects-meta` / `using-tasks` / `using-wiki`. -- Any other MCP server. - -## Hard rule: don't auto-mutate config - -The procedure clones a repo, writes `~/.config/projects-mcp/auth.toml` (carries the Gitea token), and edits `~/.claude.json`. **Always pause for explicit confirmation between Phase 1 (discovery, read-only) and Phase 2 (plan), and again before Phase 3 (backup + writes).** A trigger phrase is permission to run discovery, not permission to clone or write secrets. - -## Procedure - -### Phase 0 — Environment sanity - -- Confirm Claude Code is the current harness (need `mcpServers` registration in `~/.claude.json`). -- Confirm `git`, `node`, `npm` are on `PATH`. Node ≥ 18 (the server uses ES modules). -- Confirm network reachability to `https://git.kzntsv.site` (the Gitea host). On HTTP 401/403 later, the token is dead — stop and ask for a new one. -- Pick paths: `~/projects/.common/lib/projects-meta-mcp`, `~/.config/projects-mcp/`, `~/.cache/projects-mcp/`, `~/projects/.wiki/` (shared wiki clone). POSIX-style `~/...` resolves correctly under git-bash on Windows. - -### Phase 1 — Discovery (read-only) - -Search, in order. Report only "found at ", never echo token values. - -**Existing Gitea token.** Look in priority order: - -1. `~/.config/projects-mcp/auth.toml` → `gitea_token = "..."` -2. Env var `PROJECTS_META_GITEA_TOKEN` -3. Existing `~/.claude.json` → `mcpServers.projects-meta` block (rare; legacy installs sometimes inline `env.GITEA_TOKEN`) - -The first hit wins. Capture internally for Phase 5; **never echo it in chat**. - -**Repo install state.** Check whether `~/projects/.common/lib/projects-meta-mcp/.git` exists. If yes, `git -C ~/projects/.common/lib/projects-meta-mcp rev-parse HEAD` → record the SHA so Phase 4 can decide *clone* vs *pull*. - -**Build artifact.** Check `~/projects/.common/lib/projects-meta-mcp/dist/server.js`. If absent, Phase 4 will run `npm install && npm run build`. - -**Shared wiki clone.** Check if `~/projects/.wiki/.git` exists and `origin` matches `https://git.kzntsv.site/OpeItcLoc03/projects-wiki(.git)?`. If non-matching `origin`, stop and ask — the user may have an unrelated wiki there. - -**MCP registration.** Read `~/.claude.json` and check `mcpServers.projects-meta`. Note the command + args. If args point at a stale path, Phase 6 will fix it. - -**Cache state.** List `~/.cache/projects-mcp/` (if it exists). Just for the report — don't rely on it. - -### Phase 2 — Plan + confirm - -Present a single-block plan to the user: - -``` -Token: | NOT FOUND — will ask> -Repo: | will clone> -Build artifact: -Wiki clone: -MCP entry: -Backups: ~/.claude.json.bak-, ~/.config/projects-mcp/auth.toml.bak- (if exists) -``` - -Wait for explicit confirmation ("ok", "go", "поехали"). Anything else → stop. - -If no token was found in Phase 1 — first ask: "Paste a Gitea personal access token (scope: `read:repository` for read-only, `write:repository` to enable mutations), or open `https://git.kzntsv.site/user/settings/applications` to create one." Don't proceed past Phase 2 without a token. - -### Phase 3 — Backup - -Copy each file we will modify to `.bak-YYYYMMDD-HHMMSS`: - -```bash -TS=$(date +%Y%m%d-%H%M%S) -[ -f ~/.claude.json ] && cp ~/.claude.json ~/.claude.json.bak-$TS -[ -f ~/.config/projects-mcp/auth.toml ] && cp ~/.config/projects-mcp/auth.toml ~/.config/projects-mcp/auth.toml.bak-$TS -``` - -Confirm both backups exist (when their source existed) before any further edit. The repo and wiki clones don't need backup — git is the backup. - -### Phase 4 — Clone + build - -```bash -# Server -if [ -d ~/projects/.common/lib/projects-meta-mcp/.git ]; then - git -C ~/projects/.common/lib/projects-meta-mcp pull --ff-only -else - git clone https://git.kzntsv.site/OpeItcLoc03/projects-meta-mcp ~/projects/.common/lib/projects-meta-mcp -fi -cd ~/projects/.common/lib/projects-meta-mcp -npm install -npm run build - -# Shared wiki -mkdir -p ~/projects -if [ -d ~/projects/.wiki/.git ]; then - git -C ~/projects/.wiki pull --ff-only -else - git clone https://git.kzntsv.site/OpeItcLoc03/projects-wiki ~/projects/.wiki -fi -``` - -Verify `~/projects/.common/lib/projects-meta-mcp/dist/server.js` exists after build. If not — abort, the build failed; ask the user to run `npm run build` manually and paste the output. - -### Phase 5 — Write `auth.toml` - -```bash -mkdir -p ~/.config/projects-mcp -``` - -If `~/.config/projects-mcp/auth.toml` already exists and Phase 1 found a valid `gitea_token` line — skip the write. Otherwise, write the file with the token captured in Phase 1 (or freshly pasted in Phase 2): - -```toml -gitea_url = "https://git.kzntsv.site" -gitea_user = "OpeItcLoc03" # acting identity (commit author) -gitea_token = "" -gitea_owners = ["victor", "cancel_music"] # additional Gitea owners to sync -agenda_tasks_repo = "OpeItcLoc03/agenda" # cross-project meta-board (qualified) -# gitea_aggregate_skip_owners = ["OpeItcLoc03"] # opt: sync but hide from `tasks_aggregate` -``` - -**Schema notes (v2.x server):** - -- `gitea_owners` is an array of owners whose repos are scanned by `sync.js` and surfaced in aggregation views. `gitea_user` is acting identity only (commit author footer), not necessarily aggregated. -- `agenda_tasks_repo` is **qualified** (`/`). The literal `agenda` in `target_project` resolves through this field. -- `gitea_aggregate_skip_owners` (optional, v2.2.0+) — visited by sync (so mutations work via cache lookup) but hidden from `tasks_aggregate` / `tasks_search`. Useful for keeping infra repos write-able without polluting the dashboard. -- Backwards-compat: legacy installs with only `gitea_user = "X"` and no `gitea_owners` → server reads as `gitea_owners = ["X"]`. -- Legacy `meta_tasks_repo` / `meta_wiki_repo` → renamed to `agenda_tasks_repo` / built-in `projects-wiki`. Old keys ignored on v2.x. - -Permissions: on Linux / macOS run `chmod 600 ~/.config/projects-mcp/auth.toml`. On Windows the default ACL is per-user, no extra step. - -### Phase 6 — Register in `~/.claude.json` - -Edit `~/.claude.json`. Add or update the `mcpServers.projects-meta` block: - -```json -{ - "mcpServers": { - "projects-meta": { - "command": "node", - "args": ["/dist/server.js"] - } - } -} -``` - -Absolute path resolution: - -| Platform | `` | -|---|---| -| Windows | `C:/Users//projects/.common/lib/projects-meta-mcp` (forward slashes; works in JSON without escaping) | -| Linux | `/home//projects/.common/lib/projects-meta-mcp` | -| macOS | `/Users//projects/.common/lib/projects-meta-mcp` | - -After each edit, validate JSON: - -```bash -# Windows (git-bash) -powershell.exe -NoProfile -c "Get-Content '' -Raw | ConvertFrom-Json | Out-Null" -# Linux / macOS -jq empty -# fallback -python -c "import json; json.load(open(''))" -``` - -If validation fails → restore from `.bak-*` and abort. - -### Phase 7 — Smoke test (best-effort) + run initial sync - -Best-effort: call `mcp__projects-meta__meta_status`. If it returns a JSON blob with `synced_at` / `wiki_pages_count` — the server is reachable in *this* session. - -Then run a one-shot sync to populate the cache: - -```bash -cd ~/projects/.common/lib/projects-meta-mcp -node dist/sync.js -``` - -Expect a non-zero `projects_count` and a fresh `~/.cache/projects-mcp/tasks.json`. On 401 / 403 → token is wrong scope or expired; rotate via `https://git.kzntsv.site/user/settings/applications` and re-edit `auth.toml`. - -**Important caveat to relay to the user:** in the *same* session that just ran setup, the MCP server you're talking to is whatever was bound at session start. So a passing `meta_status` only proves "some projects-meta is alive" — not "the registration we just wrote is what's serving it". The real test is after Claude Code restart. - -### Phase 8 — Restart guidance + final report - -Tell the user: - -``` -✅ Setup complete. Restart Claude Code so the new mcpServers.projects-meta - registration binds to a fresh stdio session. - -After restart: - • mcp__projects-meta__* tools serve from ~/projects/.common/lib/projects-meta-mcp/dist/server.js - • Cache lives at ~/.cache/projects-mcp/tasks.json (refresh: node dist/sync.js) - • Shared wiki clone at ~/projects/.wiki/ — `git -C ~/projects/.wiki pull --ff-only` for fresh anchors - • Backups saved at ~/.claude.json.bak- (and auth.toml.bak- if it existed before) - -If something breaks after restart: - • Restore from .bak-* and tell me — we'll roll back together. -``` - -## Rollback procedure - -If a problem surfaces (now or after restart): - -1. Stop. Don't try to fix forward. -2. Find the most recent `.bak-YYYYMMDD-HHMMSS` next to `~/.claude.json` (and `~/.config/projects-mcp/auth.toml` if applicable). -3. `cp .bak- ` for each. -4. Optional: `rm -rf ~/projects/.common/lib/projects-meta-mcp` and `rm -rf ~/.cache/projects-mcp`. Keep `~/projects/.wiki/` — it's a useful clone regardless of MCP state. -5. Restart Claude Code. -6. Confirm `mcp__projects-meta__*` is gone (or back to the pre-existing version). -7. Report what went wrong so we can fix the procedure. - -## Cross-platform notes - -The procedure is platform-agnostic. Only auxiliary tooling differs: - -| | JSON validate | Backup | Permissions on auth.toml | -|---|---|---|---| -| Windows (git-bash) | `powershell.exe -NoProfile -c "Get-Content '' -Raw \| ConvertFrom-Json \| Out-Null"` | `cp` | per-user ACL by default | -| Linux | `jq empty ` (or `python -c "import json; json.load(open(''))"`) | `cp` | `chmod 600` | -| macOS | same as Linux | `cp` | `chmod 600` | - -Path forms (`~/.local/...`, `~/.config/...`, `~/projects/...`) are identical on all three. - -## Common mistakes - -- **Skipping Phase 1.** "User just said 'install projects-meta' — let's go." No — find existing token / repo / wiki first; re-cloning over an existing install loses any local commits in the wiki. -- **Echoing the token.** It's a secret. Edit / Write tool calls inevitably contain it (that's how it gets into `auth.toml`), but no chat output should. -- **Cloning over an unrelated `~/projects/.wiki/`.** If it exists with a different `origin`, stop. The user may have an unrelated wiki there. -- **Writing `auth.toml` with `0644` perms on Linux/macOS.** Token leak. Always `chmod 600` after write. -- **Treating in-session `meta_status` as proof.** Same as the context7 caveat — the active MCP connection was bound at session start. -- **Auto-running on every "use projects-meta".** This skill is intrusive. Trigger only on explicit "install/setup/configure projects-meta", or when MCP tools are missing and the user is blocked. -- **Forgetting `node dist/sync.js`.** Without an initial sync, the cache is empty and `tasks_aggregate` returns nothing — the user thinks setup failed. diff --git a/skills/update-skills/SKILL.md b/skills/update-skills/SKILL.md index b1adeb0..125a7eb 100644 --- a/skills/update-skills/SKILL.md +++ b/skills/update-skills/SKILL.md @@ -85,11 +85,10 @@ setup; pi loads `~/.agents/skills` by default. Verify with `pi --help` / a fresh The update scripts (`scripts/update.sh` and `scripts/update.ps1`) handle: 1. **git pull --ff-only** in `~/projects/skills/` (stash if dirty, pop after). -2. **Conditionally rebuild projects-meta-mcp** — if `~/projects/.common/lib/projects-meta-mcp/` has a `.git` directory and source changed (`git pull` fetched new commits), run `npm run build`. -3. **Conditionally rebuild interns-mcp** — same pattern, `pip install -e .`. -4. **Install all skills** via `install.sh` / `install.ps1`. -5. **Show version diff** — before/after `version:` frontmatter for each skill. -6. **Print reload hints** — `/reload-mcp` if MCP changed, new session otherwise. +2. **Conditionally rebuild interns-mcp** — same pattern, `pip install -e .`. +3. **Install all skills** via `install.sh` / `install.ps1`. +4. **Show version diff** — before/after `version:` frontmatter for each skill. +5. **Print reload hints** — `/reload-mcp` if MCP changed, new session otherwise. ## Out of scope diff --git a/skills/using-projects-meta/README.md b/skills/using-projects-meta/README.md deleted file mode 100644 index 947dce4..0000000 --- a/skills/using-projects-meta/README.md +++ /dev/null @@ -1,170 +0,0 @@ -# using-projects-meta - -Runtime policy for the local `projects-meta-mcp` stdio server. Two -responsibilities, one server: - -1. **Cross-project task aggregation** — reads / writes `.tasks/STATUS.md` in - any of the user's Gitea repos. -2. **Shared knowledge wiki** — query / ingest a single Gitea-backed wiki at - `~/projects/projects-wiki/.wiki/` (clone root: `~/projects/projects-wiki/`, - Gitea repo: `projects-wiki`). - -`using-projects-meta` governs *usage* of an installed server. Initial setup -(clone, build, `auth.toml`, MCP registration) is owned by -[`setup-projects-meta`](../setup-projects-meta/). - -Full server reference: -`mcp__projects-meta__knowledge_get slug=packages/projects-meta-mcp`. - -## When it triggers - -- User asks for cross-project state ("what's on the boards", "across all - projects", "что у меня на досках", "по всем проектам"). -- User wants to query / ingest the shared wiki ("check shared wiki", "search - projects-wiki", "ingest into shared wiki", "общая вики", "заингесть в общую"). -- User wants to create / update / close a task in *another* project from the - current cwd ("заведи в проекте X задачу", "close task Y in project Z"). -- User asks for sync diagnostics ("when did the cache last refresh", "are there - sync errors"). -- If `mcp__projects-meta__*` tools are missing, this skill delegates to - [`setup-projects-meta`](../setup-projects-meta/) before doing anything else. - -## Local-first rule (critical) - -For the **current** project — read disk directly (`.tasks/STATUS.md`, -`.wiki/index.md`). The MCP cache: - -- May be stale (sync runs only when triggered). -- Hides `🟢 done` by default. -- May not contain unpushed projects. - -Use MCP only for **other** projects, **other** machines, or the **shared** -wiki content. See the table below. - -| Question | Where to read | -|---|---| -| "What's the status of *this* project?" | local `.tasks/STATUS.md` | -| "What's on all my boards?" | `mcp__projects-meta__tasks_aggregate` | -| "Has *this* project's wiki got X?" | local `.wiki/index.md` | -| "Has the **shared** wiki got X?" | `mcp__projects-meta__knowledge_search` | -| "Sync state across machines?" | `mcp__projects-meta__meta_status` | - -## Step 0 — Freshness gate (v1.1.0, mandatory pre-flight) - -`projects-meta` is a bus between machines — another host may have pushed -minutes ago. Without this gate, reads return stale data and writes hit -sha-based optimistic-lock 422s with no explanation. - -Before **any** `tasks_*` or `knowledge_*` call: - -1. `mcp__projects-meta__meta_status` — probe cache age + errors. -2. If `cache_age_minutes` > 10 OR `errors_count` > 0 → - `node ~/projects/.common/lib/projects-meta-mcp/dist/sync.js`. -3. For shared-wiki **writes** (`knowledge_ingest`, `knowledge_promote`) → - **also** `git -C ~/projects/projects-wiki pull --ff-only`. Unconditional. - The MCP server uses sha-based optimistic locking on the wiki repo; - without an up-to-date local SHA the commit is rejected with a 422. -4. For tasks-mutations (`tasks_create`/`update`/`close`) → sync via - `dist/sync.js` is enough; there's no local clone of the target tasks repo. -5. If sync returns **401 / 403** → STOP. Token is dead. Send the user to - `~/.config/projects-mcp/auth.toml` to rotate `gitea_token`. Don't - pretend success, don't retry silently. - -**Don't sync unconditionally** on every call — overhead + 401-risk for -casual reads. The 10-minute window is the chosen threshold. - -**Don't apply Step 0 to `meta_status` itself** — it's the probe. - -## Two operation classes - -### Read (no confirmation) - -`tasks_aggregate`, `tasks_search`, `tasks_get`, `knowledge_search`, -`knowledge_get`, `knowledge_suggest_promote`, `meta_status` — all -side-effect-free. Call directly, cite the result. - -### Mutate (always two-step) - -`tasks_create`, `tasks_update`, `tasks_close`, `knowledge_ingest`, -`knowledge_promote` — write to Gitea. Procedure: - -1. Call **without** `confirm: true` → returns dry-run preview (proposed file - diff + commit message). -2. Show the preview to the user. Wait for explicit "ok" / "go" / "поехали". -3. Re-call with `confirm: true` → committed. - -**Never inline `confirm: true` on the first call.** A trigger phrase is -permission to plan, not to commit. - -## Tool quick reference - -### Read - -| Tool | Required args | Purpose | -|---|---|---| -| `mcp__projects-meta__tasks_aggregate` | — | All active tasks across cached projects | -| `mcp__projects-meta__tasks_search` | `query` | Substring search across slug + next_action | -| `mcp__projects-meta__tasks_get` | `project` | Raw STATUS.md of one project (cache snapshot) | -| `mcp__projects-meta__knowledge_search` | `query`; opt `domain`, `limit` | Shared-wiki search; default domain auto-detected from cwd | -| `mcp__projects-meta__knowledge_get` | `slug` | Full text of one wiki page | -| `mcp__projects-meta__knowledge_suggest_promote` | — | Local `.wiki/concepts/` candidates for shared promotion | -| `mcp__projects-meta__meta_status` | — | Sync diagnostics (cache age, project / page / error counts) | - -### Mutate (need `write:repository` Gitea scope) - -| Tool | Required args | Effect | -|---|---|---| -| `mcp__projects-meta__tasks_create` | `target_project`, `slug`, `description`, `next_action` | Append block to target's `.tasks/STATUS.md` via Gitea commit | -| `mcp__projects-meta__tasks_update` | `target_project`, `slug` + ≥1 mutable field | Sha-based optimistic lock; 422 on conflict | -| `mcp__projects-meta__tasks_close` | `target_project`, `slug` (+ opt `note`) | Marks task 🟢 done with identity-footer | -| `mcp__projects-meta__knowledge_ingest` | `target_project`, `type`, `slug`, `body` | Three commits: `/.md` + `index.md` + `log.md` | -| `mcp__projects-meta__knowledge_promote` | `target_project`, `slug`, `body` | Move `raw/.md` → `summaries/.md` | - -`type` ∈ `entities` / `concepts` / `packages` / `summaries` / `raw`. -`target_project` = Gitea repo name, or `_meta` (meta-tasks / meta-wiki repos -from `auth.toml`). - -## Common mistakes - -- **Reading current project's tasks via `tasks_get`.** Read `.tasks/STATUS.md` - on disk; the MCP cache is for *other* projects. -- **Inlining `confirm: true` on first call.** Always preview first; show user; - only then `confirm: true`. -- **Confusing the local `.wiki/` with the shared `projects-wiki`.** They are - two different stores. `using-wiki` operates on the local one; - `using-projects-meta` queries / ingests the shared one. -- **Acting on stale `tasks_aggregate`.** If `meta_status.age_seconds` > 3600, - either run `node dist/sync.js` (in `~/projects/.common/lib/projects-meta-mcp`) or warn the - user about staleness. -- **Vague `knowledge_search` queries.** "auth" returns noise. Multi-word, - specific queries return targeted snippets. -- **Wrong `type` on `knowledge_ingest`.** Mis-typed pages land in the wrong - section and break `index.md`. Pick from the five canonical types. - -## When NOT to use - -- The current project's own tasks — read `.tasks/STATUS.md`. -- The current project's own wiki — read `.wiki/`. -- Library / framework documentation — that's [`using-context7`](../using-context7/). -- Repo-internal code search — that's `Glob` / `Grep`. -- One-off git history questions — `git log`. - -## Install - -From the repo root: - -```bash -bash scripts/install.sh using-projects-meta -``` - -Works on Windows under git-bash, Linux, macOS. - -## See also - -- [`setup-projects-meta`](../setup-projects-meta/) — companion, owns server - install + MCP registration. -- [`using-context7`](../using-context7/) — sister skill for library docs (same - using-X structure). -- [`using-tasks`](../using-tasks/), [`using-wiki`](../using-wiki/) — - per-project policies for in-repo `.tasks/` and `.wiki/`. Orthogonal to this - skill; together they cover both per-project and cross-project state. diff --git a/skills/using-projects-meta/SKILL.md b/skills/using-projects-meta/SKILL.md deleted file mode 100644 index e6fa20d..0000000 --- a/skills/using-projects-meta/SKILL.md +++ /dev/null @@ -1,238 +0,0 @@ ---- -name: using-projects-meta -author: ours -version: 1.3.0 -description: Use when working across multiple projects on one or many machines — cross-project task aggregation (`mcp__projects-meta__tasks_*`), shared Gitea-backed wiki query / ingest (`mcp__projects-meta__knowledge_*`), or sync diagnostics (`mcp__projects-meta__meta_status`). Triggers on phrases like "across all projects", "what's on the boards", "check shared wiki", "search projects-wiki", "ingest into shared wiki", "что у меня на досках", "по всем проектам", "общая вики", "cross-project status", or any time the user wants to see / mutate state in another repo than the current cwd. v1.1.0 mandates a Step 0 freshness gate (probe `meta_status`, sync if stale, pull `projects-wiki` before shared-wiki writes) — see SKILL body. Mutation tools require two-step preview → confirm. Skip for the **current** project's tasks/wiki — those live on disk in `.tasks/` / `.wiki/`. ---- - -# Using the projects-meta MCP server - -## Overview - -`projects-meta-mcp` is a local stdio MCP server. Two responsibilities: - -1. **Cross-project task aggregation** — parses `.tasks/STATUS.md` from every repo on the user's Gitea, caches them in `~/.cache/projects-mcp/tasks.json`. Read tools (`tasks_aggregate`, `tasks_search`, `tasks_get`) hit the cache. Mutations (`tasks_create`, `tasks_update`, `tasks_close`) commit back to Gitea with sha-based optimistic lock. -2. **Shared knowledge wiki** — single Gitea repo (`projects-wiki`) cloned at `~/projects/projects-wiki/` with content at `~/projects/projects-wiki/.wiki/`, structured as packages / concepts / entities / summaries / raw. `knowledge_search` + `knowledge_get` for queries, `knowledge_ingest` + `knowledge_promote` for writes. - -Source of truth: Gitea (`https://git.kzntsv.site`, owner `OpeItcLoc03`). Cache and clone are local convenience. - -Full reference: `mcp__projects-meta__knowledge_get slug=packages/projects-meta-mcp`. - -## Prerequisites - -This skill assumes `mcp__projects-meta__*` tools are available. If they aren't (tools missing from the session, or calls fail with a connection error), the server isn't running for this session. Trigger the **`setup-projects-meta`** skill to clone, build, write `auth.toml`, and register `mcpServers.projects-meta` in `~/.claude.json`. It's a one-time procedure with confirmation gates. - -## Local-first rule - -**For the current project — read disk directly.** `.tasks/STATUS.md` and `.wiki/` files in cwd are always fresher than the MCP cache. The cache: - -- May be stale (default sync runs only when triggered). -- Hides 🟢 done by default. -- May not contain locally-developed projects that aren't pushed to Gitea yet. - -Use MCP only for **other** projects, **other** machines, or **shared** wiki content. - -| Question | Where to read | -|---|---| -| "What's the status of *this* project?" | local `.tasks/STATUS.md` | -| "What's on all my boards?" | `mcp__projects-meta__tasks_aggregate` | -| "Has *this* project's wiki got a page on X?" | local `.wiki/index.md` + relevant file | -| "Has the **shared** wiki got a page on X?" | `mcp__projects-meta__knowledge_search` | -| "Sync state across machines?" | `mcp__projects-meta__meta_status` | - -## When to use - -- Cross-project task overview ("what am I working on across projects", "по всем проектам", "across the board"). -- Hopping into another repo's task state without cloning it ("what's the status of project X"). -- Querying the shared wiki for cross-cutting concepts (patterns, package references, design notes that apply to several repos). -- Ingesting a finished design / decision into the shared wiki so other machines / projects can see it. -- Creating a task in another project's `.tasks/STATUS.md` from the current repo (cross-project handoff). -- Sync diagnostics (when did the cache last refresh, are there errors, how many projects). - -## When NOT to use - -- The current project's own tasks or wiki — read disk. -- Anything inside a single project — `.tasks/.md` and `.wiki/.md` are always closer. -- One-off questions answered by `git log` or a single file. -- Library / framework documentation — that's `using-context7`. -- Code search — that's `Glob` / `Grep`. - -## Step 0 — Freshness gate (run before any tool) - -`projects-meta` is a bus between machines. Another host may have pushed minutes ago. Without this gate, reads return stale data and writes hit sha-based optimistic-lock 422s with no explanation. Mandatory pre-flight, every session, every workflow: - -``` -1. Call mcp__projects-meta__meta_status. - -2. Branch on cache freshness: - • If cache_age_minutes > 10 OR errors_count > 0: - run `node ~/projects/.common/lib/projects-meta-mcp/dist/sync.js` - (or `npm run sync` from ~/projects/.common/lib/projects-meta-mcp). - • Else: cache is fresh enough — skip sync, no need to hit the network. - -3. For shared-wiki WRITES (knowledge_ingest, knowledge_promote): - ALWAYS additionally run `git -C ~/projects/projects-wiki pull --ff-only` - regardless of cache age. The MCP server uses sha-based optimistic locking; - without an up-to-date local file SHA, the commit will be rejected (422) - and the failure mode is opaque to the user. - -4. For tasks-mutations (tasks_create, tasks_update, tasks_close): - sync via dist/sync.js is enough — there's no local clone of the target - tasks repo, mutations go straight through Gitea API. Sync only refreshes - the local view so you reason from current state. - -5. If sync returns 401 or 403: - STOP. The Gitea token in ~/.config/projects-mcp/auth.toml is dead or - wrong-scoped. Tell the user explicitly: - "Gitea sync failed with <401|403>. Rotate gitea_token in - ~/.config/projects-mcp/auth.toml (Gitea: settings/applications) - and rerun." - Do not pretend sync succeeded. Do not retry silently. -``` - -**Don't sync unconditionally on every call.** Network overhead + risk of 401 even on a casual "what's on my boards". The 10-minute cache window is the right balance — catches multi-machine drift without burning Gitea round-trips for back-to-back questions. - -**Don't apply Step 0 to `meta_status` itself** — it's the freshness probe, not a downstream read. - -## Workflow - -### Read (no confirmation needed) - -``` -0. Run Step 0 — Freshness gate (above) first. -1. Identify what you need: cross-project tasks? shared wiki page? sync state? -2. Pick the right read tool (table below). -3. Cite the result with the source slug / project name. -``` - -### Mutate (always two-step) - -``` -0. Run Step 0 — Freshness gate (above) first. - For shared-wiki writes (knowledge_ingest, knowledge_promote): unconditional - `git -C ~/projects/projects-wiki pull --ff-only` is part of Step 0. -1. Identify the mutation: tasks_create / tasks_update / tasks_close / knowledge_ingest / knowledge_promote. -2. Call the tool WITHOUT `confirm: true` → returns a dry-run preview (the proposed file diff and the Gitea commit message). -3. Show the preview to the user. Wait for explicit "ok" / "go" / "поехали". -4. Re-call with `confirm: true` to commit. -``` - -**Never inline `confirm: true` on the first call.** A trigger phrase ("create a task in project X") is permission to *plan*, not to *commit*. - -## Tool quick reference - -### Read tools - -| Tool | Required args | Purpose | -|---|---|---| -| `mcp__projects-meta__tasks_aggregate` | — | All active tasks across all cached projects | -| `mcp__projects-meta__tasks_search` | `query` | Substring search across slug + next_action | -| `mcp__projects-meta__tasks_get` | `project` | Raw STATUS.md of one project (cached snapshot) | -| `mcp__projects-meta__knowledge_search` | `query`; opt `domain`, `limit` | Shared-wiki search; auto-detects domain from cwd, pass `domain="all"` to disable | -| `mcp__projects-meta__knowledge_get` | `slug` | Full text of one wiki page (e.g. `packages/projects-meta-mcp`) | -| `mcp__projects-meta__knowledge_suggest_promote` | — | Local `.wiki/concepts/` candidates for shared-wiki promotion | -| `mcp__projects-meta__meta_status` | — | Sync diagnostics: cache age, project count, error count, page count | - -### Mutation tools (need `write:repository` Gitea scope; preview → confirm) - -| Tool | Required args | Effect | -|---|---|---| -| `mcp__projects-meta__tasks_create` | `target_project`, `slug`, `description`, `next_action` (+ opt `where_stopped`, `status`, `blocker`, `branch`, `source_project`) | Append block to `/.tasks/STATUS.md` via Gitea commit | -| `mcp__projects-meta__tasks_update` | `target_project`, `slug` + ≥1 of `where_stopped` / `next_action` / `blocker` / `branch` / `description` / `status` | Sha-based optimistic lock; 422 on conflict | -| `mcp__projects-meta__tasks_close` | `target_project`, `slug` (+ opt `note`) | Sets task to 🟢 done; appends identity-footer | -| `mcp__projects-meta__knowledge_ingest` | `target_project`, `type`, `slug`, `body` (+ opt `frontmatter`, `source_project`) | Three commits: `/.md` + `index.md` + `log.md`. `type` ∈ entities / concepts / packages / summaries / raw | -| `mcp__projects-meta__knowledge_promote` | `target_project`, `slug`, `body` (+ opt `frontmatter`, `source_project`) | Move `raw/.md` → `summaries/.md` with auto `raw_path` link | - -`target_project` is **qualified** `/` (e.g. `victor/books`, `OpeItcLoc03/skills`), or the literal `agenda` for the cross-project meta-board (resolves via `agenda_tasks_repo` in `auth.toml`). Bare names (`books`) are rejected with a hint to use the qualified form. Cross-cutting design: shared wiki → `concepts/projects-meta-multi-owner`. - -## Examples - -### Read example: cross-project status - -User: "что у меня на досках?" - -``` -1. mcp__projects-meta__tasks_aggregate - → 7 projects, 12 active tasks - -2. Group by project, summarize 1 line per active task. - Cite project name; if a task is stale (cache age > 1h), flag it. -``` - -### Read example: shared wiki query - -User: "есть ли в общей вики что-то про setup-using паттерн?" - -``` -1. mcp__projects-meta__knowledge_search - query: "setup-using skill pair pattern" - domain: "all" - → hits include concepts/setup-using-skill-pair - -2. mcp__projects-meta__knowledge_get - slug: "concepts/setup-using-skill-pair" - → full text - -3. Summarize, link with markdown to the slug. -``` - -### Mutation example: create cross-project task - -User: "заведи в проекте books задачу на миграцию `settings.json`" - -``` -1. mcp__projects-meta__tasks_create - target_project: "victor/books" - slug: "settings-json-migration" - description: "<...>" - next_action: "<...>" - (no `confirm`) - → preview: proposed STATUS.md diff + commit message - -2. Show preview to user. - -3. User: "ok, go" - -4. mcp__projects-meta__tasks_create - (same args + confirm: true) - → committed to Gitea -``` - -### Mutation example: closing a cross-project task - -User: "close `[projects-meta-skills]` in skills" - -``` -1. mcp__projects-meta__tasks_close - target_project: "OpeItcLoc03/skills" - slug: "projects-meta-skills" - note: "" - (no `confirm`) - → preview - -2. User confirms. - -3. Re-call with confirm: true. -``` - -## Common mistakes - -| Mistake | Fix | -|---|---| -| Reading current project's tasks via `tasks_get` instead of disk | Read `.tasks/STATUS.md` directly. MCP is for *other* projects. | -| Inlining `confirm: true` on the first mutation call | Always preview first; show user; only then `confirm: true`. | -| Using `knowledge_search` for the project's own wiki | The shared wiki is a separate Gitea repo. Local `.wiki/` is in cwd. | -| Acting on a stale `tasks_aggregate` without checking `meta_status` | Step 0 — Freshness gate is mandatory. If `cache_age_minutes` > 10 (or errors > 0), run `node ~/projects/.common/lib/projects-meta-mcp/dist/sync.js` first. | -| Skipping `git -C ~/projects/projects-wiki pull` before `knowledge_ingest` / `knowledge_promote` | sha-based optimistic lock will reject the commit (422) and the failure is opaque. Pull is unconditional for shared-wiki writes — fast-forward is a no-op when current. | -| Treating sync 401/403 as "MCP is fine, the page just doesn't exist yet" | 401/403 means the Gitea token is dead. Stop, tell the user to rotate `gitea_token` in `~/.config/projects-mcp/auth.toml`. Never guess on stale data. | -| Calling `knowledge_ingest` with the wrong `type` | `type` must be one of `entities` / `concepts` / `packages` / `summaries` / `raw`. Mis-typed pages land in the wrong section and break `index.md`. | -| Vague `knowledge_search` queries ("auth", "config") | Specific multi-word queries return targeted snippets; vague ones return noise. | -| Forgetting `domain="all"` when searching across families | Default `domain` is auto-detected from cwd; use `"all"` if the wiki page lives in a different family. | -| Passing bare project name (`target_project: "books"`) to mutation tools | v2.x rejects bare names. Use qualified `/` (e.g. `victor/books`, `OpeItcLoc03/skills`). Literal `agenda` is the only exception (cross-project meta-board). | - -## Red flags - -- "I'll just commit it directly" → no. Mutation tools have a preview step for a reason — silent writes to another repo are a recipe for drift. -- "The cache is fresh enough" → run Step 0. The 10-minute window is the threshold; below it skip sync, above it sync. Don't eyeball this — the bus moves fast in cross-machine sessions. -- "I'll skip the pull, my last write was 30 seconds ago" → another machine pushed in between. Always pull before shared-wiki writes; the sha-lock check is your only safety net. -- "I'll skip the wiki page" → if you're answering a cross-cutting question and there's no wiki page, that's a `knowledge_ingest` candidate. Surface it to the user.