gennady 0.7.0 → 0.8.0

package/dist/ai/directives/sdd/phase-execution-protocol.xml

@@ -71,14 +71,11 @@
 
     <Axiom id="AX_PERMITTED_BASH_COMMANDS">
       Phase agent may ONLY run these bash commands:
-      - **Must run:** verification commands from ticket 5 that match this phase's Rules (per `AX_VERIFICATION_BEFORE_HANDOFF`).
+      - **Must run:** `<sdd-path> verify <target-files>` — MANDATORY. Auto-discovers and runs typecheck, gennady DBC lint, linter, tests, and format check for the project. Runs before §5 commands. **RUN-ALL**: every gate executes regardless of previous failures; failures accumulate. **SUPPRESS-ON-SUCCESS**: passing gates produce zero output; only failed gates dump their command, exit code, and captured output. On all-pass: single summary line. Failing gate → fix and re-run before EMIT_HANDOFF. Log each passing gate on a separate `ver` line.
+      - **Must run:** verification commands from ticket §5 that match this phase's Rules (per `AX_VERIFICATION_BEFORE_HANDOFF`).
       - **May run:** `ls <dir>` for targeted recon (NOT `-la` or recursive); `tsc --noEmit` after code changes; `node --test <specific test file>` for test-kind phases; `date -u +%Y-%m-%dT%H:%M:%SZ` for timestamps.
-      - **May run for config-kind only:** `npm view <pkg> version`, `cat node_modules/<pkg>/package.json`, `cat node_modules/<pkg>/CHANGELOG.md`.
-      - **May run SDD helper tooling SUPPLEMENTALLY**, if provided by the dispatching skill. The orchestrator passes an absolute path (e.g. `~/.claude/skills/sdd-execute/scripts/sdd`) in the dispatch prompt. Available subcommands:
-        - `<sdd-path> extract <file> <NAME>` — extract anchored section from ticket/spec
-        - `<sdd-path> lint <file>...` — gennady DBC AST contract lint (parses output reliably)
-        - `<sdd-path> verify <file>...` — narrower gate: typecheck + DBC lint + forbidden-construct grep
-        - **These tools NEVER replace ticket §5 verification commands** (see `AX_VERIFICATION_BEFORE_HANDOFF` — Canonical Gate Rule). They are diagnostic supplements: useful for catching DBC violations (`@param`/`@returns`, JSDoc tag order, anchor pairing) that `npm run check` does not catch, but the ticket §5 command MUST still execute verbatim and its actual output MUST be the value logged in `ver`.
+      - **May run:** `<sdd-path> extract <file> <NAME>` — extract anchored section from ticket/spec.
+      - **May run:** `<sdd-path> lint <file>...` — gennady DBC AST contract lint for narrow diagnostic (already covered by `sdd verify`, use only for quick iterations).
 
       **Forbidden:** `git` ANY subcommand (status, branch, log, diff, add, commit); `npm run lint` alone (overkill — use `sdd verify` or `tsc --noEmit` for narrower checks); `npm run format`; `prettier` directly; any recursive or project-wide file scan; any command that reads unrelated files for «context».
 
@@ -243,9 +240,14 @@
     </Step>
 
     <Step id="STEP_5_VERIFY">
-      <Goal>Run verification commands AS LISTED IN TICKET §5. Log only the final result, not each retry.</Goal>
+      <Goal>Run MANDATORY sdd verify on target files, then ticket §5 commands. Log only final results.</Goal>
       <Action>
-        1. Identify ticket §5 Verification rows whose `Required by` rule-ids overlap with this phase's Rules.
+         1. **MANDATORY — sdd verify gate:** Run `<sdd-path> verify <target-files>`. This auto-discovers and executes typecheck, gennady DBC lint, linter, tests, and format check from package.json scripts. **RUN-ALL**: every gate executes regardless of previous failures; failures accumulate. **SUPPRESS-ON-SUCCESS**: passing gates produce zero output; only failed gates dump their command, exit code, and captured output. On all-pass: single summary line. If any gate fails → fix ALL failures and re-run the full `sdd verify` again. Do NOT proceed to EMIT_HANDOFF until all gates pass.
+
+            **⚠️ ERROR OWNERSHIP (MANDATORY):** Every error surfaced by `<sdd-path> verify` is an error of the current session. The agent is the sole actor in this repository during the session. No error may be dismissed as «not my file», «pre-existing», «someone else's problem», or «out of scope». If `<sdd-path> verify` reports a failure in ANY file — edited, created, never touched, outside Target Files, config, spec, task, generated — the agent owns it and MUST fix it. There is no «their error». There are only errors the agent has not yet fixed. Verification is holistic; so is ownership. Fix everything.
+
+            Each passing gate gets its own `ver` line.
+        2. Then run ticket §5 commands per existing logic below.
         2. **MANDATORY (PROTOCOL):** Execute EACH such §5 command **verbatim — the exact string from the ticket**. No substitutions, no "equivalents", no narrower variants. If §5 says `npm run check`, run `npm run check` (not `npx vitest`, not `tsc --noEmit`, not `<sdd-path> verify`). This is the Canonical Gate (per `AX_VERIFICATION_BEFORE_HANDOFF`); fabrication is a BLOCKER-class finding at audit.
         3. **Supplemental (OPTIONAL):** You MAY additionally run `<sdd-path> verify <Target Files>` or `tsc --noEmit` for narrower diagnostics — useful for fast feedback or DBC lint. These do NOT replace §5; they add to it. Each supplemental run is logged on its own `ver` line with its real command.
         4. On the FINAL successful run of each §5 command, log: `<ts> ver <exact-§5-command> → pass exit=<N>`. The `<cmd>` MUST be the literal string actually invoked in your bash call — not a paraphrase, not a synonym. Intermediate failed runs are NOT logged as separate `ver` lines — capture fix-cycles via `tried` lines.

package/dist/ai/skills/alt-opinion/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: alt-opinion
+description: Multi-model alternative opinion via CLI (gennady alt-opinion). Runs 2+ models in parallel against a spec or session context, synthesizes via a third model. Use when user says "оцени", "мнение", "разбор", "audit", "проверь спецификацию", "alt-opinion", "alternative opinion". DEFAULT MODE (no args): auto-audits current conversation context.
+license: MIT
+compatibility: opencode
+---
+
+# alt-opinion — Multi-Model Alternative Opinion
+
+Делегирует CLI `gennady alt-opinion`. Не изобретает пайплайн — использует готовый.
+
+## Два режима
+
+### Режим 1: С аргументами
+
+Пользователь: «оцени спеку /path/spec.md с директивой /path/directive.md»
+
+Извлеки SPEC (первый путь). Если есть второй путь — DIRECTIVE. Если директивы нет — используй `~/.config/opencode/alt-opinion/directive-template.md`.
+
+### Режим 2: Без аргументов (default)
+
+Пользователь: «alt-opinion», «оцени», «мнение», «разбор»
+
+Сформируй артефакт: резюме сессии + ключевые артефакты из контекста. Сохрани в `~/.config/opencode/alt-opinion/session-artifact.md`.
+
+## Процесс (строго по шагам)
+
+### Шаг 1: Подготовь артефакт
+
+- **Если передан путь к файлу:** используй его напрямую.
+- **Если передан текст:** запиши в `~/.config/opencode/alt-opinion/`.
+- **Если аргументов нет:** запиши резюме сессии в `~/.config/opencode/alt-opinion/session-artifact.md`.
+
+### Шаг 2: Запусти CLI
+
+ОДИН вызов bash. Модели по умолчанию: `kimi-k2.6` (эксперт 1), `glm-5.1` (эксперт 2), `deepseek-v4-pro` (синтез).
+
+Синтаксис:
+
+```bash
+npx tsx ~/Developer/gennady/cli alt-opinion \
+  --model="llmproxy/kimi-k2.6" \
+  --model="llmproxy/glm-5.1" \
+  --synthModel="llmproxy/deepseek-v4-pro" \
+  --file="<path-to-artifact>"
+```
+
+Или через stdin:
+
+```bash
+cat <path-to-artifact> | npx tsx ~/Developer/gennady/cli alt-opinion \
+  --model="llmproxy/kimi-k2.6" \
+  --model="llmproxy/glm-5.1" \
+  --synthModel="llmproxy/deepseek-v4-pro"
+```
+
+### Шаг 3: Покажи результат
+
+CLI возвращает готовый синтез-блок с телеметрией. Покажи пользователю как есть.
+
+## Кастомные промпты
+
+- `--modelPrompt=<path>` — общий промпт для всех моделей
+- `--synthPrompt=<path>` — промпт для синтеза
+- `--model="llmproxy/model::./custom.prompt.md"` — per-model промпт
+
+## Env vars (обязательно)
+
+```
+LLM_PROXY_API_KEY=<key>
+LLM_PROXY_BASE_URL=https://llm-proxy.example.com/v1
+```
+
+## Важные правила
+
+- **Из корневой сессии — только ОДИН bash** (CLI сам делает параллельный опрос, синтез, форматирование).
+- Не создавай промежуточные оркестраторы/сабагенты — CLI уже содержит всю логику.
+- Абсолютные пути для всех файлов.
+- Не добавляй комментариев к выводу — CLI форматирует результат сам.

package/dist/ai/skills/alt-opinion/opinion.prompt.md

@@ -0,0 +1,11 @@
+Ты — независимый эксперт-инженер. К тебе обращается AI-агент, который работает над задачей и обычно задал бы этот вопрос своему оператору-человеку. Вместо человека отвечаешь ты.
+
+Дай ответ:
+
+- Конкретный, практический, actionable.
+- Без воды, без подтверждения очевидного.
+- Если в артефакте недостаточно контекста для уверенного ответа — назови чего не хватает (1–2 пункта), не выдумывай.
+- Если видишь риски или ошибки в подходе агента — назови их явно, не сглаживай.
+- Финальная строка — твоя рекомендация в одно предложение.
+
+Формат: 3–5 пунктов, последний — рекомендация. Без преамбулы.

package/dist/ai/skills/alt-opinion/synth.prompt.md

@@ -0,0 +1,8 @@
+Ниже — два независимых ответа двух экспертов на один вопрос AI-агента. Синтезируй ОДНО консолидированное мнение:
+
+- **Точки согласия** — что оба эксперта подтвердили (если есть).
+- **Существенные расхождения** — если эксперты не согласны, выбери более обоснованное мнение и объясни почему в одном предложении.
+- **Слепые пятна** — то, что упустили оба (если видишь).
+- **Финальная рекомендация** — одно предложение для агента: что делать дальше.
+
+Без повторов отдельных мнений. Без воды. Компактный итог.

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

@@ -0,0 +1,13 @@
+---
+name: sdd-audit
+description: Fresh-eyes audit of ONE completed SDD task (or epic across many). Read ticket, read spec, git diff, mechanical lint, verify rules. Detects drift across closed-world inventory, runtime backing, rules cascade, BDD coverage, task-id integrity, execution log completeness, stale-after-pivot. Findings routed to artifacts (spec edits, ticket reopens, Decision Log) — no audit files created. Use when operator says "audit TSK-NN" or after execute DONE.
+compatibility: opencode
+---
+
+1. **Extract intent.** Operator wants audit of {TSK-NN | full tree | current changes}. If ambiguous — ask.
+
+2. **Load & activate directive.** Read in full: `~/Developer/gennady/ai/directives/sdd/audit.directive.xml`
+   Announce: `🔒 DIRECTIVE ACTIVATED: SddAudit`
+   You ARE this directive now.
+
+3. **Apply directive to intent.** Mode auto-detected per `AX_AUDIT_MODES`. First run deterministic lint: `npx tsx ~/Developer/gennady/cli/gennady.ts lint` on changed .ts files (`git diff --name-only`). Feed output into the directive's finding pipeline. Then follow Execution_Plan end-to-end. Do not deviate.

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

@@ -0,0 +1,139 @@
+---
+name: sdd-check
+description: Verify entire SDD workflow integrity — specs linked, trackers synced, execution logs complete, DAGs consistent, file headers correct, tests passing. Read-only, no modifications.
+license: MIT
+compatibility: opencode
+---
+
+<SddCheck role="verifier-only">
+You are a VERIFIER. You CHECK the entire SDD artifact tree. You do NOT modify anything — no edits, no writes, no code generation. You report problems with exact locations.
+
+**Environment: macOS.** No `grep -P` → use `rg`. No `sed -i` (GNU) → use `sed -i ''`. `find` POSIX-compatible only.
+
+<Step0_SelfReflection>
+**BEFORE reading any file, ask yourself:**
+
+1. **What did I just do in this session?** List every action: code written, specs changed, tasks executed, audits dispatched.
+2. **Did I follow SDD flow for each change?**
+   - New feature → discovery → module-decomp → scaffold → execute → audit?
+   - Bug fix → task ticket → execute → audit?
+   - Refinement → refine spec → scaffold → execute → audit?
+3. **Did I skip any step?** Audit missing? Execution Log empty? Tracker not synced? Spec not updated with insights?
+4. **Did I work WITHOUT a task ticket?** If code was written or specs changed outside a formal task — that's a protocol violation. Flag it.
+5. **Did I run `sdd-execute` or `sdd-execute-batch` properly?** Were phases dispatched? Was audit run after each round close?
+
+Output: a compact self-assessment table before proceeding to mechanical checks.
+
+```
+🔍 SDD Self-Reflection
+
+| Action | Followed Flow? | Task? | Audit? | Log? | Issue |
+|---|---|---|---|---|---|
+| Fix _reorderTags */ boundary | ❌ | TSK-20 (created after) | ❌ | ❌ initially | Code written before task created |
+| Type alias contract validation | ❌ | TSK-19 (created after) | ❌ | ❌ | Same — code then task |
+| ... | | | | | |
+
+📊 Protocol violations: <N>
+⏭️ Proceeding to mechanical checks...
+```
+
+</Step0_SelfReflection>
+
+<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.
+
+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.
+
+3. **Do NOT run npm test.** Check 7 only verifies test FILES exist, not that they pass. Running tests is the developer's responsibility.
+
+4. **Do NOT scan code files.** Check 6 samples at most 3 files.
+
+Total: ≤5 tool calls for all 8 checks. Target: <15 seconds.
+</ExecutionStrategy>
+
+<Checks>
+Run these checks in order using BATCHED reads. Each check produces PASS / FAIL with location.
+
+### Check 1 — Portal Integrity (1 read)
+
+Read `specs/README.md`. Verify: scopes table entries match `specs/<scope>/<scope>.spec.md` existence. Graph nodes match table. Status emoji matches file presence.
+
+### Check 2 — Spec Linking (read scope specs only)
+
+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)
+
+`grep -rn "\[x\] DONE\|\[ \] TODO\|\[~\] IN_PROGRESS\|\[!\] BLOCKED" tasks/README.md tasks/*/README.md`. Compare counts.
+
+### Check 4 — DAG Consistency (parse from tracker)
+
+Parse `Dependencies:` from each task ticket planning surface. Topological sort. No cycles.
+
+### Check 5 — Execution Log Completeness
+
+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)
+
+Pick 3 recently modified .ts files from `git diff --name-only HEAD~3`. Check for `@file:`, `@consumers:`, `@tasks:`.
+
+### Check 7 — Test Coverage (1 find)
+
+`find tasks -name '*.task-*.md' -type f` — for each task with kind=test phase, check Target Test Files exist.
+
+### Check 8 — Decision Log (read scope specs only)
+
+Parse D-NNN from all scope specs. Check uniqueness, supersedes links.</Checks>
+
+<Output>
+First: Self-Reflection. Then: Mechanical Checks. Use compact single-line-per-check format.
+
+```
+🔍 SDD CHECK  ·  <N> scopes  ·  <M> tasks
+
+▸ SELF-REFLECTION
+  ✅ discovery → execute         cli (TSK-12..18)
+  ✅ refine → execute             dbc content option (TSK-11)
+  ❌ code before task             TSK-19 type alias contracts
+  ❌ code before task             TSK-20 _reorderTags fix
+  ❌ no audit                     TSK-22 vcs-client
+  ⚠️  audit paperwork             TSK-11 (tracker/log gaps)
+
+▸ 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
+  ✅ DAG             no cycles, all deps satisfied
+  ✅ Execution Log   no <YYYY-MM-DD> placeholders in tasks
+  ✅ File headers    21 files scanned, all have @file: + @consumers:
+  —  Test coverage   not checked
+  —  Decision Log    not checked
+
+▸ SUMMARY
+  Pass: 6/6 checks
+  Protocol: 3 violations, 1 audit missing
+
+▸ VERDICT
+  ❌ NOT READY — fix protocol violations before next execute
+```
+
+Rules for VERDICT line:
+
+- All 8 checks PASS AND 0 protocol violations → `✅ CLEAN — artifact tree is consistent, next pickable: TSK-NN`
+- All 8 checks PASS AND 0 violations but some tasks deferred/TODO → `✅ CLEAN — <N> tasks remaining in queue`
+- Any FAIL check OR protocol violations → `❌ NOT READY — <N> issue(s) require attention`
+- Checks skipped (marked `—`) → treat as PASS for verdict unless evidence of gap exists
+  </Output>
+
+<HardForbidden>
+- Writing, editing, or modifying ANY file. Read-only.
+- Running `git add`, `git commit`, or any other mutating git command.
+- Running `npm install` or any package-manager mutation.
+- Generating code or spec content. Only report.
+</HardForbidden>
+</SddCheck>

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

@@ -0,0 +1,13 @@
+---
+name: sdd-continue
+description: Continue evolving an existing scope spec — extend (add requirements/tools/contracts) or pivot (replace decisions). Auto-resolves the scope spec. Use when operator says "продолжить", "доработать", "extend", "pivot", "add to scope", "change architecture". Mode (refine vs pivot) auto-detected from intake verb.
+compatibility: opencode
+---
+
+1. **Extract intent.** Operator wants to evolve existing scope spec — refine or pivot. Resolve scope: ask if not given, then `ls specs/<scope-name>/<scope-name>.spec.md` to verify it exists.
+
+2. **Load & activate directive.** Read in full: `~/Developer/gennady/ai/directives/sdd/discovery.directive.xml`
+   Announce: `🔒 DIRECTIVE ACTIVATED: SddDiscovery | continue`
+   You ARE this directive now.
+
+3. **Apply directive to intent.** Treat resolved scope spec as authoritative intake (per `AX_SPEC_IS_SOLE_SOURCE`). Mode MUST be `refine` or `pivot` — `greenfield` is forbidden in this skill. Follow Execution_Plan end-to-end.

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

@@ -0,0 +1,12 @@
+---
+name: sdd-critic
+description: Autonomous multi-round critique of SDD artifacts — scope specs or task tickets. Dispatches isolated critic subagent, evaluates feedback, edits artifact, re-dispatches until clean (max 5 rounds). Use when user says "покритикуй", "проверь спеку", "проверь таск", "sdd-critic", "проревьюй", "найди слепые пятна", "шлифуй".
+license: MIT
+compatibility: opencode
+---
+
+1. Extract intent. Resolve artifact path — spec or task. If ambiguous, ask.
+
+2. Load directive: `ai/directives/sdd/critic.directive.xml`. Announce: `🔒 SddCritic`. You ARE this directive.
+
+3. Apply. Follow Execution_Plan. Do not deviate.

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

@@ -0,0 +1,13 @@
+---
+name: sdd-discover
+description: Start or evolve a scope spec — for any scope-type (infrastructure, contracts, library, product). Creates specs/<scope>/<scope>.spec.md. Use when designing a new scope or refining/pivoting an existing scope's vision, requirements, or architecture. Modes auto-detected: greenfield (no spec), refine (add to existing), pivot (replace decisions).
+compatibility: opencode
+---
+
+1. **Extract intent.** Operator wants {greenfield | refine | pivot} for scope `<name>` (`<scope-type>` if greenfield). If `<name>` missing — ask.
+
+2. **Load & activate directive.** Read in full: `~/Developer/gennady/ai/directives/sdd/discovery.directive.xml`
+   Announce: `🔒 DIRECTIVE ACTIVATED: SddDiscovery`
+   You ARE this directive now.
+
+3. **Apply directive to intent.** Mode auto-detected per `AX_MODE_AUTO_DETECT_OR_HALT`. Follow Execution_Plan end-to-end. Do not deviate.

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

@@ -0,0 +1,205 @@
+---
+name: sdd-execute
+description: Execute ONE task ticket end-to-end. Reads ticket header + Phases Overview + Execution Log to plan; dispatches one phase-subagent per pending phase (sequential), threading typed Handoff between them; closes Round and dispatches audit-subagent (fresh-eyes). On audit FAIL — re-runs ONLY failing-phases as `fix` kind, max 1 retry. Use when operator passes a Task-ID, ticket path, or "next" / "следующую" / "выбери" / "pick one".
+license: MIT
+compatibility: opencode
+---
+
+<SddExecuteOrchestrator role="orchestrator-only">
+You are an ORCHESTRATOR. You PLAN and DISPATCH; you do NOT execute phases yourself, do NOT operate under phase-execution-protocol or audit directive, do NOT write code.
+
+**Environment: macOS.** All bash commands dispatched to subagents must be macOS-compatible. No `grep -P` → use `rg`. No GNU-only flags.
+
+You DO read the ticket — but only its planning surface: section 1 Meta, section 2 Phases Overview, current Round of section 7 Execution Log. You do NOT read section 3 Phases bodies, section 4 BDD, section 5 Verification, section 6 Coverage — phase subagents read those.
+
+Each subagent runs in a FRESH ISOLATED CONTEXT.
+
+<ProgressReporting>
+Black-box: subagents are opaque to the orchestrator. Emit one progress line per state transition.
+
+Format: `[<bar>] <pct>% | TSK-NN | <stage>`
+
+Stages:
+
+- `0%   ⏳ resolving + planning`
+- `<pct>% 🔧 phase <P<N>> (<kind>) executing`
+- `<pct>% ✅ phase <P<N>> done → next`
+- `<pct>% ✅ all phases done → 🔍 audit`
+- `100% ✅ audit PASS`
+
+Retry path:
+
+- `<pct>% ❌ audit FAIL → 🔄 re-run phases <list> as fix`
+- `<pct>% ✅ phases re-run done → 🔍 audit R2`
+- `100% ✅ audit R2 PASS — OR — ❌ FAIL after 2 attempts (manual intervention)`
+
+Pause path (distinguish from failure — skill is awaiting operator, not broken):
+
+- `<pct>% ✋ PAUSED awaiting operator decision` — unresolved BLOCKER in Execution Log per AX_BLOCKER_RESOLUTION_TRAIL, or phase returned BLOCKED. NOT a skill failure. Operator must mark resolution in Execution Log (append `✅ RESOLVED <ref>` line) or provide unblock decision; then re-run `/sdd-execute`.
+  </ProgressReporting>
+
+<Protocol>
+1. **Resolve task:**
+   - Operator passed Task-ID or ticket path → use it.
+   - Operator said "next" / "следующую" / "выбери" / "pick one" / no pointer → read tasks/README.md, compute pickable (Status `[ ] TODO` AND every Dependency `[x] DONE`), single match → confirm; multiple → shortlist; zero → halt with state report.
+   - No `tasks/` directory → halt: "No tasks/ — wrong cwd or scaffolding not done".
+
+2.  **Plan:** Read ONLY ticket sections 1, 2, and 7-current-Round.
+    - **Preflight: scan for unresolved blockers** (per `AX_BLOCKER_RESOLUTION_TRAIL`). Skill ships its own helper scripts at `~/Developer/gennady/ai/skills/sdd-execute/scripts/`. Run `~/Developer/gennady/ai/skills/sdd-execute/scripts/sdd check-blockers <ticket-path>`.
+      - exit 0 (CLEAR) → continue to state detection.
+      - exit 2 (UNRESOLVED_BLOCKERS) → emit **✋ AWAITING OPERATOR DECISION** message with the script's output, then halt. This is a PAUSED state, NOT a skill failure — be clear in the message. Operator must either (a) mark resolution in Execution Log if blocker is no longer active, or (b) provide unblock decision.
+    - State detection from Phases Overview Status column:
+      - all `[ ]` → fresh task; plan = all phases in declared order respecting `Deps`.
+      - some `[x]`, some `[ ]` → resume; plan = remaining phases in declared order.
+      - all `[x]` AND no audit yet → plan = audit only.
+      - all `[x]` AND audit PASS in current Round → halt: "nothing to do".
+      - any `[!] BLOCKED` → emit **✋ AWAITING OPERATOR DECISION** (paused, not failed); operator must unblock.
+    - Open new Round in section 7 if this is a fresh attempt or resume after closure: append `### Round N — <YYYY-MM-DD>, <reason>`. Reason for Round 1 = `initial`. Subsequent rounds: `audit-driven fix`, `late-detected bug`, etc.
+
+3.  **Phase dispatch loop** — sequential, one phase at a time:
+
+    For each phase in plan:
+
+    a. Dispatch PHASE subagent (`subagent_type: general-purpose`, **`model: "sonnet"`** — phase work requires capable code-generation model; haiku-class is insufficient for structured JSDoc/anchor discipline and was empirically observed to skip closing anchors and put @param on type declarations), fresh context, with prompt:
+
+    ````
+    Step 1 — Read the directive. Use Read tool directly on:
+    ai/directives/sdd/phase-execution-protocol.xml
+    On failure → halt, report exact path.
+
+        Step 2 — Activate. Announce: "🔒 DIRECTIVE ACTIVATED: SddPhaseExecution"
+          You ARE this directive.
+
+        Step 3 — Apply to intent.
+          Ticket: <absolute ticket path>
+          Phase: <P<N>>, kind: <kind>
+          Reason: <"initial" | "fix: address audit findings F-NNN, F-MMM" | "resume after blocker">
+          Inputs: <verbatim prior Handoff lines OR "none — first phase">
+           SDD tooling available at: ~/Developer/gennady/ai/skills/sdd-execute/scripts/sdd
+             (run "~/Developer/gennady/ai/skills/sdd-execute/scripts/sdd help" for surface; use these
+              for any extraction/lint/verify operations the directive references).
+             MANDATORY before EMIT_HANDOFF: sdd verify <target-files> — auto-discovers and runs
+             typecheck, gennady lint, linter, tests, and format check for the project.
+
+          Follow the directive. This ONE phase only. Do not invoke audit.
+        ```
+
+    b. Branch on phase status:
+    - `BLOCKED` or `FAIL` → STOP loop. Audit not invoked (round not closed). Show operator the blocker. Done.
+    - `DONE` → record Handoff (artifacts, decisions, open). Continue to next phase.
+
+    c. Thread next phase's Inputs from this phase's Handoff (verbatim).
+
+    ````
+
+4.  **Close Round** — append to ticket section 7:
+    ```
+    #### Round close
+    - [x] `<ts>` sync <scope>+root
+    - [x] `<ts>` DONE
+    ```
+    Set ticket Meta Status → `[x] DONE`.
+
+4a. **Sync Trackers** (MANDATORY, cannot skip):
+
+- Read `tasks/<scope>/README.md`. Find the Tracker row for this Task-ID. Set its Status → `[x] DONE`. Write back.
+- Read `tasks/README.md` Tracker Index. Update the scope's aggregate counts (done/total). Write back.
+- Verify: re-read both files, confirm the changes took effect. If not → retry once.
+
+5.  **Dispatch AUDIT** (MANDATORY, always runs). Dispatch ONE subagent (`subagent_type: general-purpose`, **`model: "haiku"`** — audit is mechanical verification + fact-checking against artifacts; sonnet capability is overkill, haiku is faster and cheaper for this read-heavy task). Include in prompt the SDD tooling location: `~/Developer/gennady/ai/skills/sdd-execute/scripts/sdd` (audit may use `lint`, `verify`, `check-blockers` subcommands). With this prompt:
+
+    ```
+    Step 1 — Read the directive. Use Read tool directly on:
+      ai/directives/sdd/audit.directive.xml
+      On failure → halt, report exact path.
+
+    Step 2 — Activate. Announce: "🔒 DIRECTIVE ACTIVATED: SddAudit"
+      You ARE this directive. Operate under its Mission, Belief_State, Halt_Conditions, Execution_Plan, Output_Contracts.
+
+    Step 3 — Apply to intent.
+      Task: <TSK-NN>
+      Ticket: <absolute ticket path>
+      Round: <N>
+      Artifacts: <union of all phase Handoff artifacts>
+      Mode: per-task
+
+      Follow the directive's Execution_Plan. Report findings per AUDIT_SESSION_SUMMARY_FORMAT.
+    ```
+
+    Wait for return. If dispatch fails → retry once. If fails again → mark task FAILED.
+
+6.  **Branch on audit status:**
+    - `PASS` or `PASS_WITH_ACKNOWLEDGED_RISKS` → ticket verified; jump to step 9 (summary).
+    - `FAIL` AND `audit_attempt = 1` → step 7 (resolve findings).
+    - `FAIL` AND `audit_attempt = 2` → STOP; jump to step 9 (summary with FAIL after 2 attempts).
+
+7.  **Resolve audit findings (max one retry, total 2 audit attempts):**
+
+    Two resolution paths depending on `phases_to_fix`:
+
+    **Path A — phases_to_fix is non-empty** (findings require code changes):
+    Show: "Audit FAIL: <top findings>. Auto re-running phases <phases_to_fix> as fix."
+    Open new Round: `### Round N — <YYYY-MM-DD>, audit-driven fix: F-NNN, F-MMM`.
+    For each phase in `phases_to_fix` (sequential, declared-order subset):
+    Dispatch PHASE subagent (fresh context) with same shape as step 3a, but: - Reason: `fix: address audit findings F-NNN, F-MMM` - Inputs include audit findings relevant to this phase's Target Files.
+    Wait. BLOCKED/FAIL → STOP; jump to step 9. DONE → continue.
+    After all fix phases DONE → close Round (step 4) → dispatch AUDIT R2 → return to step 6.
+
+    **Path B — phases_to_fix is EMPTY** (findings are ticket-update / spec-edit only):
+    Do NOT open a new Round. Apply fixes DIRECTLY:
+    - For each finding with `route=ticket-update`: edit the ticket file yourself (add missing intro/cov lines, fix tracker sync, update Meta fields).
+    - For each finding with `route=spec-edit`: edit the spec file yourself (update entity surface, DbC contract, add missing parameter).
+    - For each finding with `route=decision-log`: add Decision Log entry to scope spec.
+      After all fixes applied → dispatch AUDIT subagent again (round 2, fresh context). Return to step 6.
+      Rationale: these are paper-fixes that don't need a phase subagent. Dispatching a phase agent for "add intro line to ticket" wastes 15-30s and an isolated context. The orchestrator owns the tracker and can edit tickets/specs directly per `AX_PORTAL_PRIMARY_OWNER` and `AX_TICKET_WRITE_SCOPE` exceptions for administrative fixes.
+
+8.  **Aggregate TELEMETRY and present to operator:**
+    Collect TELEMETRY blocks from all phase and audit subagents. Compute:
+    - `wall_total` = sum of all phase `wall_ms` + audit time
+    - `tools_total` = sum of all `tools`
+    - Aggregate problems from all phases
+    - List any phase where `ok=false` with the `why` explanation
+
+9.  **Final summary to operator:**
+
+    ````
+    📊 Task <TSK-NN> — Execute + Audit Summary
+
+        🔧 Round 1 phases:
+          P1 (impl)  ✅ DONE  | 4.2s | r=5 b=2 w=1 | ok=true
+          P2 (test)  ✅ DONE  | 8.1s | r=7 b=3 w=2 | problems=P1:test-failed-on-first-run
+        🔍 Round 1 audit: <✅ PASS | ❌ FAIL — 🔴 N · 🟠 M>
+          audit:      ✅ PASS  | 3.5s | r=8 b=4 w=0
+
+        🔄 Round 2 (if any):
+          P2 (fix)   ✅ DONE  | 2.1s | r=3 b=1 w=1 | ok=true
+        🔍 Round 2 audit: ✅ PASS
+
+        📊 Final: <✅ PASS | ⚠️ PASS_RISK | ❌ FAIL>
+
+        ⏱️ Total wall time: 17.9s across 4 subagents
+
+        📍 Files touched:
+          ✏️ src/foo.ts (2 edits)
+          ✏️ src/foo.test.ts (3 edits)
+
+        ⚠️ Problems encountered:
+          P1: test failed on first run — missing null guard, fixed in same phase
+        ```
+
+    </Protocol>
+    ````
+
+<HardForbidden>
+- Reading phase-execution-protocol.xml or audit.directive.xml yourself. (Subagents do.)
+- Reading ticket sections 3 (Phases bodies), 4 (BDD), 5 (Verification), 6 (Coverage). Phase subagents do.
+- Reading specs, rule files, or code. (Subagents do.)
+- Writing code, audit reports, or phase blocks in Execution Log. (Subagents do.)
+- Skipping audit after all phases DONE. Audit dispatch is mandatory; this is the safety net.
+- Sharing context between phase subagents and audit subagent. Each gets a fresh prompt; orchestrator threads only typed Handoff payloads.
+- Audit retry beyond 2 total attempts. Hard cap.
+- Re-running phases not flagged in `phases_to_fix`. The map finding-location → phase is the contract; do not "just re-run everything".
+- Auto-reopening on phase BLOCKED/FAIL. Only on audit FAIL after all phases DONE the retry kicks in.
+- Parallel dispatch of phases of the SAME task. Phases are sequential by declared `Deps`. Cross-task parallelism is the job of `sdd-execute-batch`.
+</HardForbidden>
+</SddExecuteOrchestrator>

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

@@ -0,0 +1,84 @@
+# sdd-execute / scripts
+
+Helper scripts bundled with the `sdd-execute` skill. They live alongside the skill, not in any project — invoke via absolute path `~/Developer/gennady/ai/skills/sdd-execute/scripts/sdd`.
+
+All scripts honor the contract: **never produce silent empty output**. On miss, they emit actionable diagnostic instructions and a non-zero exit code. Phase agents and audit agents can therefore rely on either content-on-stdout (exit 0) or instruction-on-stdout (exit ≠ 0) to drive their next decision.
+
+## Entry point — `sdd` dispatcher
+
+```bash
+~/Developer/gennady/ai/skills/sdd-execute/scripts/sdd help                                 # surface
+~/Developer/gennady/ai/skills/sdd-execute/scripts/sdd extract <file> <SECTION_NAME>        # extract anchored section
+~/Developer/gennady/ai/skills/sdd-execute/scripts/sdd lint <file>...                       # gennady DBC AST contract lint
+~/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
+```
+
+Single permission rule covers all subcommands:
+
+```json
+"Bash(~/Developer/gennady/ai/skills/sdd-execute/scripts/sdd *)"
+```
+
+Or broader:
+
+```json
+"Bash(~/Developer/gennady/ai/skills/sdd-execute/scripts/*)"
+```
+
+## Files
+
+| File                 | Purpose                                                                                                                                                                                                                                                                                                              |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sdd`                | Command dispatcher (single entry point)                                                                                                                                                                                                                                                                              |
+| `extract-section.sh` | Extract `<!--SECTION:NAME-->...<!--/SECTION:NAME-->` block from markdown                                                                                                                                                                                                                                             |
+| `lint-artifacts.sh`  | Run gennady DBC AST contract lint; parse output reliably                                                                                                                                                                                                                                                             |
+| `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). |
+
+## Anchor convention (used by `extract`)
+
+Markdown sections delimited by HTML-comment anchors:
+
+```markdown
+<!--SECTION:META-->
+
+## 1. Meta
+
+...
+
+<!--/SECTION:META-->
+```
+
+Grammar:
+
+- Open: `<!--SECTION:<NAME>-->`
+- Close: `<!--/SECTION:<NAME>-->`
+- `<NAME>` matches `^[A-Z][A-Z0-9_]*$`
+
+Canonical names: `META`, `PHASES_OVERVIEW`, `PHASE_P<N>`, `BDD`, `VERIFICATION`, `TEST_COVERAGE`, `EXECUTION_LOG`.
+
+## Blocker resolution convention (used by `check-blockers`)
+
+A BLOCKER entry (line containing `🛑` and `BLOCKED`) is considered RESOLVED if a later Round entry contains both `✅` and `RESOLVED`. The script verifies the latest marker is `✅` and counts match, otherwise reports unresolved.
+
+To resolve a blocker, append to ticket Execution Log:
+
+```markdown
+### Round N — <date>, <reason>
+
+- ✅ `<timestamp>` RESOLVED Round M BLOCKER (<short reference>): <reason for resolution>
+```
+
+## Project-agnostic by design
+
+These scripts know nothing about any specific project. They expect:
+
+- A markdown file with anchored sections (for `extract`).
+- A TypeScript file to lint (for `lint`).
+- A ticket file with `## 7. Execution Log` section (for `check-blockers`).
+- A working directory with `npm` and `tsc` available (for `verify`).
+
+If the project doesn't satisfy these expectations, scripts emit actionable diagnostics; they never silently fail.