gennady 0.7.0 → 0.8.0

package/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/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/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/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.

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

@@ -0,0 +1,158 @@
+#!/usr/bin/env bash
+# @file: Scan ticket Execution Log for unresolved BLOCKER entries.
+# @consumers: orchestrator (preflight before phase dispatch); audit; CI hooks.
+# @contract: AX_BASH_NO_SILENT_EMPTY. Implements AX_BLOCKER_RESOLUTION_TRAIL —
+#            BLOCKER from earlier Round is ACTIVE unless a later Round explicitly
+#            marks it RESOLVED.
+#
+# Heuristic detection:
+#   - Lines containing both "🛑" AND "BLOCKED" → blocker entry (with line number, context).
+#   - Lines containing both "✅" AND "RESOLVED" → resolution marker.
+#   - If RESOLVED markers count >= BLOCKED markers count, AND the last 🛑/✅ marker
+#     in the log is ✅ → all blockers considered resolved.
+#   - Otherwise → list latest blocker entries as ACTIVE; orchestrator must decide.
+#
+# Usage:
+#   check-blockers.sh <ticket-file>
+#
+# Exit codes:
+#   0  — no unresolved blockers (clear to dispatch)
+#   2  — one or more unresolved blockers (orchestrator MUST resolve before dispatch)
+#   4  — bad invocation
+#   1  — file not found
+
+set -uo pipefail
+
+PROG="check-blockers"
+
+if [[ $# -ne 1 ]]; then
+    cat <<EOF
+[$PROG] BAD_INVOCATION
+  expected: $PROG <ticket-file>
+  got:      $PROG $*
+
+Required action (ORCHESTRATOR):
+  Pass exactly one ticket file path.
+EOF
+    exit 4
+fi
+
+ticket="$1"
+
+if [[ ! -f "$ticket" ]]; then
+    cat <<EOF
+[$PROG] FILE_NOT_FOUND
+  file: $ticket
+
+Required action:
+  Verify ticket path; task may need re-resolution.
+EOF
+    exit 1
+fi
+
+# Locate Execution Log section start. Convention: "## 7. Execution Log".
+log_start=$(grep -n "^## 7\. Execution Log" "$ticket" | head -1 | cut -d: -f1)
+if [[ -z "$log_start" ]]; then
+    cat <<EOF
+[$PROG] NO_EXECUTION_LOG
+  file: $ticket
+
+The ticket lacks a "## 7. Execution Log" section. Either the ticket is malformed
+or uses a different section number/title.
+
+Required action (ORCHESTRATOR):
+  Verify ticket structure follows scaffold.directive convention. If structure is
+  correct but section title differs, update this script's heuristic accordingly.
+
+Treating as clear (no blockers detectable).
+EOF
+    exit 0
+fi
+
+# Extract Execution Log content
+log_content=$(tail -n +"$log_start" "$ticket")
+
+# Find blocker and resolution lines (with line numbers).
+# Use awk with proper line numbering, output to temp files for portability with macOS bash 3.2 (no mapfile).
+blocker_lines=()
+resolved_lines=()
+blocker_count=0
+resolved_count=0
+
+while IFS= read -r line; do
+    [[ -n "$line" ]] && blocker_lines+=("$line") && blocker_count=$((blocker_count + 1))
+done < <(grep -n "🛑.*BLOCKED\|BLOCKED.*🛑" "$ticket" 2>/dev/null | awk -F: -v start="$log_start" '$1 >= start { print $0 }')
+
+while IFS= read -r line; do
+    [[ -n "$line" ]] && resolved_lines+=("$line") && resolved_count=$((resolved_count + 1))
+done < <(grep -n "✅.*RESOLVED\|RESOLVED.*✅" "$ticket" 2>/dev/null | awk -F: -v start="$log_start" '$1 >= start { print $0 }')
+
+# Determine last marker (BLOCKER or RESOLUTION) by line number
+last_blocker_line=0
+last_resolved_line=0
+if [[ $blocker_count -gt 0 ]]; then
+    last_blocker_line=$(echo "${blocker_lines[$((blocker_count - 1))]}" | cut -d: -f1)
+fi
+if [[ $resolved_count -gt 0 ]]; then
+    last_resolved_line=$(echo "${resolved_lines[$((resolved_count - 1))]}" | cut -d: -f1)
+fi
+
+# ---------------------------------------------------------------------------
+# Verdict
+# ---------------------------------------------------------------------------
+
+if [[ $blocker_count -eq 0 ]]; then
+    cat <<EOF
+[$PROG] CLEAR
+  ticket: $ticket
+  blockers found: 0
+  status: no BLOCKER entries in Execution Log; clear to dispatch phase.
+EOF
+    exit 0
+fi
+
+if [[ $resolved_count -ge $blocker_count ]] && [[ $last_resolved_line -gt $last_blocker_line ]]; then
+    cat <<EOF
+[$PROG] CLEAR
+  ticket: $ticket
+  blockers found:   $blocker_count
+  resolutions:      $resolved_count
+  last marker:      ✅ RESOLVED on line $last_resolved_line
+  status: AX_BLOCKER_RESOLUTION_TRAIL satisfied — all blockers resolved.
+EOF
+    exit 0
+fi
+
+# Unresolved blockers — emit list
+cat <<EOF
+[$PROG] UNRESOLVED_BLOCKERS
+  ticket: $ticket
+  blockers found:   $blocker_count
+  resolutions:      $resolved_count
+  last 🛑 line:     $last_blocker_line
+  last ✅ line:     $last_resolved_line
+  status: AX_BLOCKER_RESOLUTION_TRAIL violated — latest marker is BLOCKER, not RESOLUTION.
+
+Active BLOCKER entries (last 5):
+EOF
+# Print last 5 elements portably (no slicing syntax that requires bash 4)
+start_idx=$((blocker_count - 5))
+[[ $start_idx -lt 0 ]] && start_idx=0
+i=$start_idx
+while [[ $i -lt $blocker_count ]]; do
+    echo "  ${blocker_lines[$i]}" | cut -c1-200
+    i=$((i + 1))
+done
+
+cat <<EOF
+
+Required action (ORCHESTRATOR):
+  1. Read the listed BLOCKER entries in the ticket.
+  2. Verify whether each blocker is still ACTIVE in current environment:
+     - If actually still blocking → escalate to operator with unblock options.
+     - If actually resolved (e.g. environment fixed, decision made) → append
+       Round N entry with "✅ RESOLVED <Round-M BLOCKER ref>: <reason>" line
+       to Execution Log; then re-run this script.
+  3. DO NOT dispatch phase agent while any blocker is unresolved.
+EOF
+exit 2

package/ai/skills/sdd-execute/scripts/classify-scripts.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// @file: Heuristic npm script classifier — reads package.json, outputs discovered commands as JSON.
+// @consumers: verify.sh
+// @tasks: TSK-55, TSK-61
+//
+// Usage: node classify-scripts.js [project-root]
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+function hasCategory(body, category) {
+  const patterns = {
+    tsc: /\b(tsc|tsgo)\b/,
+    lint: /\b(eslint|mail-core-lint\b|biome check\b|standard\b)\b/,
+    test: /\b(jest|vitest|playwright test|mocha\b|--test\b)\b/,
+    format: /\b(prettier|biome format)\b/,
+  };
+  return patterns[category] ? patterns[category].test(body) : false;
+}
+
+function classify(name, body) {
+  const isUmbrellaName = /^(check|ci-check|check:all|verify)$/.test(name);
+  if (isUmbrellaName && body.length > 0) return ['umbrella'];
+
+  const tc = hasCategory(body, 'tsc') ? 1 : 0;
+  const lc = hasCategory(body, 'lint') ? 1 : 0;
+  const sc = hasCategory(body, 'test') ? 1 : 0;
+  const hasGennady = /\bgennady\b/.test(body) || /lint:contracts/.test(body);
+  const hasChain = body.includes('&&');
+  const hasParallel = /[&]/.test(body) && /;\s*wait/.test(body);
+
+  if (tc + lc + sc >= 2 && (hasChain || hasParallel)) return ['umbrella'];
+  if (hasGennady && hasChain) return ['umbrella'];
+
+  const classes = [];
+  if (hasGennady) classes.push('gennady');
+
+  const typecheckName = /^(type-?check|typecheck|typecheck:|tsc)$/.test(name);
+  const typecheckBody = /\b(tsc|tsgo)\b/.test(body) && /--noEmit/.test(body);
+  if (
+    (typecheckName || typecheckBody || name === 'lint:ts') &&
+    !name.startsWith('build:') &&
+    !name.startsWith('prepublish')
+  )
+    classes.push('typecheck');
+
+  const lintName = /^(lint|lint:all|lint-check|eslint|mc:eslint|stylist:lint|stylelint)$/.test(
+    name
+  );
+  const lintBody = hasCategory(body, 'lint');
+  if (
+    (lintName || lintBody) &&
+    !name.startsWith('lint:fix') &&
+    !name.startsWith('lint:contracts') &&
+    !name.startsWith('lint:ts') &&
+    !hasGennady
+  )
+    classes.push('lint');
+
+  const testName = /^(test|test:|mc:test|mc:jest|jest)$/.test(name);
+  const testBody = hasCategory(body, 'test') || /\bnode\b.*--test\b/.test(body);
+  if (testName || (testBody && !name.startsWith('build:') && !name.startsWith('prepublish')))
+    classes.push('test');
+
+  const formatName = /^format(:?check)?$/.test(name);
+  const formatBody = hasCategory(body, 'format');
+  if (formatName || formatBody) classes.push('format');
+
+  return classes.length > 0 ? classes : ['unknown'];
+}
+
+function selectBest(entries, cls) {
+  const priority = {
+    typecheck: { 'type-check': 10, typecheck: 10, tsc: 5 },
+    gennady: { 'lint:contracts': 10 },
+    lint: { lint: 10, eslint: 7, 'lint:all': 5, 'lint-check': 5, 'mc:eslint': 3 },
+    test: { test: 10, 'test:unit': 7, 'mc:test': 5, 'mc:jest': 3, jest: 3 },
+    format: { 'format:check': 10, format: 5 },
+  };
+  const candidates = entries.filter((e) => e.classes.includes(cls));
+  if (candidates.length === 0) return undefined;
+  const rank = (name) => (priority[cls] && priority[cls][name]) || 1;
+  candidates.sort((a, b) => rank(b.name) - rank(a.name));
+  return candidates[0] ? candidates[0].name : undefined;
+}
+
+// --- Main ---
+const rootArg = process.argv.slice(2).find((a) => !a.startsWith('-'));
+const root = rootArg ? resolve(rootArg) : process.cwd();
+
+let pkg;
+try {
+  pkg = JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf-8'));
+} catch {
+  console.error(`[classify-scripts] package.json not found at ${root}`);
+  process.exit(1);
+}
+
+const entries = Object.entries(pkg.scripts || {}).map(([name, body]) => ({
+  name,
+  body,
+  classes: classify(name, body),
+}));
+
+const selected = {};
+for (const cls of ['typecheck', 'gennady', 'lint', 'test', 'format']) {
+  const best = selectBest(entries, cls);
+  if (best) selected[cls] = best;
+}
+
+process.stdout.write(JSON.stringify({ scripts: entries, selected }));