gennady 0.8.3 → 0.8.4

package/README.md

@@ -73,6 +73,7 @@ npx gennady commit --apply
 npx gennady cat ./src
 npx gennady cat "./src/**/*.ts" --output=md
 npx gennady cat ./src --plain
+npx gennady cat --url="https://gitlab.com/.../-/merge_requests/123"
 ```
 
 **Опции:**
@@ -81,6 +82,22 @@ npx gennady cat ./src --plain
 - `--plain`: без ANSI-цветов
 - `--exclude`, `-e`: исключить паттерны
 - `--ext`: фильтр по расширениям
+- `--url`: MR/PR URL для удалённого сбора файлов
+
+---
+
+### 🔍 `review`
+
+AI-ревью staged изменений.
+
+```bash
+npx gennady review
+npx gennady review --branch=develop
+```
+
+**Опции:**
+
+- `--branch`, `-b`: target branch для diff (по умолчанию origin/main)
 
 ---
 
@@ -160,7 +177,6 @@ echo '[{"discussionId":"123","body":"✅ Fixed"}]' | \
   npx gennady vcs-reply --project=group/project --iid=123
 
 # Проверка без отправки
-
 echo '[{"discussionId":"123","body":"✅ Fixed"}]' | \
   npx gennady vcs-reply --project=group/project --iid=123 --dry-run
 ```
@@ -179,19 +195,212 @@ echo '[{"discussionId":"123","body":"✅ Fixed"}]' | \
 
 ---
 
+### 🧹 `lint`
+
+Валидация TypeScript-файлов: file-header, anchors, DbC-контракты, invariant-count.
+
+```bash
+npx gennady lint ./src
+npx gennady lint --staged
+npx gennady lint ./src --autofix --verbose
+```
+
+**Опции:**
+
+- `--autofix`: автоисправление DbC-контрактов
+- `--staged`: только staged и untracked `.ts` (взаимоисключающий с путями)
+- `--verbose`, `-v`: debug-логи
+- `--max-invariants`: макс. инвариантов на сущность (по умолчанию 3)
+- `--exclude`: исключить файлы по glob (повторяемый)
+
+---
+
+### 🗯️ `alt-opinion`
+
+Мульти-модельные мнения с опциональным синтезом.
+
+```bash
+# Мнение двух моделей с синтезом
+npx gennady alt-opinion \
+  --model="llmproxy/kimi-k2.6" \
+  --model="llmproxy/glm-5.1" \
+  --synthModel="llmproxy/deepseek-v4-pro" \
+  --file="./spec.md"
+
+# Через stdin
+cat spec.md | npx gennady alt-opinion \
+  --model="llmproxy/gpt-4o" \
+  --model="openrouter/claude-sonnet"
+```
+
+**Опции:**
+
+- `--model`: дескриптор модели `provider/model[::prompt.md]` (повторяемый)
+- `--synthModel`: модель-синтезатор
+- `--file`: путь к входному файлу
+- `--modelPrompt`: промпт для всех моделей
+- `--synthPrompt`: промпт для синтезатора
+- `--strict`: exit 1 при ошибке любой модели
+
+---
+
+### 🔄 `sync`
+
+Синхронизация `ai/directives/` из npm-пакета в текущий проект.
+
+```bash
+npx gennady sync
+npx gennady sync --dry-run
+npx gennady sync ts-patterns typescript --dry-run
+```
+
+**Опции:**
+
+- `--dry-run`: предпросмотр без записи
+
+---
+
+### 🔄 `sync-skills`
+
+Синхронизация SDD-навыков из `ai/skills/` в `.claude/skills/` проекта.
+
+```bash
+npx gennady sync-skills
+npx gennady sync-skills --dry-run
+npx gennady sync-skills sdd-execute
+```
+
+**Опции:**
+
+- `--dry-run`: предпросмотр без записи
+
+---
+
+### 🧭 `orient`
+
+Навигация по проекту: file-header разметка, DBC-контракты, граф зависимостей.
+
+```bash
+npx gennady orient                          # карта проекта
+npx gennady orient --task=TSK-03            # файлы задачи
+npx gennady orient --consumer=DbcTsLinter   # кто потребляет модуль
+npx gennady orient --file=path/to/file.ts   # детальный просмотр
+npx gennady orient --graph                  # граф зависимостей
+npx gennady orient --specs                  # обзор спек
+```
+
+**Опции:**
+
+- `--file`, `--task`, `--consumer`, `--entity`: поиск по атрибутам
+- `--graph`, `--specs`: обзорные режимы
+- `--fuzzy`, `--detail`, `--depth`, `--max-results`: настройки вывода
+
+---
+
+### 📋 `agents-rules`
+
+Выводит инструкцию по `orient` для AI-агентов.
+
+```bash
+npx gennady agents-rules
+```
+
+---
+
+### 🖥️ `remote-console`
+
+Зеркалирование браузерной консоли в локальный stdout.
+
+```bash
+npx gennady remote-console
+npx gennady remote-console --port=8080
+npx gennady remote-console --url="https://example.com"
+```
+
+**Опции:**
+
+- `--port`, `-p`: порт (по умолчанию 43001)
+- `--host`: хост (по умолчанию localhost)
+- `--url`: URL страницы для открытия с активацией
+
+---
+
+Подробнее: [`cli/cmd/README.md`](cli/cmd/README.md).
+
+---
+
 ## 🛠️ Типовые сценарии
 
-### 1. Верификация MR
+### 1. Сделать коммит
+
+```bash
+npx gennady commit
+npx gennady commit --mode=oneline --apply --task=TSK-42
+```
+
+### 2. Проверить качество кода
+
+```bash
+npx gennady lint ./src
+npx gennady lint --staged --autofix
+```
+
+### 3. Навигация по проекту
+
+```bash
+npx gennady orient                    # карта
+npx gennady orient --task=TSK-03      # файлы задачи
+npx gennady orient --graph            # граф зависимостей
+npx gennady agents-rules              # инструкция для AGENTS.md
+```
+
+### 4. Верификация MR
 
 ```bash
 export GITLAB_PERSONAL_TOKEN="<token>"
 npx gennady review-verify --ref=group/project!123
 ```
 
-### 2. Разрешение merge-конфликтов
+### 5. AI-ревью изменений
+
+```bash
+npx gennady review
+npx gennady review --branch=develop
+```
+
+### 6. Разрешение merge-конфликтов
 
 ```bash
 git merge feature/some-branch
 # если есть конфликты
 npx gennady resolve-conflicts
 ```
+
+### 7. Собрать файлы для AI
+
+```bash
+npx gennady cat "./src/**/*.ts" --output=md --plain | pbcopy
+```
+
+### 8. Синхронизация директив и навыков
+
+```bash
+npx gennady sync
+npx gennady sync-skills
+```
+
+### 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. Зеркалирование консоли браузера
+
+```bash
+npx gennady remote-console
+```

package/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/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/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/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/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/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`)