gennady 0.7.0 → 0.8.0

package/dist/ai/skills/sdd-execute/scripts/lint-artifacts.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+# @file: Run gennady lint on phase artifacts; parse output for success/failure (gennady exit-code unreliable).
+# @consumers: phase agents (STEP_5_VERIFY); audit subagents (STEP_1 pre-pass cross-check)
+# @contract: AX_BASH_NO_SILENT_EMPTY — never produces empty stdout. On miss → actionable instruction.
+#
+# Why this wrapper exists:
+#   - gennady CLI lives outside the project (canonical: ~/Developer/gennady/cli/gennady.ts).
+#   - gennady requires `node --experimental-strip-types` (Node 22+) — the bare `node` invocation is non-obvious.
+#   - gennady returns exit code 0 even when lint reports errors (the failure signal is the literal token
+#     "[linting → failed]" in stdout). We must parse output, not trust exit code.
+#   - Success signal is the literal token "[linting → clean] no errors".
+#
+# Usage:
+#   lint-artifacts.sh <file1> [<file2> ...]
+#
+# Exit codes:
+#   0 — all files clean (gennady output contains "[linting → clean]" and NOT "[linting → failed]")
+#   1 — gennady CLI not found / unable to invoke
+#   2 — lint reported errors (one or more violations); full output emitted
+#   3 — ambiguous output (neither "clean" nor "failed" token present); investigate gennady CLI changes
+#   4 — bad invocation (no args)
+
+set -uo pipefail
+
+PROG="lint-artifacts"
+GENNADY_CLI=~/Developer/gennady/cli/gennady.ts
+
+if [[ $# -lt 1 ]]; then
+    cat <<EOF
+[$PROG] BAD_INVOCATION
+  expected: $PROG <file1> [<file2> ...]
+  got:      $PROG (no args)
+
+Required action (ORCHESTRATOR / phase agent):
+  Pass at least one TypeScript file path to lint.
+  Typically: phase's Target Files list.
+EOF
+    exit 4
+fi
+
+if [[ ! -f "$GENNADY_CLI" ]]; then
+    cat <<EOF
+[$PROG] GENNADY_CLI_NOT_FOUND
+  expected at: $GENNADY_CLI
+
+Diagnosis: the gennady AST DbC linter is unreachable from this environment.
+
+Required action (ORCHESTRATOR):
+  1. Verify the gennady project is checked out at ~/Developer/gennady.
+  2. If gennady moved → update GENNADY_CLI variable in this script.
+  3. If on a CI/sandbox without gennady → this is a HARD blocker; phase cannot verify.
+     Report to operator: cannot complete phase without DBC contract verification.
+
+DO NOT proceed to EMIT_HANDOFF without gennady lint passing.
+EOF
+    exit 1
+fi
+
+# ---------------------------------------------------------------------------
+# Run gennady lint and capture output
+# ---------------------------------------------------------------------------
+
+# Use a temp file to capture full output; we need both grep on it and to emit on failure.
+tmp_out=$(mktemp -t lint-artifacts.XXXXXX)
+trap 'rm -f "$tmp_out"' EXIT
+
+# Run gennady. We intentionally ignore its exit code (unreliable per contract above).
+npx tsx "$GENNADY_CLI" lint "$@" > "$tmp_out" 2>&1 || true
+
+has_clean=$(grep -c '\[linting → clean\]' "$tmp_out" 2>/dev/null || echo 0)
+has_failed=$(grep -c '\[linting → failed\]' "$tmp_out" 2>/dev/null || echo 0)
+
+# Convert to single-line numbers (grep -c with || echo 0 may produce odd output on some shells)
+has_clean=${has_clean//[^0-9]/}
+has_failed=${has_failed//[^0-9]/}
+has_clean=${has_clean:-0}
+has_failed=${has_failed:-0}
+
+# ---------------------------------------------------------------------------
+# Branch on tokens
+# ---------------------------------------------------------------------------
+
+if [[ "$has_failed" -gt 0 ]]; then
+    # Extract just the error lines (those with file:line: error: format) + final summary
+    cat <<EOF
+[$PROG] LINT_FAILED
+  files lint'd: $#
+  gennady output token: [linting → failed]
+
+Full lint output (gennady DBC AST findings):
+EOF
+    # Print error lines and the failure summary line
+    grep -E '\[linting → failed\]|: error: |^---|^References:|^  ' "$tmp_out" | head -200
+    echo
+    cat <<EOF
+---
+
+Required action (PHASE AGENT, before EMIT_HANDOFF):
+  1. Read each error: format is <file>:<line>:<col>: error: <ERR_CODE>: <message>
+  2. Common categories:
+     - ERR_DBC_LINT_PARAM_MISSING — add @param <name> <coherent-role-description>
+     - ERR_DBC_LINT_RETURNS_MISSING — add @returns <business-purpose-of-value>
+     - ERR_DBC_ORDER — reorder JSDoc tags per AX_BASE_CONTRACT_SHAPE:
+         @purpose → @consumers → @implements → @invariant → @pre →
+         @param → @throws → @returns → @post → @sideEffect
+  3. Fix all violations in the target files.
+  4. Re-run this script. Repeat until clean.
+  5. Do NOT EMIT_HANDOFF with lint failures present — that is fabricated DONE.
+
+References:
+  /Users/k.lebedev/Developer/vkt/ai/directives/coding/typescript-rules.xml
+  — AX_TAG_USAGE_MATRIX, AX_BASE_CONTRACT_SHAPE, AX_FLAT_JSDOC_FOR_PROPERTIES
+EOF
+    exit 2
+fi
+
+if [[ "$has_clean" -gt 0 ]]; then
+    # Clean. Emit concise PASS line to keep parent context light.
+    file_count=$#
+    echo "[$PROG] LINT_PASS"
+    echo "  files lint'd: $file_count"
+    echo "  gennady output token: [linting → clean]"
+    exit 0
+fi
+
+# Neither token found — gennady output format may have changed.
+cat <<EOF
+[$PROG] AMBIGUOUS_OUTPUT
+  files lint'd: $#
+  gennady output token: (neither "linting → clean" nor "linting → failed" found)
+
+Diagnosis: gennady CLI output format may have changed (or there is an unhandled edge case).
+
+Captured output:
+$(cat "$tmp_out" | head -50)
+
+Required action (ORCHESTRATOR):
+  1. Re-read gennady source: ~/Developer/gennady/cli/gennady.ts
+  2. Check command output tokens in the LintCommand implementation.
+  3. Update this script's parsing to match new tokens.
+  4. Until resolved → treat as a HARD blocker; DO NOT assume PASS.
+EOF
+exit 3

package/dist/ai/skills/sdd-execute/scripts/scan.sh

@@ -0,0 +1,385 @@
+#!/usr/bin/env bash
+# @file: Emit comprehensive SDD project snapshot in a single tool call.
+# @consumers: sdd-check, sdd-continue, sdd-execute-batch (preflight + triage).
+# @contract: AX_BASH_NO_SILENT_EMPTY. One-shot rich-context emitter so agents
+#            avoid running multiple ad-hoc find/grep commands.
+#
+# Output sections (stable, machine-readable):
+#   [HEADER]    — scan metadata (root, timestamp, version)
+#   [TASKS]     — TSV: path, status, last_round, blocker, placeholders, warnings
+#   [TRACKERS]  — TSV: tracker_path, done, todo, in_progress, blocked, total
+#   [SPECS]     — TSV: spec_path, scope, modules_listed, modules_missing
+#   [WARNINGS]  — severity \t location \t message (collected during scan)
+#   [SUMMARY]   — key=value totals
+#
+# Usage:
+#   scan.sh [project-root]   # defaults to current directory
+#
+# Exit codes:
+#   0  — snapshot emitted (may include WARNINGS — agent must inspect)
+#   2  — structural failure (root not found, tasks/ missing, etc.); STDOUT has
+#        actionable diagnostic instructions
+#   4  — bad invocation
+
+set -uo pipefail
+
+PROG="scan"
+VERSION="1"
+
+# ---------------------------------------------------------------------------
+# Argument parsing
+# ---------------------------------------------------------------------------
+
+if [[ $# -gt 1 ]]; then
+    cat <<EOF
+[$PROG] BAD_INVOCATION
+  expected: $PROG [project-root]
+  got:      $PROG $*
+
+Required action:
+  Pass zero or one argument — the project root. Defaults to current directory.
+EOF
+    exit 4
+fi
+
+ROOT="${1:-.}"
+
+if [[ ! -d "$ROOT" ]]; then
+    cat <<EOF
+[$PROG] BAD_ROOT
+  path: $ROOT
+  reason: not a directory or does not exist
+
+Required action:
+  - Verify you passed a project root that exists.
+  - From within a project, call: $PROG  (no arg) or $PROG .
+EOF
+    exit 2
+fi
+
+# Resolve to absolute path for stable output
+ROOT_ABS="$(cd "$ROOT" && pwd)"
+
+# ---------------------------------------------------------------------------
+# Sanity: does this look like an SDD project?
+# ---------------------------------------------------------------------------
+
+has_tasks=0
+has_specs=0
+[[ -d "$ROOT_ABS/tasks" ]] && has_tasks=1
+[[ -d "$ROOT_ABS/specs" ]] && has_specs=1
+
+if [[ $has_tasks -eq 0 && $has_specs -eq 0 ]]; then
+    cat <<EOF
+[$PROG] NOT_AN_SDD_PROJECT
+  root: $ROOT_ABS
+  reason: neither tasks/ nor specs/ directory found
+
+Required action:
+  - If this is meant to be an SDD project, run /sdd-scaffold to bootstrap it.
+  - If you ran from the wrong directory, pass the project root explicitly:
+      $PROG /path/to/project
+  - If your project uses non-standard layout (tasks elsewhere), this tool
+    does not support that — convention is tasks/ + specs/ under root.
+EOF
+    exit 2
+fi
+
+# ---------------------------------------------------------------------------
+# Buffers (using temp files for portability with macOS bash 3.2)
+# ---------------------------------------------------------------------------
+
+TMPDIR_BUF="$(mktemp -d -t sdd-scan.XXXXXX)" || { echo "[$PROG] MKTEMP_FAILED"; exit 2; }
+trap 'rm -rf "$TMPDIR_BUF"' EXIT
+
+WARN_FILE="$TMPDIR_BUF/warnings"
+: > "$WARN_FILE"
+
+emit_warn() {
+    # severity \t location \t message
+    printf '%s\t%s\t%s\n' "$1" "$2" "$3" >> "$WARN_FILE"
+}
+
+# ---------------------------------------------------------------------------
+# HEADER
+# ---------------------------------------------------------------------------
+
+printf '# sdd scan v%s\n' "$VERSION"
+printf 'ROOT=%s\n' "$ROOT_ABS"
+printf 'SCANNED_AT=%s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+printf 'HAS_TASKS=%d\n' "$has_tasks"
+printf 'HAS_SPECS=%d\n' "$has_specs"
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+# Extract Meta.Status from a ticket. Echoes one of:
+#   DONE | TODO | IN_PROGRESS | BLOCKED | UNKNOWN
+extract_status() {
+    local f="$1"
+    # Look in first 60 lines for "Status:" with [flag] STATE
+    local line
+    line=$(head -60 "$f" 2>/dev/null | grep -m1 -E '^\s*-?\s*\*?\*?Status:\*?\*?\s*\[.\]' || true)
+    if [[ -z "$line" ]]; then
+        echo "UNKNOWN"
+        return
+    fi
+    # Extract flag char between [ and ]
+    local flag
+    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
+}
+
+# Count Round headers in Execution Log. Echoes count (0 if none).
+count_rounds() {
+    local f="$1"
+    grep -E '^### Round [0-9]+' "$f" 2>/dev/null | wc -l | tr -d ' '
+}
+
+# Detect blocker state. Echoes:
+#   none      — no 🛑 BLOCKED entries
+#   active    — at least one 🛑 BLOCKED with no matching later ✅ RESOLVED
+#   resolved  — all 🛑 entries followed by ✅ RESOLVED (last marker is ✅)
+blocker_state() {
+    local f="$1"
+    local log_start
+    log_start=$(grep -n "^## 7\. Execution Log" "$f" 2>/dev/null | head -1 | cut -d: -f1)
+    [[ -z "$log_start" ]] && { echo "none"; return; }
+
+    local blockers resolved last_b last_r
+    blockers=$(grep -nE '🛑.*BLOCKED|BLOCKED.*🛑' "$f" 2>/dev/null \
+                | awk -F: -v s="$log_start" '$1>=s' | wc -l | tr -d ' ')
+    resolved=$(grep -nE '✅.*RESOLVED|RESOLVED.*✅' "$f" 2>/dev/null \
+                | awk -F: -v s="$log_start" '$1>=s' | wc -l | tr -d ' ')
+
+    [[ "$blockers" -eq 0 ]] && { echo "none"; return; }
+
+    last_b=$(grep -nE '🛑.*BLOCKED|BLOCKED.*🛑' "$f" 2>/dev/null \
+                | awk -F: -v s="$log_start" '$1>=s {print $1}' | tail -1)
+    last_r=$(grep -nE '✅.*RESOLVED|RESOLVED.*✅' "$f" 2>/dev/null \
+                | awk -F: -v s="$log_start" '$1>=s {print $1}' | tail -1)
+    last_b="${last_b:-0}"
+    last_r="${last_r:-0}"
+
+    if [[ "$resolved" -ge "$blockers" && "$last_r" -gt "$last_b" ]]; then
+        echo "resolved"
+    else
+        echo "active"
+    fi
+}
+
+# Count placeholder markers (unfilled scaffold values) in a ticket.
+count_placeholders() {
+    local f="$1"
+    grep -E '<YYYY-MM-DD>|<TBD>|`\[<ts>\]`|<command>|<scope>|<scenario>|<test-file>::<case>|<list or' "$f" 2>/dev/null | wc -l | tr -d ' '
+}
+
+# Per-ticket warnings (string, comma-separated, "-" if none)
+ticket_warnings() {
+    local f="$1"
+    local w=()
+    # Required structural sections
+    grep -q '^## 1\. Meta' "$f" 2>/dev/null || w+=("no-meta-section")
+    grep -q '^## 7\. Execution Log' "$f" 2>/dev/null || w+=("no-execlog-section")
+    # Anchor closure sanity
+    local opens closes
+    opens=$(grep -E '^[[:space:]]*<!--SECTION:[A-Z][A-Z0-9_]*-->' "$f" 2>/dev/null | wc -l | tr -d ' ')
+    closes=$(grep -E '^[[:space:]]*<!--/SECTION:[A-Z][A-Z0-9_]*-->' "$f" 2>/dev/null | wc -l | tr -d ' ')
+    if [[ "$opens" -ne "$closes" ]]; then
+        w+=("anchors-mismatch:$opens-open/$closes-close")
+    fi
+    if [[ ${#w[@]} -eq 0 ]]; then
+        echo "-"
+    else
+        (IFS=,; echo "${w[*]}")
+    fi
+}
+
+# ---------------------------------------------------------------------------
+# [TASKS]
+# ---------------------------------------------------------------------------
+
+printf '\n[TASKS]\n'
+printf '# path\tstatus\tlast_round\tblocker\tplaceholders\twarnings\n'
+
+if [[ $has_tasks -eq 0 ]]; then
+    printf '# (tasks/ directory not present)\n'
+    emit_warn "WARN" "tasks/" "directory missing; no tickets to scan"
+else
+    # -L follows symlinks (project convention; see AGENTS.md in symlinked projects)
+    TASK_FILES=$(find -L "$ROOT_ABS/tasks" -name '*.task-*.md' -type f 2>/dev/null | sort || true)
+    if [[ -z "$TASK_FILES" ]]; then
+        printf '# (no *.task-*.md files found under tasks/)\n'
+        emit_warn "INFO" "tasks/" "no ticket files matching '*.task-*.md' — project may be pre-scaffold"
+    else
+        while IFS= read -r f; do
+            [[ -z "$f" ]] && continue
+            rel="${f#$ROOT_ABS/}"
+            status=$(extract_status "$f")
+            rounds=$(count_rounds "$f")
+            blocker=$(blocker_state "$f")
+            placeholders=$(count_placeholders "$f")
+            warns=$(ticket_warnings "$f")
+
+            # Promote suspicious combinations into the WARNINGS section
+            if [[ "$status" == "DONE" && "$blocker" == "active" ]]; then
+                emit_warn "ERROR" "$rel" "status=DONE but unresolved BLOCKER in Execution Log"
+            fi
+            if [[ "$status" == "DONE" && "$placeholders" -gt 0 ]]; then
+                emit_warn "WARN" "$rel" "status=DONE but $placeholders scaffold placeholder(s) remain"
+            fi
+            if [[ "$status" == "UNKNOWN" ]]; then
+                emit_warn "WARN" "$rel" "Meta.Status not parseable (expected '[x] DONE' / '[ ] TODO' / '[~] IN_PROGRESS' / '[!] BLOCKED')"
+            fi
+            if [[ "$warns" != "-" ]]; then
+                emit_warn "WARN" "$rel" "ticket structure: $warns"
+            fi
+
+            printf '%s\t%s\t%s\t%s\t%s\t%s\n' \
+                "$rel" "$status" "$rounds" "$blocker" "$placeholders" "$warns"
+        done <<< "$TASK_FILES"
+    fi
+fi
+
+# ---------------------------------------------------------------------------
+# [TRACKERS]
+# ---------------------------------------------------------------------------
+
+printf '\n[TRACKERS]\n'
+printf '# tracker_path\tdone\ttodo\tin_progress\tblocked\ttotal\n'
+
+if [[ $has_tasks -eq 0 ]]; then
+    printf '# (tasks/ missing)\n'
+else
+    TRACKERS=$(find -L "$ROOT_ABS/tasks" -name 'README.md' -type f 2>/dev/null | sort || true)
+    if [[ -z "$TRACKERS" ]]; then
+        printf '# (no README.md trackers found under tasks/)\n'
+        emit_warn "WARN" "tasks/" "no tracker README.md files — convention is tasks/README.md per scope"
+    else
+        while IFS= read -r tr; do
+            [[ -z "$tr" ]] && continue
+            rel="${tr#$ROOT_ABS/}"
+            # Count tracker rows matching TSK-NN pattern with status cell
+            # Match both bare and link form: `| TSK-NN |` or `| [TSK-NN](...) |`
+            done_c=$(grep -E '\|[[:space:]]*\[?TSK-[0-9]+.*`?\[x\]`?[[:space:]]+DONE' "$tr" 2>/dev/null | wc -l | tr -d ' ')
+            todo_c=$(grep -E '\|[[:space:]]*\[?TSK-[0-9]+.*`?\[ \]`?[[:space:]]+TODO' "$tr" 2>/dev/null | wc -l | tr -d ' ')
+            inpg_c=$(grep -E '\|[[:space:]]*\[?TSK-[0-9]+.*`?\[~\]`?[[:space:]]+IN_PROGRESS' "$tr" 2>/dev/null | wc -l | tr -d ' ')
+            blkd_c=$(grep -E '\|[[:space:]]*\[?TSK-[0-9]+.*`?\[!\]`?[[:space:]]+BLOCKED' "$tr" 2>/dev/null | wc -l | tr -d ' ')
+            total=$((done_c + todo_c + inpg_c + blkd_c))
+            if [[ "$total" -eq 0 ]]; then
+                # Tracker README might be the top-level overview without ticket rows — fine, but mark with hint
+                emit_warn "INFO" "$rel" "no TSK rows detected (top-level overview tracker?)"
+            fi
+            printf '%s\t%d\t%d\t%d\t%d\t%d\n' "$rel" "$done_c" "$todo_c" "$inpg_c" "$blkd_c" "$total"
+        done <<< "$TRACKERS"
+    fi
+fi
+
+# ---------------------------------------------------------------------------
+# [SPECS]
+# ---------------------------------------------------------------------------
+
+printf '\n[SPECS]\n'
+printf '# spec_path\tscope\tmodules_listed\tmodules_missing\n'
+
+if [[ $has_specs -eq 0 ]]; then
+    printf '# (specs/ missing)\n'
+else
+    SPECS=$(find -L "$ROOT_ABS/specs" -name '*.spec.md' -type f 2>/dev/null | sort || true)
+    if [[ -z "$SPECS" ]]; then
+        printf '# (no *.spec.md files under specs/)\n'
+        emit_warn "INFO" "specs/" "no spec files — run /sdd-discover to bootstrap"
+    else
+        while IFS= read -r sp; do
+            [[ -z "$sp" ]] && continue
+            rel="${sp#$ROOT_ABS/}"
+            # Derive scope from path: specs/<scope>/<scope>.spec.md or specs/<scope>/<module>/<module>.spec.md
+            scope=$(echo "$rel" | awk -F/ '{print $2}')
+            # Count module references: paths like (../<module>/<module>.spec.md) or relative links to *.spec.md
+            modules=$(grep -oE '[a-z][a-z0-9-]*\.spec\.md' "$sp" 2>/dev/null | sort -u | wc -l | tr -d ' ')
+            # Count missing referenced specs (link target does not exist relative to this spec)
+            missing=0
+            base_dir=$(dirname "$sp")
+            while IFS= read -r link; do
+                [[ -z "$link" ]] && continue
+                # Resolve relative
+                if [[ -e "$base_dir/$link" ]]; then
+                    :
+                else
+                    missing=$((missing + 1))
+                fi
+            # Only consider real markdown links: ](path.spec.md...) — preceded by ']'.
+            # Skip inline-code paths like (`path.spec.md`) — those are descriptive references, not links.
+            done < <(grep -oE '\]\([^)`]+\.spec\.md[^)]*\)' "$sp" 2>/dev/null \
+                       | sed -E 's/^\]\(//; s/[#)].*$//' | sort -u)
+            if [[ "$missing" -gt 0 ]]; then
+                emit_warn "ERROR" "$rel" "$missing referenced *.spec.md link(s) do not resolve on disk"
+            fi
+            printf '%s\t%s\t%d\t%d\n' "$rel" "${scope:-unknown}" "$modules" "$missing"
+        done <<< "$SPECS"
+    fi
+fi
+
+# ---------------------------------------------------------------------------
+# [WARNINGS]
+# ---------------------------------------------------------------------------
+
+printf '\n[WARNINGS]\n'
+printf '# severity\tlocation\tmessage\n'
+if [[ -s "$WARN_FILE" ]]; then
+    cat "$WARN_FILE"
+else
+    printf '# (none)\n'
+fi
+
+# ---------------------------------------------------------------------------
+# [SUMMARY]
+# ---------------------------------------------------------------------------
+
+# Aggregate from emitted [TASKS] block by re-walking files (cheap, ~ms).
+sum_done=0; sum_todo=0; sum_inpg=0; sum_blkd=0; sum_unk=0
+sum_active_blockers=0; sum_total_tasks=0
+if [[ $has_tasks -eq 1 && -n "${TASK_FILES:-}" ]]; then
+    while IFS= read -r f; do
+        [[ -z "$f" ]] && continue
+        sum_total_tasks=$((sum_total_tasks + 1))
+        s=$(extract_status "$f")
+        case "$s" in
+            DONE)        sum_done=$((sum_done+1)) ;;
+            TODO)        sum_todo=$((sum_todo+1)) ;;
+            IN_PROGRESS) sum_inpg=$((sum_inpg+1)) ;;
+            BLOCKED)     sum_blkd=$((sum_blkd+1)) ;;
+            *)           sum_unk=$((sum_unk+1)) ;;
+        esac
+        b=$(blocker_state "$f")
+        [[ "$b" == "active" ]] && sum_active_blockers=$((sum_active_blockers+1))
+    done <<< "$TASK_FILES"
+fi
+
+warn_count=$(grep -E '^WARN' "$WARN_FILE" 2>/dev/null | wc -l | tr -d ' ')
+err_count=$(grep -E '^ERROR' "$WARN_FILE" 2>/dev/null | wc -l | tr -d ' ')
+info_count=$(grep -E '^INFO' "$WARN_FILE" 2>/dev/null | wc -l | tr -d ' ')
+
+printf '\n[SUMMARY]\n'
+printf 'tasks_total=%d\n' "$sum_total_tasks"
+printf 'tasks_done=%d\n' "$sum_done"
+printf 'tasks_todo=%d\n' "$sum_todo"
+printf 'tasks_in_progress=%d\n' "$sum_inpg"
+printf 'tasks_blocked=%d\n' "$sum_blkd"
+printf 'tasks_unknown_status=%d\n' "$sum_unk"
+printf 'active_blockers=%d\n' "$sum_active_blockers"
+printf 'warnings=%d\n' "$warn_count"
+printf 'errors=%d\n' "$err_count"
+printf 'info=%d\n' "$info_count"
+
+# Exit 0 always when snapshot emitted. WARNINGS/ERRORS are *data* the agent must
+# interpret — they are not invocation failures. Use exit 2 only when we cannot
+# emit a snapshot (handled above).
+exit 0

package/dist/ai/skills/sdd-execute/scripts/sdd

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# @file: SDD command dispatcher — single entry point for all SDD helper scripts.
+# @consumers: phase agents, audit agents, orchestrator skills
+# @contract: AX_BASH_NO_SILENT_EMPTY. Stable surface: `sdd <subcommand> <args>`.
+#
+# Subcommands:
+#   sdd extract <file> <NAME>           — extract <!--SECTION:NAME--> ... <!--/SECTION:NAME--> block
+#   sdd lint <file>...                  — run gennady DBC AST lint, parse output reliably
+#   sdd verify <file>...                — comprehensive gate: typecheck + gennady lint + forbidden_grep
+#   sdd check-blockers <ticket-file>    — scan Execution Log for unresolved BLOCKER entries
+#   sdd scan [project-root]             — emit comprehensive project snapshot (single rich call)
+#   sdd help                            — print this help
+#
+# Why this wrapper exists:
+#   - Single permission rule pattern: `Bash(scripts/sdd/sdd *)` covers ALL SDD operations.
+#   - Stable API across project lifetimes — script names underneath can change without breaking agent patterns.
+#   - Consistent error contract (AX_BASH_NO_SILENT_EMPTY) across all subcommands.
+#
+# Exit codes (forwarded from subcommand):
+#   0    — success
+#   1-N  — subcommand-specific failure (see each subcommand's documented codes)
+#   127  — unknown subcommand
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROG="sdd"
+SUBCMD="${1:-help}"
+shift 2>/dev/null || true
+
+case "$SUBCMD" in
+    extract)
+        exec "$SCRIPT_DIR/extract-section.sh" "$@"
+        ;;
+    lint)
+        exec "$SCRIPT_DIR/lint-artifacts.sh" "$@"
+        ;;
+    verify)
+        exec "$SCRIPT_DIR/verify.sh" "$@"
+        ;;
+    check-blockers)
+        exec "$SCRIPT_DIR/check-blockers.sh" "$@"
+        ;;
+    scan)
+        exec "$SCRIPT_DIR/scan.sh" "$@"
+        ;;
+    help|--help|-h)
+        cat <<'EOF'
+sdd — SDD command dispatcher
+
+USAGE
+    sdd <subcommand> <args>
+
+SUBCOMMANDS
+    extract <file> <NAME>       Extract anchored section from a markdown file.
+                                  NAME format: ^[A-Z][A-Z0-9_]*$
+                                  Examples: META, PHASES_OVERVIEW, PHASE_P1, BDD, VERIFICATION,
+                                            TEST_COVERAGE, EXECUTION_LOG
+
+    lint <file>...              Run gennady DBC AST lint on listed TypeScript files.
+                                  Output parsed for "[linting → clean]" / "[linting → failed]".
+                                  Exit code reliable (unlike raw gennady).
+
+    verify <file>...            Comprehensive verification gate — runs ALL of:
+                                   (1) npm run typecheck
+                                   (2) gennady DBC lint on listed files
+                                   (3) npm run lint
+                                   (4) npm run test
+                                   (5) npm run format check
+                                 RUN-ALL: every gate executes; failures accumulate.
+                                 SUPPRESS-ON-SUCCESS: passing gates produce zero output.
+                                 On all-pass: single line. On failure: only failed gates
+                                 with captured output shown.
+
+    scan [root]                 Emit one rich snapshot of an SDD project:
+                                  [HEADER] [TASKS] [TRACKERS] [SPECS] [WARNINGS] [SUMMARY]
+                                  Designed so triage/check skills make ONE call instead of
+                                  many ad-hoc find/grep commands. Suspicious states
+                                  (DONE+placeholders, DONE+active-blocker, anchor mismatch,
+                                  unparseable Meta.Status, broken spec links) are surfaced
+                                  in [WARNINGS]. Defaults to current directory.
+
+    check-blockers <ticket>     Scan ticket Execution Log for unresolved BLOCKER entries.
+                                  A BLOCKER is considered RESOLVED if a later Round contains
+                                  a "✅ RESOLVED" entry referencing it. Returns list of
+                                  unresolved blockers, or PASS if all resolved / none.
+
+    help                        Print this help.
+
+PERMISSION HINT
+    Single project permission rule covers all subcommands:
+        "Bash(scripts/sdd/sdd *)"
+
+CONTRACT
+    All subcommands honor AX_BASH_NO_SILENT_EMPTY — empty output is never produced;
+    instead actionable diagnostic instructions are emitted with non-zero exit.
+EOF
+        exit 0
+        ;;
+    "")
+        echo "[$PROG] BAD_INVOCATION: no subcommand"
+        echo "  Run: sdd help"
+        exit 127
+        ;;
+    *)
+        cat <<EOF
+[$PROG] UNKNOWN_SUBCOMMAND: $SUBCMD
+
+Available subcommands: extract, lint, verify, check-blockers, scan, help.
+Run: sdd help
+EOF
+        exit 127
+        ;;
+esac