s-skillkit 0.3.7__tar.gz → 0.4.0__tar.gz

{s_skillkit-0.3.7 → s_skillkit-0.4.0}/CHANGELOG.md

@@ -6,6 +6,31 @@
 
 ## [Unreleased]
 
+### Added — канон навыка переехал в кит: `skillkit.canon` (#162)
+
+- **Один источник правды вместо трёх.** Форма навыка (раскладка `src/<пакет>/` +
+  `skills/<slug>/` + `install/` + `tests/`, frontmatter `SKILL.md`, порядок ключей
+  `_skill_meta.toml`, `pyproject` с синхронной версией и командой) жила в трёх
+  копиях: `clikit.scaffold`, `skillery_cli.templates` и
+  `reverse_factory.factory.canon`. Копии разошлись: скаффолд `clikit` собирал
+  плоскую раскладку с `kind = "cli"` — родом, которого нет вовсе, — и такой навык
+  не проходил валидатор. Канон перенесён в кит целиком, вместе с тестами.
+- **Почему в `skillkit`.** Всё, что рендерит канон, читает и ставит этот же кит:
+  `manifest` разбирает `_skill_meta.toml`, `targets` раскладывает папку навыка по
+  агентам, `bootstrap` поднимает зависимости и self-check, а сгенерированный
+  `install/install.py` — тонкая обёртка над китом. Обоснование и отклонённые
+  варианты — `docs/adr/0001-kanon-navyka-zhivet-v-skillkit.md`.
+- **Что появилось:** `SkillLayout` / `layout`, `SkillMeta`, `render_skill_md`,
+  `render_skill_meta`, `render_pyproject`, `render_install_docs`,
+  `render_skillgateignore`, `validate_canonical_skill`, `ALLOWED_KINDS`,
+  `module_name` / `command_name`, `read_declared_name` / `stamp_declared_name`.
+- **Форма против смысла.** Канон держит форму; тело `SKILL.md` и описание
+  приносит производитель через `body=` / `description=`. Тело по умолчанию —
+  нейтральный каркас AK-канона (роутер + пять секций с TODO), без упоминаний
+  конкретной фабрики: кит остаётся брендо-нейтральным.
+- **Зависимостей не прибавилось:** модуль на голом stdlib (`re`, `tomllib`,
+  `dataclasses`, `pathlib`).
+
 ### Fixed — гейт принадлежности у CLI-команд и MCP-серверов (#2272)
 
 - **Навык больше не забирает чужую команду.** `path_store.add_cli` снимал ЛЮБОЙ

{s_skillkit-0.3.7 → s_skillkit-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: s-skillkit
-Version: 0.3.7
+Version: 0.4.0
 Summary: Локальное ядро управления навыками: install из git/локальной папки, junction/symlink-линковка в scope агента, .skillignore-фильтр, build manifest, project-манифест. 0 завязок на сеть/auth — stdlib + tomli-w + pathspec + platformdirs.
 Author: Dmitry
 License: MIT

s_skillkit-0.4.0/docs/adr/0000-template.md

@@ -0,0 +1,20 @@
+# NNNN. Краткий заголовок решения
+
+- **Статус:** proposed | accepted | superseded (→ ADR-NNNN) | deprecated
+- **Дата:** ГГГГ-ММ-ДД
+
+## Контекст
+
+Какую ситуацию/проблему решаем. Что вынуждает принять решение сейчас: ограничения, требования, силы, которые тянут в разные стороны. Достаточно, чтобы понять «почему» без внешнего контекста.
+
+## Решение
+
+Что именно решили — одной-двумя фразами, в настоящем времени: «Делаем X». Конкретно и проверяемо.
+
+## Последствия
+
+Что становится проще и что — сложнее/дороже после принятия. Плюсы, минусы, новые обязательства и ограничения, которые теперь придётся держать.
+
+## Альтернативы
+
+Какие варианты рассматривали и **почему отклонили** (в этом ценность записи). Кратко: вариант → причина отказа / отложено до условия.

s_skillkit-0.4.0/docs/adr/0001-kanon-navyka-zhivet-v-skillkit.md

@@ -0,0 +1,122 @@
+# 0001. Канон навыка живёт в skillkit — рядом с тем, кто его читает
+
+- **Статус:** accepted
+- **Дата:** 2026-09-01
+
+## Контекст
+
+«Навык в каноне Skillery» — это набор файлов строго определённой формы:
+`skills/<slug>/SKILL.md` с frontmatter, `skills/<slug>/_skill_meta.toml`,
+`src/<пакет>/` (src-layout), `tests/`, `install/`, `.skillgateignore`,
+`pyproject.toml` с той же версией и той же консольной командой, что в манифесте.
+
+Эту форму на диск кладут РАЗНЫЕ производители, и каждый завёл свою копию правил:
+
+1. **`clikit.scaffold`** (790 строк) — свои `render_skill_md` / `render_skill_meta` /
+   `render_pyproject` / `render_install_skill` / `render_self_check` /
+   `render_smoke_test`. Раскладка ДРУГАЯ: плоский `<pkg>/` вместо `src/<pkg>/`,
+   `SKILL.md` и `_skill_meta.toml` в КОРНЕ вместо `skills/<slug>/`,
+   `kind = "cli"` — рода, которого нет в списке допустимых
+   (`prompt` / `comprehensive` / `tooling`), — ни `install/`, ни `tests/`.
+2. **`skillery_cli.templates`** (802 строки) — свои `render_skill_meta_toml`,
+   онбординг-триада `scripts/{install_skill,self_check,smoke_test}.py`,
+   `render_pyproject`, CLI-скелет. В докстроке прямо написано «зеркалит
+   `clikit.scaffold.render_cli_module`» — то есть копия по замыслу.
+3. **`reverse_factory.factory.canon`** (1033 строки) — раскладка, рендер,
+   `validate_canonical_skill`; три производителя фабрики уже сведены на него
+   фитнес-функцией `test_factory_canon_single_source.py`.
+
+Цена расхождения не гипотетическая: навык, собранный `clikit.scaffold_cli`, не
+проходит `validate_canonical_skill` — его топологию перед публикацией переводили
+РУКАМИ. Ровно этот ручной шаг канон и должен был убрать.
+
+Выбирать источник пришлось сейчас потому, что канон фабрики только что обкатан
+живьём (генерация → `uv sync` → `uv run pytest` → боевой прогон установщика,
+reverse-factory 84c7749), и держать рядом с работающим ещё две копии — значит
+гарантированно разойтись с ним снова.
+
+## Решение
+
+**Единственный канон навыка — модуль `skillkit.canon`.** Туда переносится
+проверенный канон фабрики целиком: раскладка (`SkillLayout`, `layout`), рендер
+(`render_skill_md` / `render_skill_meta` / `render_pyproject` /
+`render_install_docs` / `render_skillgateignore`) и валидатор
+`validate_canonical_skill` вместе с его тестами.
+
+Почему именно `skillkit`, а не `clikit` и не фабрика:
+
+- **Писатель формата обязан жить рядом с читателем.** Всё, что рендерит канон,
+  читает и ставит этот же кит: `_skill_meta.toml` разбирает `skillkit.manifest`,
+  папку навыка раскладывает по агентам `skillkit.targets`, зависимости и
+  self-check поднимает `skillkit.bootstrap`. Сгенерированный `install/install.py`
+  — буквально тонкая обёртка над `skillkit`. Разведи их по разным репозиториям —
+  и они разойдутся молча, как уже разошлись.
+- **`clikit` — не та зона.** Кит отвечает за плоть CLI (command-kit, вывод,
+  конфиг, транспорт) и про навыки не знает ничего. То, что он рендерил
+  `_skill_meta.toml` с несуществующим `kind = "cli"`, — прямое следствие того,
+  что формат жил не у своего владельца.
+- **Фабрика — потребитель, а не библиотека.** `reverse-factory` тянет playwright,
+  camoufox, nodriver. Сделать её зависимостью клиента `skillery` нельзя.
+- **Кит уже общий.** И `reverse-factory`, и `skillery-cli` уже объявляют
+  `s-skillkit>=0.3.7` — новая зависимость никому не заводится.
+- **Канон ничего не тянет.** Модуль на голом stdlib (`re`, `tomllib`,
+  `dataclasses`, `pathlib`): TOML пишем сами, читаем через `tomllib`. Лёгкий кит
+  остаётся лёгким.
+
+Граница «форма против смысла»: канон держит ФОРМУ (frontmatter, аллоулист
+`files`, порядок ключей манифеста, раскладку файлов, состав `install/`), а СМЫСЛ
+приносит производитель через `body=` / `description=`. Поэтому тело `SKILL.md` по
+умолчанию в ките нейтральное (каркас AK-канона с TODO), а реверс-специфичное тело
+остаётся в фабрике.
+
+Остальные места зовут канон, а не копируют его:
+
+- `reverse_factory.factory.canon` — тонкий ре-экспорт `skillkit.canon` плюс своё
+  реверс-тело `SKILL.md`. Путь модуля сохранён: по нему ходят шесть импортёров и
+  фитнес-функция.
+- `clikit.scaffold` — рендер навыка удалён целиком; кит скаффолдит только CLI.
+
+## Последствия
+
+Правило канона теперь ровно одно на всю экосистему: правка формы навыка делается
+в `skillkit.canon`, и её видят все производители сразу. Валидатор и рендер лежат
+рядом, поэтому «рендер выдал то, что валидатор не принимает» ловится тестом в
+самом ките.
+
+`clikit` перестал уметь генерировать навык — это НАМЕРЕННАЯ потеря. Кто
+скаффолдил навык через `clikit.scaffold_cli(skill=True)`, получал невалидный
+навык; теперь он получает CLI-пакет и берёт навык у `skillkit.canon` (или у
+`skillery new`). Обратная совместимость сломана осознанно: сохранять способ
+сделать заведомо непроходящий навык — хуже, чем убрать его.
+
+Кит подрос: `skillkit` перестал быть чисто ФС-механикой и взял на себя ещё и
+рендер. Оправдание — тот же аргумент, что и в решении: формат, который кит
+читает, он же должен и писать. Брендо-нейтральность при этом сохранена: имён
+конкретных продуктов и фабрик в модуле нет.
+
+Обязательство на будущее: `skillery-cli` пока держит свою копию (`templates/`).
+Пока миграция не закончена, у канона фактически два писателя, и расхождение
+возможно — это записано отдельной задачей и закрывается фитнес-функцией на
+стороне клиента, а не договорённостью.
+
+## Альтернативы
+
+**Оставить канон в `reverse-factory`, остальным импортировать оттуда.** Отклонено:
+фабрика тянет браузерный стек (playwright / camoufox / nodriver), и клиент
+`skillery`, который ставится пользователю одной командой, не может от неё
+зависеть. Библиотечный код в приложении — инверсия слоёв.
+
+**Сделать каноном `clikit`.** Отклонено: чужая зона. `clikit` — плоть CLI, про
+навыки не знает; именно его версия канона и разошлась сильнее всех
+(`kind = "cli"`, плоская раскладка). Кроме того, `clikit` не зависит от
+`skillkit`, а канон обязан согласовываться с читателем манифеста — пришлось бы
+либо заводить зависимость снизу вверх, либо снова дублировать знание.
+
+**Отдельный кит `skillcanonkit`.** Отклонено как лишняя сущность: канон — 1000
+строк stdlib, целиком про навык, и уже сейчас неотделим от `manifest`/`targets`.
+Новый кит дал бы четвёртый репозиторий, четвёртый выпуск и четвёртую версию в
+чужих зависимостях ради модуля, у которого один естественный владелец.
+
+**Не переносить, а описать канон документом и проверять линтером.** Отклонено:
+документ не рендерит. Копии остались бы копиями, а расхождение ловилось бы
+постфактум — ровно так и жили до сих пор.

s_skillkit-0.4.0/docs/adr/README.md

@@ -0,0 +1,30 @@
+# ADR — журнал архитектурных решений
+
+**Что это.** ADR (Architecture Decision Record) — короткий документ на **одно** архитектурное решение: контекст → что решили → почему → последствия. Лежат здесь, в `docs/adr/`, со **сквозной нумерацией** (`0001-…`, `0002-…`). Шаблон — [`0000-template.md`](0000-template.md).
+
+**Зачем.** «Почему» проекта нельзя держать в комментариях к задачам и переписке — оно теряется. ADR — дистиллят решения: агент читает его **перед** правкой и не «чинит» то, что было выбрано сознательно. Дёшев по токенам: одно решение прочитать проще, чем реконструировать его из истории коммитов.
+
+## Когда заводить ADR — когда сошлись 3 условия
+
+1. решение **дорого откатить** (влияет на структуру, данные, контракты);
+2. без контекста оно **выглядит странно** (кто-то потом захочет «починить»);
+3. были **реальные альтернативы** и выбор — осознанный трейдофф.
+
+Если хотя бы одно условие не выполнено — ADR не нужен, хватит `comment` на задаче в Atlas.
+
+## Правила ведения
+
+- **Нумерация сквозная**, файл — `NNNN-краткий-слаг.md` (`0001-operating-model-foundamentals.md`).
+- **Не редактировать задним числом.** Принятое решение — исторический факт. Если решение отменено новым — старому ставим `Статус: superseded` (со ссылкой на новое ADR), а не переписываем его.
+- **«Схлопывание».** Когда цепочка `superseded` разрослась, допустимо свести её к одному ADR с текущим состоянием — ради экономии контекста агента. Прежние помечаем как схлопнутые.
+- **Статусы:** `proposed` → `accepted` → (`superseded` / `deprecated`).
+
+## Что НЕ идёт в ADR
+
+- **состояние** (ветка/worktree, стадия) — это тег/поле задачи в Atlas;
+- **ход работы / handoff** — `comment` на задаче в Atlas;
+- **черновой план реализации** — scratchpad, в `.gitignore`, в репо не коммитится.
+
+Полная модель фиксации артефактов (4 слоя) — в `ai-ecosystem-core/AGENT-OPERATING-MODEL.md`, раздел «Модель фиксации артефактов».
+
+**Методология:** практика ADR (Michael Nygard), компактный формат Matt Pocock (`github.com/mattpocock/skills`, grill-with-docs), примеры в NATS / AG2.

{s_skillkit-0.3.7 → s_skillkit-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "s-skillkit"
-version = "0.3.7"
+version = "0.4.0"
 description = "Локальное ядро управления навыками: install из git/локальной папки, junction/symlink-линковка в scope агента, .skillignore-фильтр, build manifest, project-манифест. 0 завязок на сеть/auth — stdlib + tomli-w + pathspec + platformdirs."
 readme = "README.md"
 license = { text = "MIT" }
@@ -55,6 +55,15 @@ select = ["E", "F", "I", "B", "UP", "N", "SIM", "RUF"]
 #   возвращает (store, target, store_dir); читаемее, чем индексирование).
 ignore = ["RUF001", "RUF002", "RUF003", "RUF022", "RUF059"]
 
+[tool.ruff.lint.per-file-ignores]
+# canon.py несёт ДОСЛОВНЫЕ шаблоны генерируемых файлов (install.ps1 / install.sh /
+# install.py / _skill_meta.toml). Перенос строки внутри такого шаблона — это правка
+# ЧУЖОГО файла, который потом ляжет на диск навыка: команда PowerShell,
+# разорванная ради длины, просто не выполнится. Ограничение длины снято для
+# модуля целиком, потому что `# noqa` внутри многострочного литерала уехал бы в
+# сам вывод.
+"skillkit/canon.py" = ["E501"]
+
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 testpaths = ["tests"]

{s_skillkit-0.3.7 → s_skillkit-0.4.0}/skillkit/__init__.py

@@ -10,8 +10,11 @@ platformdirs. Запуск подпроцессов (uv/git/cmd/powershell) —
   локальная папка / stub) + junction/symlink-линковка в scope агента,
   инкрементальный update по sha-diff, remove/keep-local/purge, migrate_scope.
   Включает P0 stub-would-clobber guard.
-- ``targets`` — ``IAgentTarget`` + детект агента (Claude Code / Codex /
+- ``targets`` — ``AgentTarget`` + детект агента (Claude Code / Codex /
   OpenCode / Antigravity). Раскладки сверены с живым опытом 2026-07-21.
+- ``canon`` — КАНОН раскладки навыка: рендер (SKILL.md / _skill_meta.toml /
+  pyproject / install/ / .skillgateignore) и ``validate_canonical_skill``.
+  Писатель формата живёт рядом с читателем (``manifest``/``targets``) — ADR-0001.
 - ``manifest`` — build manifest для publish + ридеры frontmatter / _skill_meta.toml
   (в т.ч. артефакты установки: cli / mcp / runtime_dependencies / onboarding /
   hooks).
@@ -44,6 +47,7 @@ from __future__ import annotations
 from skillkit import (
     binary_installer,
     bootstrap,
+    canon,
     collections,
     deps_installer,
     filter,
@@ -64,6 +68,18 @@ from skillkit.binary_installer import (
     platform_asset_name,
 )
 from skillkit.bootstrap import bootstrap_skill, run_self_check
+from skillkit.canon import (
+    ALLOWED_KINDS,
+    SkillLayout,
+    SkillMeta,
+    layout,
+    render_install_docs,
+    render_pyproject,
+    render_skill_md,
+    render_skill_meta,
+    render_skillgateignore,
+    validate_canonical_skill,
+)
 from skillkit.collections import LocalCollectionError
 from skillkit.config import SkillkitConfig, configure, reset_to_defaults
 from skillkit.errors import (
@@ -111,7 +127,7 @@ from skillkit.targets import (
     ClaudeCodeTarget,
     CodexTarget,
     HookConfigDescriptor,
-    IAgentTarget,
+    AgentTarget,
     McpConfigDescriptor,
     OpenCodeTarget,
     agent_skill_dir,
@@ -120,7 +136,7 @@ from skillkit.targets import (
 )
 from skillkit.uv_bootstrap import ensure_uv
 
-__version__ = "0.3.7"
+__version__ = "0.4.0"
 
 __all__ = [
     "__version__",
@@ -168,7 +184,7 @@ __all__ = [
     "stamp_ownership",
     "skill_dir_name",
     # targets
-    "IAgentTarget",
+    "AgentTarget",
     "BaseAgentTarget",
     "ClaudeCodeTarget",
     "CodexTarget",
@@ -179,6 +195,17 @@ __all__ = [
     "agent_skill_dir",
     "detect_agent",
     "get_target",
+    # канон раскладки навыка (рендер + валидатор)
+    "ALLOWED_KINDS",
+    "SkillLayout",
+    "SkillMeta",
+    "layout",
+    "render_install_docs",
+    "render_pyproject",
+    "render_skill_md",
+    "render_skill_meta",
+    "render_skillgateignore",
+    "validate_canonical_skill",
     # manifest
     "BuiltManifest",
     "build_manifest",
@@ -194,6 +221,7 @@ __all__ = [
     "bootstrap_skill",
     "run_self_check",
     # подмодули (ФС-механика навыка)
+    "canon",
     "linker",
     "filter",
     "manifest",