gennady 0.8.3 → 0.8.4

package/cli/cmd/README.md

@@ -0,0 +1,185 @@
+# cli/cmd — Команды CLI
+
+16 команд для AI-агентов: работа с git, генерация commit-сообщений, ревью, merge-конфликты, линтинг, навигация по коду, синхронизация, мониторинг.
+
+---
+
+## Типовые сценарии
+
+### 1. Сделать коммит
+
+```bash
+# Сгенерировать commit message из staged-изменений
+npx gennady commit
+
+# One-line + сразу применить
+npx gennady commit --mode=oneline --apply
+
+# С указанием задачи
+npx gennady commit --task=MAILCORE-123
+```
+
+### 2. Проверить качество кода
+
+```bash
+# Линтинг директории
+npx gennady lint ./src
+
+# Только staged .ts файлы
+npx gennady lint --staged
+
+# Автофикс DbC-контрактов
+npx gennady lint ./src --autofix
+```
+
+### 3. Навигация по проекту
+
+```bash
+# Карта проекта (все файлы с аннотациями)
+npx gennady orient
+
+# Найти файлы по задаче
+npx gennady orient --task=TSK-03
+
+# Кто потребляет модуль
+npx gennady orient --consumer=DbcTsLinter
+
+# Граф зависимостей
+npx gennady orient --graph
+
+# Детальный просмотр файла
+npx gennady orient --file=path/to/file.ts
+
+# Встроить orient-инструкции в AGENTS.md
+npx gennady agents-rules
+```
+
+### 4. Ревью MR/PR
+
+```bash
+# Верификация MR по текущей ветке
+npx gennady review-verify
+
+# По URL
+npx gennady review-verify --url="https://gitlab.com/group/repo/-/merge_requests/42"
+
+# По ref
+npx gennady review-verify group/repo!42
+
+# Только XML issues
+npx gennady review-issues --ref=group/repo!42
+
+# Ответить на discussion-треды
+echo '[{"discussionId":"abc","body":"Fixed"}]' | \
+  npx gennady vcs-reply --project=group/repo --iid=42
+```
+
+### 5. AI-ревью staged-изменений
+
+```bash
+npx gennady review
+npx gennady review --branch=develop
+```
+
+### 6. Разрешить merge-конфликты
+
+```bash
+# После git merge с конфликтами
+npx gennady resolve-conflicts
+npx gennady resolve-conflicts --branch=main --incoming=feature/x
+```
+
+### 7. Собрать файлы для AI-контекста
+
+```bash
+# XML (по умолчанию)
+npx gennady cat "./src/**/*.ts"
+
+# Markdown, без цвета
+npx gennady cat "./src/**/*.ts" --output=md --plain | pbcopy
+
+# Из удалённого MR
+npx gennady cat --url="https://gitlab.com/.../-/merge_requests/123"
+```
+
+### 8. Синхронизировать директивы и навыки
+
+```bash
+# Директивы
+npx gennady sync
+npx gennady sync --dry-run
+
+# Навыки
+npx gennady sync-skills
+npx gennady sync-skills --dry-run
+```
+
+### 9. Мульти-модельный анализ
+
+```bash
+# Мнение двух моделей с синтезом
+npx gennady alt-opinion \
+  --model="llmproxy/kimi-k2.6" \
+  --model="llmproxy/glm-5.1" \
+  --synthModel="llmproxy/deepseek-v4-pro" \
+  --file="./spec.md"
+```
+
+### 10. Мониторинг AI-агентов
+
+```bash
+# Live-дашборд
+npx gennady agent-mon
+
+# Одноразовый снапшот
+npx gennady agent-mon --once
+```
+
+---
+
+## Все команды
+
+| Команда             | Назначение                                              |
+| ------------------- | ------------------------------------------------------- |
+| `commit`            | Генерация commit message из staged-изменений через AI   |
+| `cat`               | Вывод файлов в XML/Markdown для AI-контекста            |
+| `review`            | AI-ревью staged изменений                               |
+| `review-verify`     | Сборка промпта для верификации MR/PR discussions        |
+| `review-issues`     | XML-артефакт issues из MR/PR                            |
+| `vcs-reply`         | Постинг ответов в GitLab MR discussions                 |
+| `resolve-conflicts` | Промпт для AI-разрешения merge-конфликтов               |
+| `remote-console`    | Зеркалирование браузерной консоли в stdout              |
+| `lint`              | Валидация .ts файлов: headers, anchors, DbC, invariants |
+| `alt-opinion`       | Мульти-модельные мнения с синтезом                      |
+| `sync`              | Синхронизация `ai/directives/` из npm-пакета            |
+| `sync-skills`       | Синхронизация SDD-навыков в `.claude/skills/`           |
+| `agent-mon`         | Интерактивный дашборд мониторинга AI-агентов            |
+| `orient`            | Навигация по file-header и DBC-контрактам               |
+| `agents-rules`      | Инструкция по orient для AI-агентов                     |
+
+---
+
+## Структура команды
+
+```
+cli/cmd/<name>/
+├── <name>.cmd.ts     # Исполняемая логика команды
+├── index.ts          # Точка входа для динамического импорта
+├── help.ts           # help-вывод (опционально)
+└── README.md         # Документация (есть только у orient — канонический источник для agents-rules)
+```
+
+При добавлении команды обновить: `cli/cmd/README.md` (этот файл), `cli/AGENTS.md`, `cli/gennady.ts`.
+
+---
+
+## Связанные спеки
+
+- `specs/cli/cli.spec.md` — общая спека CLI
+- `specs/cli/lint/lint.spec.md` — линтинг
+- `specs/cli/alt-opinion/alt-opinion.spec.md` — alt-opinion
+- `specs/cli/cat/cat.spec.md` — cat
+- `specs/cli/sync/sync.spec.md` — sync
+- `specs/cli/sync-skills/sync-skills.spec.md` — sync-skills
+- `specs/cli/agents-rules/agents-rules.spec.md` — agents-rules
+- `specs/cli/e2e/e2e.spec.md` — e2e-тестирование

package/dist/ai/directives/sdd/audit.directive.xml

@@ -45,6 +45,16 @@
       Files in diff but absent from ticket declaration + Execution Log → candidates for `CLOSED_WORLD_DRIFT` (public entities) or `EXECUTION_LOG_INCOMPLETE` (utility-only changes).
     </Axiom>
 
+    <Axiom id="AX_MECHANICAL_VIA_SDD_CHECK">
+      Deterministic mechanical checks — file-header presence, Task-ID collision, tracker-sync — are NOT hand-coded here. They live in one tool, `sdd check`, which sdd-check (whole tree) and this directive (scoped) both consume. Single source of mechanical truth → no drift between the two SDD reviewers.
+
+      - `sdd check --files <git-diff in-scope files>` → [HEADERS] (`@file`/`@consumers`/`@tasks` presence).
+      - `sdd check --task <Task-ID>` → [TASKID] (collision for that id) + [TRACKER_SYNC] (Meta.Status vs tracker row).
+      - `sdd check <root>` (no flag) → tree-wide [TASKID] orphan refs (epic mode).
+
+      Audit still owns everything the tool cannot decide mechanically: semantic `@consumers` resolvability, current-Task-ID identity, append-only `@tasks` regression vs git, section-anchor coverage, and all code-reading checks (closed-world, completeness, rules-compliance, runtime-backing, backflow).
+    </Axiom>
+
     <Axiom id="AX_DRIFT_TAXONOMY">
       Findings are classified by type. Every finding has exactly one:
 
@@ -318,13 +328,15 @@
       <Goal>Verify Task-ID integrity and ticket section-anchor coverage per `AX_TASK_ID_INTEGRITY`. Reuses STEP_2 git-diff scope.</Goal>
       <Action>
         1. TRACE_HEADER (STACK `ROOT__TASK_ID_INTEGRITY_CHECK`).
-        2. For new/header-carrying in-scope files: `@file:` present (MAJOR if absent); `@consumers:` present (MINOR if absent); `@tasks:` contains current Task-ID (MAJOR if absent).
-        3. Collect all `@tasks: TSK-NN[, …]` references from in-scope files.
-        4. Each ID — verify `tasks/**/*.task-NN.md` exists. Orphan → `TASK_ID_DRIFT` (`MAJOR`, HIGH).
-        5. Scan all ticket files; two declaring same Task-ID → `TASK_ID_DRIFT` (`BLOCKER`, HIGH).
-        6. Compare current `@tasks:` values against pre-task git ref. Prior IDs removed → `TASK_ID_DRIFT` (`MAJOR`).
-        7. **Ticket section-anchor coverage** (per `AX_TASK_ID_INTEGRITY` last bullet). For each anchor name templated in `TASK_TICKET_STRUCTURE` → `~/.claude/skills/sdd-execute/scripts/sdd extract <ticket> <NAME>`. Exit `2` → `EXECUTION_LOG_INCOMPLETE` `missing-section-anchor`; exit `3` → `EXECUTION_LOG_INCOMPLETE` `anchor-unbalanced`. Zero anchors found → escalate to BLOCKER.
-        8. Phase Progress. STOP.
+        2. **Mechanical primitives — delegate, do NOT hand-grep** (shared source of truth with sdd-check, per `AX_MECHANICAL_VIA_SDD_CHECK`):
+           - `~/.claude/skills/sdd-execute/scripts/sdd check --files <git-diff in-scope files>` → [HEADERS]: `verdict=PARTIAL`/`NONE` on a code file → `@file:` absent = `TASK_ID_DRIFT`/`MAJOR`, `@tasks:` absent = `MAJOR`; `has_consumers=0` = `MINOR`.
+           - `~/.claude/skills/sdd-execute/scripts/sdd check --task <Task-ID>` → [TASKID] `collision` → `TASK_ID_DRIFT` (`BLOCKER`); orphan refs surface in tree-mode (run plain `sdd check` for epic-level).
+        3. **Residual semantic checks the tool cannot do** (keep here):
+           - `@consumers:` value must resolve to an entity name in spec/codebase (not a path/dir) → `MINOR` if it does not.
+           - `@tasks:` contains current Task-ID (the tool reports presence; YOU confirm it is THIS Task-ID, not just any).
+           - Compare current `@tasks:` values against pre-task git ref. Prior IDs removed → `TASK_ID_DRIFT` (`MAJOR`).
+        4. **Ticket section-anchor coverage** (per `AX_TASK_ID_INTEGRITY` last bullet). For each anchor name templated in `TASK_TICKET_STRUCTURE` → `~/.claude/skills/sdd-execute/scripts/sdd extract <ticket> <NAME>`. Exit `2` → `EXECUTION_LOG_INCOMPLETE` `missing-section-anchor`; exit `3` → `EXECUTION_LOG_INCOMPLETE` `anchor-unbalanced`. Zero anchors found → escalate to BLOCKER.
+        5. Phase Progress. STOP.
       </Action>
     </Step>
 
@@ -375,10 +387,9 @@
         4. **Placeholder leftover scan** (fabricated done): for every `[x]` line in current round, scan for residual `<...>` literal. Any match → `EXECUTION_LOG_INCOMPLETE` (`BLOCKER`) tagged «fabricated done».
         5. Round immutability: prior round sections compared against pre-round git ref. Any edit/reorder/delete → `EXECUTION_LOG_INCOMPLETE` (`BLOCKER`).
         6. Reopens metadata: Meta `Reopens: <count>` = (Round headers count − 1). Mismatch → `EXECUTION_LOG_INCOMPLETE` (`MAJOR`).
-        7. Tracker sync:
-           - ticket Status (Meta) matches `tasks/<scope>/README.md` Tracker row for this Task-ID.
-           - `tasks/README.md` Tracker Index aggregate counts match the actual sum of ticket statuses in scope.
-           - Mismatches → `EXECUTION_LOG_INCOMPLETE` (`MAJOR`) tagged «tracker desync».
+        7. Tracker sync — delegate to `sdd check --task <Task-ID>` (per `AX_MECHANICAL_VIA_SDD_CHECK`), do NOT hand-grep:
+           - read [TRACKER_SYNC]: `match=NO` (ticket Meta.Status ≠ tracker row) or `NO_ROW` → `EXECUTION_LOG_INCOMPLETE` (`MAJOR`) tagged «tracker desync». `UNPARSEABLE` → INFO.
+           - aggregate Tracker Index counts (`tasks/README.md`) vs sum of statuses in scope remains a manual cross-check in epic mode.
         8. Phase Progress. STOP.
       </Action>
     </Step>

package/dist/ai/directives/sdd/critic-protocol.xml

@@ -21,6 +21,7 @@
       7. Non-goals — explicit exclusions.
       8. Consistency — no internal contradictions.
       9. Testability — claims verifiable, not vague ("should be fast").
+      10. Parsimony — every entity/type/contract traces to a requirement or use-case. Flag: unjustified (no driving requirement), redundant (two entities overlap WITHIN this spec), speculative (surface beyond stated boundary). Prefer reuse/extend over a new entity. Scope is intra-spec only — you cannot see the project, so never claim "X already exists elsewhere" (that is the orchestrator's check).
     </Axiom>
 
     <Axiom id="AX_TASK_DIMENSIONS">
@@ -30,6 +31,7 @@
       3. Phases — ordered correctly, deps explicit, no gaps (impl without test), Target Files non-overlapping.
       4. Clarity — fresh agent can build from this alone. Inputs/outputs specified.
       5. Completeness — all sections filled, no <TBD> or <YYYY-MM-DD>.
+      6. Parsimony — task introduces NO entity/type/method absent from the parent spec inventory. New surface declared in a task without spec backing = finding. Spec entities are reused, not re-declared. Cross-project reuse is the orchestrator's check, not yours.
     </Axiom>
 
     <Axiom id="AX_SEVERITY">
@@ -54,6 +56,7 @@
     <Pattern id="AP_FORMAT_BIAS">Assuming quality from formatting. Structure ≠ correctness.</Pattern>
     <Pattern id="AP_CREEP">Reading beyond artifact + parent spec.</Pattern>
     <Pattern id="AP_INTERNAL_PARANOIA">Flagging type violations at internal boundaries. Type system prevents these.</Pattern>
+    <Pattern id="AP_REUSE_BLIND">Claiming an entity duplicates something "in the project". You see only artifact + parent spec — judge redundancy ONLY within that scope. Project-wide dedup is the orchestrator's job.</Pattern>
   </Anti_Patterns>
 
   <Execution_Plan>

package/dist/ai/directives/sdd/critic.directive.xml

@@ -1,7 +1,7 @@
 <SddCritic keywords="critic, spec-review, task-review, bdd-audit, blind-spot, autonomous-polish, multi-round, pre-execute, orchestration" type="directive" ver="2.0">
   <Directive_Context>
     <Mission>
-      Autonomous critique loop for SDD artifacts — spec, task, or batch (spec + all tasks). You are the ORCHESTRATOR in the root session. Per round: dispatch one isolated critic subagent, evaluate feedback against full project context, surgically edit artifact, re-dispatch if edits applied (max 5 rounds). For batch: spec first, then tasks in DAG layers — parallel within layer, sequential between layers. On CLEAN: delete `## Critic Rounds` (temporary scaffolding). Artifact is clean, improvements integrated.
+      Autonomous critique loop for SDD artifacts — spec, task, or batch (spec + all tasks). You are the ORCHESTRATOR in the root session. Per round: dispatch one isolated critic subagent, evaluate feedback against full project context, reconcile every introduced entity against existing project surface (reuse > extend > justify > escalate), surgically edit artifact, re-dispatch if edits applied (max 5 rounds). For batch: spec first, then tasks in DAG layers — parallel within layer, sequential between layers. On CLEAN: delete `## Critic Rounds` (temporary scaffolding). Artifact is clean, improvements integrated.
     </Mission>
   </Directive_Context>
 
@@ -15,6 +15,7 @@
     <Axiom id="AX_DEFAULT_ACCEPT">Uncertain → ACCEPT. Cost of rejecting real finding > cost of accepting marginal one.</Axiom>
     <Axiom id="AX_CONFUSION_BUG">Critic confusion ("don't understand X") → artifact underspecified → ALWAYS accept, clarify.</Axiom>
     <Axiom id="AX_SURGICAL">Close the gap only. No restructure, rewrite, restyle. Structural overhaul → suggest re-scaffold, stop.</Axiom>
+    <Axiom id="AX_REUSE_FIRST">Orchestrator holds full project context — the ONLY actor able to detect duplication against existing code/specs (the isolated critic cannot). For every entity/type/method/contract the artifact introduces, reconcile before accepting it: REUSE existing (adapt artifact to it) > EXTEND existing > JUSTIFY new (record one-line rationale in artifact: why existing surface is insufficient) > ESCALATE to operator. Unjustified new surface is a finding to resolve, not to wave through. Bias toward consolidation — do not let the system grow a duplicate entity each round.</Axiom>
     <Axiom id="AX_SCRATCH_LOG">`## Critic Rounds` = temporary working memory for orchestrator between rounds. Deleted on final CLEAN.</Axiom>
     <Axiom id="AX_TASK_PARALLEL">Tasks critiqued in DAG layers. Same layer (no inter-dependencies) → parallel dispatch. Different layers → sequential.</Axiom>
     <Axiom id="AX_LANG">Directive: English. Artifact prose (Critic Rounds, summary): Russian.</Axiom>
@@ -36,6 +37,7 @@
     <Pattern id="AP_OVEREDIT">Rewriting sections. Close the gap, don't redecorate.</Pattern>
     <Pattern id="AP_DISMISS_CONFUSION">Ignoring "I don't understand X". Always fix.</Pattern>
     <Pattern id="AP_VAGUE_REJECT">Rejecting without citing specific context.</Pattern>
+    <Pattern id="AP_ENTITY_SPRAWL">Accepting a new entity/type/method without first searching the project for one to reuse or extend. New surface every round = sprawl.</Pattern>
   </Anti_Patterns>
 
   <Execution_Plan>
@@ -71,14 +73,27 @@
         ACCEPT: genuine gap, misunderstanding reveals ambiguity, would break downstream agent, or uncertain (AX_DEFAULT_ACCEPT).
         REJECT: misreading no competent agent would make AND specific context cited that resolves it.
         Confusion points → ALWAYS accept (AX_CONFUSION_BUG).
-        Zero accepted → go to STEP_5 (stop). Any accepted → go to STEP_3.
+        Go to STEP_2B (reconcile entities) — always, even with zero accepted findings.
+      </Action>
+    </Step>
+
+    <Step id="2B_RECONCILE">
+      <Goal>Reuse-first reconciliation — orchestrator-only, uses full project context (AX_REUSE_FIRST).</Goal>
+      <Action>
+        Round 1: reconcile EVERY entity/type/method/contract the artifact introduces. Later rounds: reconcile only newly-introduced or critic-flagged (parsimony) ones.
+        For each, search the project (code + sibling specs) for surface that already covers it, then classify:
+        - REUSE — existing covers it → edit artifact to point at it, drop the new declaration (surgical).
+        - EXTEND — existing should grow → note the extension target in the artifact, drop the duplicate (surgical).
+        - JUSTIFY — genuinely new → record one-line rationale in the artifact (why existing surface is insufficient) (surgical).
+        - ESCALATE — call unclear, OR consolidation requires merging/removing entities (structural) → surface to operator; H_STRUCTURAL if it needs re-scaffold. Do NOT perform structural consolidation yourself.
+        Surgical reuse/justify edits + accepted findings → go to STEP_3. Zero edits after reconciliation → go to STEP_5 (stop).
       </Action>
     </Step>
 
     <Step id="3_EDIT">
       <Goal>Surgical edit.</Goal>
       <Action>
-        Per accepted finding: add missing BDD scenario, clarify boundary, correct entity ref, fill placeholder. Target only the gap. Structural rewrite → H_STRUCTURAL.
+        Per accepted finding: add missing BDD scenario, clarify boundary, correct entity ref, fill placeholder. Per reconcile decision: point at existing surface (REUSE/EXTEND) or record new-entity rationale (JUSTIFY). Target only the gap. Structural rewrite or entity merge/removal → H_STRUCTURAL / ESCALATE.
       </Action>
     </Step>
 
@@ -91,6 +106,7 @@
         - Verdict: <CLEAN|NEEDS_WORK|CRITICAL>
         - Accepted: N — <list>
         - Rejected: N — "<finding>" → <reason>
+        - Reconcile: <entity → REUSE <target> | EXTEND <target> | JUSTIFY <rationale> | ESCALATE>
         - Changes: <list>
         ```
         Append-only.
@@ -136,6 +152,10 @@
           - <change>
           - ...
 
+        ♻️ Reuse decisions:
+          - <entity> → REUSE <target> | EXTEND <target> | JUSTIFY <rationale> | ESCALATE <question>
+          - ...
+
         ⚠️ Unresolved (if not CLEAN):
           - <finding> → <recommendation>
 
@@ -154,5 +174,7 @@
     - Keep `## Critic Rounds` after CLEAN.
     - ACCEPT without edit.
     - REJECT without specific context.
+    - Accept a new entity without reuse-first reconciliation (AX_REUSE_FIRST).
+    - Structurally merge/remove entities yourself — ESCALATE instead.
   </HardForbidden>
 </SddCritic>

package/dist/ai/skills/README.md

@@ -0,0 +1,150 @@
+# ai/skills — AI-навыки для агентов
+
+15 навыков (13 SDD + alt-opinion + workspace-permission-setup) для Specification-Driven Development, мульти-модельного анализа и настройки автономной среды.
+
+> `sdd-hooks-install` (хуки live-прогресса для `sdd-execute`) и `workspace-permission-setup` мигрированы в хранилище из `~/.claude/skills` — теперь под git и деплоятся через `sync-skills`.
+
+---
+
+## Типовые сценарии (Use Cases)
+
+### 1. Спроектировать новый модуль с нуля
+
+```bash
+npx gennady sync-skills
+```
+
+Затем в агенте: «@sdd-setup создай проект» → «@sdd-discover спроектируй scope vcs-client» → «@sdd-module-decomposition разбей на модули» → «@sdd-scaffold сгенерируй таски» → «@sdd-critic проверь таски» → «@sdd-execute TSK-01»
+
+| Шаг | Навык | Что делает |
+| --- | ----- | ---------- |
+| 1 | `sdd-setup` | Инициализирует `specs/README.md` (Vision, Scope Graph, таблица скоупов) |
+| 2 | `sdd-discover` | Создаёт `specs/<scope>/<scope>.spec.md` — видение, требования, архитектура |
+| 3 | `sdd-module-decomposition` | Декомпозирует product/library scope на модульные спеки с инвентарём сущностей |
+| 4 | `sdd-scaffold` | Генерирует DAG тасков из спек: Cascade Table, BDD, Phases Overview |
+| 5 | `sdd-critic` | Многораундовая критика тасков: диспатчит критика, правит артефакт (до 5 раундов) |
+| 6 | `sdd-execute` | Исполняет один таск от начала до конца: dispatch фаз → audit |
+
+### 2. Выполнить задачу
+
+```
+@sdd-execute TSK-03
+```
+
+Или: «выполни следующую», «execute pickable», «выбери что делать дальше».
+
+Навык читает таск, диспатчит фазы одну за другой, закрывает round, диспатчит fresh-eyes audit.
+
+### 3. Выполнить пачку задач
+
+```
+@sdd-execute-batch выполни всю очередь
+```
+
+Параллелит таски с непересекающимися файлами. Опциональный epic-level audit.
+
+### 4. Проверить качество спеки / таска
+
+```
+@sdd-critic проверь спеку cli/cli.spec.md
+@sdd-critic проверь таск TSK-03
+```
+
+Многораундовая критика (до 5 раундов): диспатчит изолированного критика, оценивает фидбек, правит артефакт.
+
+### 5. Продолжить / доработать существующую спеку
+
+```
+@sdd-continue добавь sync-skills в cli
+@sdd-continue измени архитектуру на event-driven
+```
+
+Автоопределение режима: refine (добавить) или pivot (заменить).
+
+### 6. Проверить целостность SDD-воркфлоу
+
+```
+@sdd-check
+```
+
+Read-only: проверяет связность спек, синхронизацию трекеров, полноту execution-логов, консистентность DAG.
+
+### 7. Аудит завершённой задачи
+
+```
+@sdd-audit TSK-05
+```
+
+Fresh-eyes: читает таск + спеку + git diff, механический линтинг, верификация правил. Фидинги роутятся в артефакты (правки спек, переоткрытие тасков).
+
+### 8. Починить после ревью / sdd-check
+
+```
+@sdd-fix найди и исправь проблемы из sdd-check
+```
+
+Классифицирует фидинги, согласовывает с оператором, исполняет фиксы, переоткрывает таски, верифицирует.
+
+### 9. Спроектировать инфраструктурный скоуп
+
+```
+@sdd-infra спроектируй infra-golang
+```
+
+Для bootstrap'а tooling'а: package manager, type-checker, linter, formatter, test runner, git hooks, CI.
+
+### 10. Получить мульти-модельное мнение
+
+```
+@alt-opinion оцени спеку cli/cli.spec.md
+```
+
+Запускает 2+ модели параллельно, синтезирует через третью. Без аргументов — автоаудит текущего контекста сессии.
+
+---
+
+## Execution-паттерны
+
+| Паттерн | Как работает | Навыки |
+| ------- | ----------- | ------ |
+| **Directive activation** | Извлечь intent → загрузить директиву → активироваться как она → выполнить план | sdd-setup, sdd-discover, sdd-module-decomposition, sdd-scaffold, sdd-audit, sdd-continue, sdd-critic, sdd-fix, sdd-infra |
+| **Orchestrator** | Прочитать таск → dispatch фаз (typed Handoff) → dispatch audit. Сам код не пишет | sdd-execute, sdd-execute-batch |
+| **CLI delegation** | Подготовить артефакт → вызвать `npx gennady alt-opinion` → показать результат | alt-opinion |
+| **Read-only verifier** | Саморефлексия + механические проверки через `sdd scan`. Код не пишет | sdd-check |
+
+---
+
+## Структура навыка
+
+```
+ai/skills/<name>/
+├── SKILL.md          # YAML frontmatter (name, description, compatibility) + markdown body
+├── scripts/          # опционально: bash/js утилиты
+└── *.prompt.md       # опционально: кастомные промпты
+```
+
+---
+
+## Синхронизация в проекты
+
+```bash
+# Синхронизировать все навыки
+npx gennady sync-skills
+
+# Предпросмотр
+npx gennady sync-skills --dry-run
+
+# Конкретный навык
+npx gennady sync-skills sdd-execute
+```
+
+Навыки деплоятся из `ai/skills/` → `.claude/skills/` проекта. Пути нормализуются: dev-пути (`~/Developer/gennady/...`) заменяются на продуктовые.
+
+---
+
+## Связанные спеки
+
+- `specs/ai-skills/ai-skills.spec.md` — общая спека библиотеки
+- `specs/ai-skills/skill-contract/skill-contract.spec.md` — контракт навыка
+- `specs/ai-skills/sdd-skills/sdd-skills.spec.md` — SDD-навыки
+- `specs/ai-skills/alt-opinion/alt-opinion.spec.md` — alt-opinion

package/dist/ai/skills/sdd-check/SKILL.md

@@ -42,9 +42,12 @@ Output: a compact self-assessment table before proceeding to mechanical checks.
 <ExecutionStrategy>
 **BATCH ALL READS.** Use the SDD scan tool for one-shot snapshot, then targeted reads.
 
-1. **One bash call** to get comprehensive snapshot:
-   `~/Developer/gennady/ai/skills/sdd-execute/scripts/sdd scan <project-root>`
-   This emits [HEADER] [TASKS] [TRACKERS] [SPECS] [WARNINGS] [SUMMARY] in a single call — replaces multiple find/grep commands.
+1. **Two bash calls** to get comprehensive snapshot + mechanical findings:
+   - `~/Developer/gennady/ai/skills/sdd-execute/scripts/sdd scan <project-root>`
+     → [HEADER] [TASKS] [TRACKERS] [SPECS] [WARNINGS] [SUMMARY] in one call.
+   - `~/Developer/gennady/ai/skills/sdd-execute/scripts/sdd check <project-root>`
+     → [TASKID] (collisions, orphan @tasks refs) + [TRACKER_SYNC] (ticket Meta.Status vs tracker row).
+     This is the SAME tool sdd-audit uses — do NOT re-implement these greps by hand (Checks 3 & 5b below read its output).
 
 2. **Concurrent reads** of all key files: Portal, scope specs (from SPECS list), trackers with issues (from WARNINGS). Do NOT read module specs initially — only if Check 2 needs them.
 
@@ -52,7 +55,7 @@ Output: a compact self-assessment table before proceeding to mechanical checks.
 
 4. **Do NOT scan code files.** Check 6 samples at most 3 files.
 
-Total: ≤5 tool calls for all 8 checks. Target: <15 seconds.
+Total: ≤6 tool calls for all checks (scan + check + check --files + targeted reads). Target: <15 seconds.
 </ExecutionStrategy>
 
 <Checks>
@@ -66,9 +69,9 @@ Read `specs/README.md`. Verify: scopes table entries match `specs/<scope>/<scope
 
 For each scope spec 9/7: module paths resolve to files. Module spec 1 links to parent. Cross-scope references resolve.
 
-### Check 3 — Tracker Sync (1 grep)
+### Check 3 — Tracker Sync (from `sdd check` [TRACKER_SYNC])
 
-`grep -rn "\[x\] DONE\|\[ \] TODO\|\[~\] IN_PROGRESS\|\[!\] BLOCKED" tasks/README.md tasks/*/README.md`. Compare counts.
+Read the [TRACKER_SYNC] section of `sdd check`. Each row `match=NO` (ticket Meta.Status ≠ tracker row) or `NO_ROW` (ticket has no tracker row) is a FAIL with the Task-ID. `UNPARSEABLE` (old-template ticket without Meta.Status) → INFO, not a fail. Do NOT re-grep counts by hand.
 
 ### Check 4 — DAG Consistency (parse from tracker)
 
@@ -78,9 +81,15 @@ Parse `Dependencies:` from each task ticket planning surface. Topological sort.
 
 From scan [TASKS] output: check `placeholders` column for any task with >0. Flag tasks where placeholders > 0 even if status DONE. Also inspect `warnings` column for `no-execlog-section` or `anchors-mismatch`.
 
-### Check 6 — File Headers (sample 3 files)
+### Check 5b — Task-ID Integrity (from `sdd check` [TASKID])
 
-Pick 3 recently modified .ts files from `git diff --name-only HEAD~3`. Check for `@file:`, `@consumers:`, `@tasks:`.
+Read the [TASKID] section of `sdd check`. `collision` (one Task-ID on ≥2 ticket files) → FAIL (BLOCKER). `orphan` (a code `@tasks: TSK-NN` with no ticket file) → FAIL. Empty section → PASS. Same tool sdd-audit STEP_2_5 uses.
+
+### Check 6 — File Headers (from `sdd check --files`)
+
+Pass recently modified source files to the shared checker instead of sampling by hand:
+`sdd check --files $(git diff --name-only HEAD~3 | grep -E '\.(ts|js|sh|go)$')`.
+Read [HEADERS]: `verdict=PARTIAL` (has some markers, missing `@file` or `@tasks`) or `NONE` on a code file → FAIL. `@consumers` absence alone → MINOR.
 
 ### Check 7 — Test Coverage (1 find)
 
@@ -107,7 +116,8 @@ First: Self-Reflection. Then: Mechanical Checks. Use compact single-line-per-che
 ▸ MECHANICAL
   ✅ Portal          4 scopes, graph ↔ table
   ✅ Spec linking    all modules → parent, cross-scope refs resolve
-  ✅ Tracker sync    dbc 13/13  cli 7/7  vcs 1/1
+  ✅ Tracker sync    dbc 13/13  cli 7/7  vcs 1/1   (sdd check [TRACKER_SYNC])
+  ✅ Task-ID         no collisions, no orphan @tasks   (sdd check [TASKID])
   ✅ DAG             no cycles, all deps satisfied
   ✅ Execution Log   no <YYYY-MM-DD> placeholders in tasks
   ✅ File headers    21 files scanned, all have @file: + @consumers:

package/dist/ai/skills/sdd-execute/scripts/README.md

@@ -13,6 +13,7 @@ All scripts honor the contract: **never produce silent empty output**. On miss,
 ~/Developer/gennady/ai/skills/sdd-execute/scripts/sdd verify <file>...                     # comprehensive gate (typecheck + lint + grep)
 ~/Developer/gennady/ai/skills/sdd-execute/scripts/sdd check-blockers <ticket-file>         # scan Execution Log per AX_BLOCKER_RESOLUTION_TRAIL
 ~/Developer/gennady/ai/skills/sdd-execute/scripts/sdd scan [project-root]                  # one-shot rich snapshot for triage skills
+~/Developer/gennady/ai/skills/sdd-execute/scripts/sdd check [root|--task TSK-NN|--files f...] # deterministic mechanical checks (shared by sdd-check + sdd-audit)
 ```
 
 Single permission rule covers all subcommands:
@@ -37,6 +38,8 @@ Or broader:
 | `verify.sh`          | Three-gate verification: typecheck + gennady DBC lint + forbidden-construct grep                                                                                                                                                                                                                                     |
 | `check-blockers.sh`  | Detect unresolved BLOCKER entries in ticket Execution Log per `AX_BLOCKER_RESOLUTION_TRAIL`                                                                                                                                                                                                                          |
 | `scan.sh`            | Emit comprehensive project snapshot ([HEADER]/[TASKS]/[TRACKERS]/[SPECS]/[WARNINGS]/[SUMMARY]). Designed so triage skills make ONE call instead of many ad-hoc find/grep. Surfaces suspicious states automatically (DONE+placeholders, DONE+active-blocker, anchor mismatch, unparseable Status, broken spec links). |
+| `check.sh`           | Deterministic mechanical checks — [TASKID] (collisions, orphan `@tasks`), [TRACKER_SYNC] (ticket Meta.Status vs tracker row), [HEADERS] (`--files` mode). Single source of mechanical truth shared by `sdd-check` (whole tree) and `sdd-audit` (scoped via `--task`/`--files`). Exit 0 clean / 3 findings / 2 structural / 4 bad-invocation. |
+| `_sdd-lib.sh`        | Shared artifact parsers (status, Task-ID, tracker-row, header flags) sourced by `check.sh`. Not executed directly. `scan.sh` migration to this lib pending.                                                                                                                                                          |
 
 ## Anchor convention (used by `extract`)
 

package/dist/ai/skills/sdd-execute/scripts/_sdd-lib.sh

@@ -0,0 +1,60 @@
+# @file: Shared SDD artifact parsers — sourced by scan.sh / check.sh, never executed directly.
+# @consumers: check.sh (canonical), scan.sh (migration pending).
+# @contract: pure functions of file contents; no stdout side effects beyond the echoed result.
+#
+# Why this lib exists:
+#   - check.sh and scan.sh both parse ticket Meta.Status, Task-ID, tracker rows, file headers.
+#   - One implementation here = no drift between the two SDD tree tools (the whole point of
+#     `sdd check`: a single source of mechanical truth that both sdd-check and sdd-audit consume).
+#
+# macOS bash 3.2 compatible: grep -E / sed -E / awk only. No grep -P, no GNU sed -i.
+
+# Extract Meta.Status flag from a ticket. Echoes: DONE | TODO | IN_PROGRESS | BLOCKED | UNKNOWN
+sdd_lib_status() {
+    local f="$1" line flag
+    line=$(head -60 "$f" 2>/dev/null | grep -m1 -E '^\s*-?\s*\*?\*?Status:\*?\*?\s*\[.\]' || true)
+    [[ -z "$line" ]] && { echo "UNKNOWN"; return; }
+    flag=$(echo "$line" | sed -nE 's/.*\[(.)\].*/\1/p')
+    case "$flag" in
+        x|X) echo "DONE" ;;
+        ' ') echo "TODO" ;;
+        '~') echo "IN_PROGRESS" ;;
+        '!') echo "BLOCKED" ;;
+        *)   echo "UNKNOWN" ;;
+    esac
+}
+
+# Extract Task-ID (TSK-NN) from a ticket Meta. Echoes the ID or empty string.
+sdd_lib_task_id() {
+    local f="$1"
+    head -30 "$f" 2>/dev/null \
+        | grep -m1 -oE 'Task-ID:\*?\*?\s*TSK-[0-9]+' \
+        | grep -oE 'TSK-[0-9]+' || true
+}
+
+# Map a tracker-row status cell (`[x]` DONE etc.) to canonical token for ONE Task-ID.
+# Args: <tracker-file> <TSK-NN>. Echoes DONE|TODO|IN_PROGRESS|BLOCKED|UNKNOWN (UNKNOWN if no row).
+sdd_lib_tracker_status() {
+    local tr="$1" id="$2" row flag
+    # Row form: | [TSK-NN](...) | ... | `[x]` DONE | ... |  (also bare TSK-NN)
+    row=$(grep -m1 -E "\|[[:space:]]*\[?${id}[]\(]" "$tr" 2>/dev/null || true)
+    [[ -z "$row" ]] && { echo "UNKNOWN"; return; }
+    flag=$(echo "$row" | sed -nE 's/.*`?\[(.)\]`?[[:space:]]+(DONE|TODO|IN_PROGRESS|BLOCKED).*/\1/p')
+    case "$flag" in
+        x|X) echo "DONE" ;;
+        ' ') echo "TODO" ;;
+        '~') echo "IN_PROGRESS" ;;
+        '!') echo "BLOCKED" ;;
+        *)   echo "UNKNOWN" ;;
+    esac
+}
+
+# Header-trio presence for a source file. Echoes three space-separated flags: <file> <consumers> <tasks>
+# Each flag is 1 (marker present) or 0 (absent). `@tasks: N/A` counts as present.
+sdd_lib_header_flags() {
+    local f="$1" hf=0 hc=0 ht=0
+    head -20 "$f" 2>/dev/null | grep -qE '@file:'      && hf=1
+    head -20 "$f" 2>/dev/null | grep -qE '@consumers:'  && hc=1
+    head -20 "$f" 2>/dev/null | grep -qE '@tasks:'      && ht=1
+    echo "$hf $hc $ht"
+}