gennady 0.8.2 → 0.8.4

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

package/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"
+}

package/ai/skills/sdd-execute/scripts/check.sh

@@ -0,0 +1,238 @@
+#!/usr/bin/env bash
+# @file: Deterministic SDD mechanical checks shared by sdd-check (whole tree) and sdd-audit (scoped).
+# @consumers: sdd-check skill (whole-tree preflight); sdd-audit directive STEP_2_5 (scoped pre-pass).
+# @contract: AX_BASH_NO_SILENT_EMPTY. Single source of mechanical truth — neither skill re-implements
+#            header presence, Task-ID integrity, or tracker sync. Pure function of files on disk.
+#
+# Three modes:
+#   check.sh [project-root]          — whole tree: TASKID + TRACKER_SYNC (all tickets) + HEADERS (all marker-bearing src)
+#   check.sh --task <TSK-NN> [root]  — one ticket: TASKID (collision/orphan-for-its-refs) + TRACKER_SYNC for that id
+#   check.sh --files <f1> [f2 ...]   — header-trio presence for an explicit file list (audit passes its git-diff scope)
+#
+# Output sections (TSV, machine-readable, stable):
+#   [HEADERS]      — file \t has_file \t has_consumers \t has_tasks \t verdict(OK|PARTIAL|NONE)
+#   [TASKID]       — kind(orphan|collision) \t id \t detail
+#   [TRACKER_SYNC] — task_id \t ticket_status \t tracker_status \t match(YES|NO|NO_ROW)
+#   [SUMMARY]      — key=value totals + findings count
+#
+# Exit codes:
+#   0 — all checks clean (zero findings)
+#   3 — one or more findings (desync / orphan / collision / partial-or-missing header)
+#   2 — structural failure (bad root / not an SDD project)
+#   4 — bad invocation
+
+set -uo pipefail
+
+PROG="check"
+VERSION="1"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=_sdd-lib.sh
+. "$SCRIPT_DIR/_sdd-lib.sh"
+
+# ---------------------------------------------------------------------------
+# Argument parsing → MODE
+# ---------------------------------------------------------------------------
+
+MODE="tree"
+TASK_ID=""
+FILES=()
+ROOT="."
+
+case "${1:-}" in
+    --task)
+        MODE="task"
+        TASK_ID="${2:-}"
+        ROOT="${3:-.}"
+        if [[ -z "$TASK_ID" || ! "$TASK_ID" =~ ^TSK-[0-9]+$ ]]; then
+            cat <<EOF
+[$PROG] BAD_INVOCATION
+  expected: $PROG --task TSK-NN [project-root]
+  got:      $PROG --task '${TASK_ID:-}' ...
+Required action: pass a Task-ID of the form TSK-<number>.
+EOF
+            exit 4
+        fi
+        ;;
+    --files)
+        MODE="files"
+        shift 2>/dev/null || true
+        FILES=("$@")
+        if [[ ${#FILES[@]} -eq 0 ]]; then
+            cat <<EOF
+[$PROG] BAD_INVOCATION
+  expected: $PROG --files <file1> [file2 ...]
+  got:      $PROG --files (no files)
+Required action: pass at least one source file to check headers on.
+EOF
+            exit 4
+        fi
+        ;;
+    --*)
+        cat <<EOF
+[$PROG] BAD_INVOCATION
+  unknown flag: $1
+  expected: $PROG [project-root] | $PROG --task TSK-NN [root] | $PROG --files <files...>
+EOF
+        exit 4
+        ;;
+    *)
+        MODE="tree"
+        ROOT="${1:-.}"
+        ;;
+esac
+
+FINDINGS=0
+
+# ---------------------------------------------------------------------------
+# Mode: --files  → HEADERS only
+# ---------------------------------------------------------------------------
+
+emit_header_row() {
+    local f="$1" flags hf hc ht verdict
+    flags=$(sdd_lib_header_flags "$f")
+    hf=$(echo "$flags" | cut -d' ' -f1)
+    hc=$(echo "$flags" | cut -d' ' -f2)
+    ht=$(echo "$flags" | cut -d' ' -f3)
+    if [[ "$hf" -eq 1 && "$ht" -eq 1 ]]; then
+        verdict="OK"   # @consumers is MINOR; @file + @tasks are the required pair
+    elif [[ "$hf" -eq 0 && "$hc" -eq 0 && "$ht" -eq 0 ]]; then
+        verdict="NONE"
+    else
+        verdict="PARTIAL"; FINDINGS=$((FINDINGS+1))
+    fi
+    printf '%s\t%d\t%d\t%d\t%s\n' "$f" "$hf" "$hc" "$ht" "$verdict"
+}
+
+if [[ "$MODE" == "files" ]]; then
+    printf '# sdd check v%s (mode=files)\n' "$VERSION"
+    printf '\n[HEADERS]\n# file\thas_file\thas_consumers\thas_tasks\tverdict\n'
+    for f in "${FILES[@]}"; do
+        if [[ ! -f "$f" ]]; then
+            printf '%s\t-\t-\t-\tMISSING_FILE\n' "$f"; FINDINGS=$((FINDINGS+1)); continue
+        fi
+        emit_header_row "$f"
+    done
+    printf '\n[SUMMARY]\nmode=files\nfiles_checked=%d\nfindings=%d\n' "${#FILES[@]}" "$FINDINGS"
+    [[ "$FINDINGS" -gt 0 ]] && exit 3 || exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# tree / task modes need an SDD root
+# ---------------------------------------------------------------------------
+
+if [[ ! -d "$ROOT" ]]; then
+    echo "[$PROG] BAD_ROOT: $ROOT is not a directory"; exit 2
+fi
+ROOT_ABS="$(cd "$ROOT" && pwd)"
+if [[ ! -d "$ROOT_ABS/tasks" && ! -d "$ROOT_ABS/specs" ]]; then
+    cat <<EOF
+[$PROG] NOT_AN_SDD_PROJECT
+  root: $ROOT_ABS
+  reason: neither tasks/ nor specs/ found
+Required action: run from an SDD project root, or pass it explicitly.
+EOF
+    exit 2
+fi
+
+printf '# sdd check v%s (mode=%s%s)\n' "$VERSION" "$MODE" "$([[ "$MODE" == task ]] && echo " $TASK_ID")"
+printf 'ROOT=%s\n' "$ROOT_ABS"
+
+TASK_FILES=$(find -L "$ROOT_ABS/tasks" -name '*.task-*.md' -type f 2>/dev/null | sort || true)
+
+# ---------------------------------------------------------------------------
+# [TASKID] — collisions (global) + orphan @tasks references
+# ---------------------------------------------------------------------------
+
+printf '\n[TASKID]\n# kind\tid\tdetail\n'
+
+# Build id → files map to detect collisions (two tickets declaring same Task-ID).
+COLLISION_TMP="$(mktemp -t sdd-check-ids.XXXXXX)"
+trap 'rm -f "$COLLISION_TMP"' EXIT
+while IFS= read -r f; do
+    [[ -z "$f" ]] && continue
+    id=$(sdd_lib_task_id "$f")
+    [[ -z "$id" ]] && continue
+    printf '%s\t%s\n' "$id" "${f#$ROOT_ABS/}" >> "$COLLISION_TMP"
+done <<< "$TASK_FILES"
+
+# Collisions: ids appearing on >1 ticket. In task mode, restrict to TASK_ID.
+while IFS= read -r id; do
+    [[ -z "$id" ]] && continue
+    [[ "$MODE" == "task" && "$id" != "$TASK_ID" ]] && continue
+    files=$(awk -F'\t' -v k="$id" '$1==k {print $2}' "$COLLISION_TMP" | paste -sd',' -)
+    printf 'collision\t%s\t%s\n' "$id" "$files"
+    FINDINGS=$((FINDINGS+1))
+done < <(cut -f1 "$COLLISION_TMP" | sort | uniq -d)
+
+# Orphans: @tasks: TSK-NN in source with no matching ticket file.
+# Whole-tree mode only (task mode trusts its own ticket exists).
+if [[ "$MODE" == "tree" ]]; then
+    known_ids=$(cut -f1 "$COLLISION_TMP" | sort -u)
+    # Collect @tasks references from source files (exclude heavy dirs).
+    refs=$(grep -rhoE '@tasks:[^@]*' "$ROOT_ABS" \
+              --include='*.ts' --include='*.js' --include='*.sh' --include='*.go' \
+              --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=dist \
+              --exclude-dir=worktrees --exclude-dir=.claude 2>/dev/null \
+            | grep -oE 'TSK-[0-9]+' | sort -u || true)
+    while IFS= read -r rid; do
+        [[ -z "$rid" ]] && continue
+        if ! echo "$known_ids" | grep -qx "$rid"; then
+            printf 'orphan\t%s\t@tasks reference with no tasks/**/*.task-*.md\n' "$rid"
+            FINDINGS=$((FINDINGS+1))
+        fi
+    done <<< "$refs"
+fi
+
+# ---------------------------------------------------------------------------
+# [TRACKER_SYNC] — ticket Meta.Status vs tracker-row status
+# ---------------------------------------------------------------------------
+
+printf '\n[TRACKER_SYNC]\n# task_id\tticket_status\ttracker_status\tmatch\n'
+
+sync_one() {
+    local f="$1" id ticket_status scope tracker tracker_status match
+    id=$(sdd_lib_task_id "$f")
+    [[ -z "$id" ]] && return
+    ticket_status=$(sdd_lib_status "$f")
+    # scope = first path segment under tasks/
+    scope=$(echo "${f#$ROOT_ABS/tasks/}" | awk -F/ '{print $1}')
+    tracker="$ROOT_ABS/tasks/$scope/README.md"
+    if [[ ! -f "$tracker" ]]; then
+        printf '%s\t%s\t-\tNO_ROW\n' "$id" "$ticket_status"; FINDINGS=$((FINDINGS+1)); return
+    fi
+    tracker_status=$(sdd_lib_tracker_status "$tracker" "$id")
+    if [[ "$ticket_status" == "UNKNOWN" ]]; then
+        # Old-template ticket lacking a parseable Meta **Status:** — cannot compare.
+        # Not a desync finding (mirrors scan.sh WARN, not ERROR); surface as UNPARSEABLE.
+        match="UNPARSEABLE"
+    elif [[ "$tracker_status" == "UNKNOWN" ]]; then
+        match="NO_ROW"; FINDINGS=$((FINDINGS+1))
+    elif [[ "$tracker_status" == "$ticket_status" ]]; then
+        match="YES"
+    else
+        match="NO"; FINDINGS=$((FINDINGS+1))
+    fi
+    printf '%s\t%s\t%s\t%s\n' "$id" "$ticket_status" "$tracker_status" "$match"
+}
+
+while IFS= read -r f; do
+    [[ -z "$f" ]] && continue
+    if [[ "$MODE" == "task" ]]; then
+        [[ "$(sdd_lib_task_id "$f")" == "$TASK_ID" ]] || continue
+    fi
+    sync_one "$f"
+done <<< "$TASK_FILES"
+
+# [HEADERS] is intentionally NOT run in tree mode: "which files must carry @tasks"
+# is a policy (task-generated vs hand-authored), not a mechanical fact. Header presence
+# is meaningful only against a known in-scope file set — provided by audit via --files.
+
+# ---------------------------------------------------------------------------
+# [SUMMARY]
+# ---------------------------------------------------------------------------
+
+printf '\n[SUMMARY]\nmode=%s\n' "$MODE"
+[[ "$MODE" == "task" ]] && printf 'task=%s\n' "$TASK_ID"
+printf 'findings=%d\n' "$FINDINGS"
+
+[[ "$FINDINGS" -gt 0 ]] && exit 3 || exit 0