autonomous-coding-toolkit 1.0.0

package/scripts/scope-infer.sh

@@ -0,0 +1,159 @@
+#!/usr/bin/env bash
+# scope-infer.sh — Infer scope tags for lessons missing them
+# Reads lesson content and applies heuristics to propose scope tags.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")" && pwd)"
+
+# Defaults
+LESSONS_DIR="$SCRIPT_DIR/../docs/lessons"
+DRY_RUN=true
+APPLY=false
+
+usage() {
+    cat <<USAGE
+Usage: scope-infer.sh [--dir <lessons-dir>] [--dry-run] [--apply]
+
+Infer scope tags for lesson files that don't have a scope: field.
+
+Options:
+  --dir <path>    Lessons directory (default: docs/lessons/)
+  --dry-run       Show proposed scope without modifying files (default)
+  --apply         Write scope field into lesson files
+  --help, -h      Show this help
+USAGE
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --dir) LESSONS_DIR="$2"; shift 2 ;;
+        --dry-run) DRY_RUN=true; APPLY=false; shift ;;
+        --apply) APPLY=true; DRY_RUN=false; shift ;;
+        --help|-h) usage; exit 0 ;;
+        *) echo "Unknown flag: $1" >&2; usage >&2; exit 1 ;;
+    esac
+done
+
+# Counters
+total=0
+inferred=0
+skipped=0
+count_universal=0
+count_language=0
+count_domain=0
+count_project=0
+
+infer_scope() {
+    local file="$1"
+    local content
+    content=$(cat "$file")
+
+    # Domain signals (check title + body)
+    local title_and_body
+    title_and_body=$(echo "$content" | tr '[:upper:]' '[:lower:]')
+
+    # Domain: ha-aria
+    if echo "$title_and_body" | grep -qE '(home assistant|\bha\b|entity.*area|automation.*trigger|hass|ha-aria)'; then
+        echo "domain:ha-aria"
+        return
+    fi
+
+    # Domain: telegram
+    if echo "$title_and_body" | grep -qE '(telegram|bot.*poll|getupdates|chat_id|telegram-brief|telegram-capture)'; then
+        echo "domain:telegram"
+        return
+    fi
+
+    # Domain: notion
+    if echo "$title_and_body" | grep -qE '(\bnotion\b|notion.*sync|notion.*database|notion-tools|notion_api)'; then
+        echo "domain:notion"
+        return
+    fi
+
+    # Domain: ollama
+    if echo "$title_and_body" | grep -qE '(\bollama\b|ollama.*queue|local.*llm|ollama-queue)'; then
+        echo "domain:ollama"
+        return
+    fi
+
+    # Framework: systemd
+    if echo "$title_and_body" | grep -qE '(systemd|systemctl|\.service|\.timer|journalctl|envfile)'; then
+        echo "framework:systemd"
+        return
+    fi
+
+    # Framework: pytest
+    if echo "$title_and_body" | grep -qE '(\bpytest\b|conftest|fixture|parametrize)'; then
+        echo "framework:pytest"
+        return
+    fi
+
+    # Framework: preact/jsx
+    if echo "$title_and_body" | grep -qE '(\bpreact\b|\bjsx\b|esbuild.*jsx|jsx.*factory)'; then
+        echo "framework:preact"
+        return
+    fi
+
+    # Project-specific: autonomous-coding-toolkit
+    if echo "$title_and_body" | grep -qE '(run-plan|quality.gate|lesson-check|mab-run|batch.*audit|ralph.*loop|headless.*mode)'; then
+        echo "project:autonomous-coding-toolkit"
+        return
+    fi
+
+    # Language: check the languages field
+    local languages
+    languages=$(sed -n '/^---$/,/^---$/{ /^languages:/p; }' "$file" 2>/dev/null | head -1)
+    languages=$(echo "$languages" | sed 's/languages:[[:space:]]*//' | tr -d '[]' | tr ',' ' ' | xargs)
+
+    if [[ "$languages" == "python" ]]; then
+        echo "language:python"
+        return
+    elif [[ "$languages" == "shell" ]]; then
+        echo "language:bash"
+        return
+    elif [[ "$languages" == "javascript" || "$languages" == "typescript" ]]; then
+        echo "language:javascript"
+        return
+    fi
+
+    # No signals → universal
+    echo "universal"
+}
+
+for lesson_file in "$LESSONS_DIR"/[0-9]*.md; do
+    [[ -f "$lesson_file" ]] || continue
+    total=$((total + 1))
+
+    # Check if scope already present
+    if sed -n '/^---$/,/^---$/p' "$lesson_file" | grep -q '^scope:'; then
+        skipped=$((skipped + 1))
+        continue
+    fi
+
+    scope=$(infer_scope "$lesson_file")
+    inferred=$((inferred + 1))
+
+    # Count by type
+    case "$scope" in
+        universal) count_universal=$((count_universal + 1)) ;;
+        language:*) count_language=$((count_language + 1)) ;;
+        domain:*) count_domain=$((count_domain + 1)) ;;
+        project:*) count_project=$((count_project + 1)) ;;
+        framework:*) count_language=$((count_language + 1)) ;;  # group with language
+    esac
+
+    basename_file=$(basename "$lesson_file")
+
+    if [[ "$APPLY" == true ]]; then
+        # Insert scope: [$scope] after the languages: line in YAML frontmatter
+        sed -i "/^languages:/a scope: [$scope]" "$lesson_file"
+        echo "  APPLIED: $basename_file → scope: [$scope]"
+    else
+        echo "  PROPOSED: $basename_file → scope: [$scope]"
+    fi
+done
+
+echo ""
+echo "Inferred scope for $inferred lessons: $count_universal universal, $count_domain domain-specific, $count_language language/framework, $count_project project-specific"
+echo "Skipped $skipped lessons (already have scope)"
+echo "Total: $total lessons scanned"

package/scripts/setup-ralph-loop.sh

@@ -0,0 +1,155 @@
+#!/usr/bin/env bash
+
+# Ralph Loop Setup Script
+# Creates state file for in-session Ralph loop
+
+set -euo pipefail
+
+# Parse arguments
+PROMPT_PARTS=()
+MAX_ITERATIONS=0
+COMPLETION_PROMISE="null"
+
+# Parse options and positional arguments
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    -h|--help)
+      cat << 'HELP_EOF'
+Ralph Loop - Interactive self-referential development loop
+
+USAGE:
+  /ralph-loop [PROMPT...] [OPTIONS]
+
+ARGUMENTS:
+  PROMPT...    Initial prompt to start the loop (can be multiple words without quotes)
+
+OPTIONS:
+  --max-iterations <n>           Maximum iterations before auto-stop (default: unlimited)
+  --completion-promise '<text>'  Promise phrase (USE QUOTES for multi-word)
+  -h, --help                     Show this help message
+
+DESCRIPTION:
+  Starts a Ralph Loop in your CURRENT session. The stop hook prevents
+  exit and feeds your output back as input until completion or iteration limit.
+
+  To signal completion, you must output: <promise>YOUR_PHRASE</promise>
+
+EXAMPLES:
+  /ralph-loop Build a todo API --completion-promise 'DONE' --max-iterations 20
+  /ralph-loop --max-iterations 10 Fix the auth bug
+  /ralph-loop Refactor cache layer  (runs forever)
+
+STOPPING:
+  Only by reaching --max-iterations or detecting --completion-promise
+  No manual stop - Ralph runs infinitely by default!
+HELP_EOF
+      exit 0
+      ;;
+    --max-iterations)
+      if [[ -z "${2:-}" ]]; then
+        echo "Error: --max-iterations requires a number argument" >&2
+        exit 1
+      fi
+      if ! [[ "$2" =~ ^[0-9]+$ ]]; then
+        echo "Error: --max-iterations must be a positive integer or 0, got: $2" >&2
+        exit 1
+      fi
+      MAX_ITERATIONS="$2"
+      shift 2
+      ;;
+    --completion-promise)
+      if [[ -z "${2:-}" ]]; then
+        echo "Error: --completion-promise requires a text argument" >&2
+        exit 1
+      fi
+      COMPLETION_PROMISE="$2"
+      shift 2
+      ;;
+    *)
+      PROMPT_PARTS+=("$1")
+      shift
+      ;;
+  esac
+done
+
+# Join all prompt parts with spaces
+PROMPT="${PROMPT_PARTS[*]}"
+
+# Validate prompt is non-empty
+if [[ -z "$PROMPT" ]]; then
+  echo "Error: No prompt provided" >&2
+  echo "Usage: /ralph-loop PROMPT [--max-iterations N] [--completion-promise TEXT]" >&2
+  exit 1
+fi
+
+# Create state file for stop hook (markdown with YAML frontmatter)
+mkdir -p .claude
+
+# Quote completion promise for YAML safely via jq JSON encoding.
+# Note: jq produces JSON-escaped output (\n, \t become literal two-char sequences).
+# This is correct for YAML scalar values parsed by the stop hook's sed-based reader.
+if [[ -n "$COMPLETION_PROMISE" ]] && [[ "$COMPLETION_PROMISE" != "null" ]]; then
+  COMPLETION_PROMISE_YAML=$(jq -n --arg cp "$COMPLETION_PROMISE" '$cp')
+else
+  COMPLETION_PROMISE_YAML="null"
+fi
+
+cat > .claude/ralph-loop.local.md <<EOF
+---
+active: true
+iteration: 1
+max_iterations: $MAX_ITERATIONS
+completion_promise: $COMPLETION_PROMISE_YAML
+started_at: "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+---
+
+$PROMPT
+EOF
+
+# Output setup message
+cat <<EOF
+Ralph loop activated in this session!
+
+Iteration: 1
+Max iterations: $(if [[ $MAX_ITERATIONS -gt 0 ]]; then echo $MAX_ITERATIONS; else echo "unlimited"; fi)
+Completion promise: $(if [[ "$COMPLETION_PROMISE" != "null" ]]; then echo "$COMPLETION_PROMISE (ONLY output when TRUE - do not lie!)"; else echo "none (runs forever)"; fi)
+
+The stop hook is now active. When you try to exit, the SAME PROMPT will be
+fed back to you. You'll see your previous work in files, creating a
+self-referential loop where you iteratively improve on the same task.
+
+To monitor: head -10 .claude/ralph-loop.local.md
+
+WARNING: This loop cannot be stopped manually! It will run infinitely
+    unless you set --max-iterations or --completion-promise.
+EOF
+
+# Output the initial prompt if provided
+if [[ -n "$PROMPT" ]]; then
+  echo ""
+  echo "$PROMPT"
+fi
+
+# Display completion promise requirements if set
+if [[ "$COMPLETION_PROMISE" != "null" ]]; then
+  echo ""
+  echo "======================================================="
+  echo "CRITICAL - Ralph Loop Completion Promise"
+  echo "======================================================="
+  echo ""
+  echo "To complete this loop, output this EXACT text:"
+  echo "  <promise>$COMPLETION_PROMISE</promise>"
+  echo ""
+  echo "STRICT REQUIREMENTS (DO NOT VIOLATE):"
+  echo "  - Use <promise> XML tags EXACTLY as shown above"
+  echo "  - The statement MUST be completely and unequivocally TRUE"
+  echo "  - Do NOT output false statements to exit the loop"
+  echo "  - Do NOT lie even if you think you should exit"
+  echo ""
+  echo "IMPORTANT - Do not circumvent the loop:"
+  echo "  Even if you believe you're stuck, the task is impossible,"
+  echo "  or you've been running too long - you MUST NOT output a"
+  echo "  false promise statement. The loop is designed to continue"
+  echo "  until the promise is GENUINELY TRUE. Trust the process."
+  echo "======================================================="
+fi

package/scripts/telemetry.sh

@@ -0,0 +1,230 @@
+#!/usr/bin/env bash
+# telemetry.sh — Local telemetry capture, dashboard, export, and import
+#
+# Usage:
+#   telemetry.sh record --project-root <dir> [--batch-number N] [--passed true|false] ...
+#   telemetry.sh show --project-root <dir>
+#   telemetry.sh export --project-root <dir>
+#   telemetry.sh import --project-root <dir> <file>
+#   telemetry.sh reset --project-root <dir> --yes
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")" && pwd)"
+source "$SCRIPT_DIR/lib/common.sh"
+
+PROJECT_ROOT=""
+SUBCOMMAND=""
+
+# --- Parse top-level ---
+SUBCOMMAND="${1:-}"
+shift || true
+
+# Parse remaining args
+BATCH_NUMBER=""
+PASSED=""
+STRATEGY=""
+DURATION=""
+COST=""
+TEST_DELTA=""
+LESSONS_TRIGGERED=""
+PLAN_QUALITY=""
+BATCH_TYPE=""
+CONFIRM_YES=false
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --project-root) PROJECT_ROOT="${2:-}"; shift 2 ;;
+        --batch-number) BATCH_NUMBER="${2:-}"; shift 2 ;;
+        --passed) PASSED="${2:-}"; shift 2 ;;
+        --strategy) STRATEGY="${2:-}"; shift 2 ;;
+        --duration) DURATION="${2:-}"; shift 2 ;;
+        --cost) COST="${2:-}"; shift 2 ;;
+        --test-delta) TEST_DELTA="${2:-}"; shift 2 ;;
+        --lessons-triggered) LESSONS_TRIGGERED="${2:-}"; shift 2 ;;
+        --plan-quality) PLAN_QUALITY="${2:-}"; shift 2 ;;
+        --batch-type) BATCH_TYPE="${2:-}"; shift 2 ;;
+        --yes) CONFIRM_YES=true; shift ;;
+        --help|-h) echo "Usage: telemetry.sh <record|show|export|import|reset> --project-root <dir> [options]"; exit 0 ;;
+        *)
+            # Positional arg (for import file)
+            if [[ -z "${IMPORT_FILE:-}" ]]; then
+                IMPORT_FILE="$1"
+            fi
+            shift ;;
+    esac
+done
+
+if [[ -z "$PROJECT_ROOT" ]]; then
+    echo "telemetry: --project-root is required" >&2
+    exit 1
+fi
+
+TELEMETRY_FILE="$PROJECT_ROOT/logs/telemetry.jsonl"
+
+case "$SUBCOMMAND" in
+    record)
+        mkdir -p "$PROJECT_ROOT/logs"
+        # Coerce numeric fields to prevent jq tonumber failures on empty strings
+        BATCH_NUMBER="${BATCH_NUMBER:-0}"; BATCH_NUMBER="${BATCH_NUMBER:-0}"
+        DURATION="${DURATION:-0}"; COST="${COST:-0}"; TEST_DELTA="${TEST_DELTA:-0}"
+        jq -cn \
+            --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+            --arg bn "${BATCH_NUMBER:-0}" \
+            --arg passed "${PASSED:-false}" \
+            --arg strategy "${STRATEGY:-unknown}" \
+            --arg duration "${DURATION:-0}" \
+            --arg cost "${COST:-0}" \
+            --arg td "${TEST_DELTA:-0}" \
+            --arg lt "${LESSONS_TRIGGERED:-}" \
+            --arg pq "${PLAN_QUALITY:-}" \
+            --arg bt "${BATCH_TYPE:-unknown}" \
+            --arg pt "$(detect_project_type "$PROJECT_ROOT")" \
+            '{
+                timestamp: $ts,
+                project_type: $pt,
+                batch_type: $bt,
+                batch_number: ($bn | tonumber),
+                passed_gate: ($passed == "true"),
+                strategy: $strategy,
+                duration_seconds: ($duration | tonumber),
+                cost_usd: ($cost | tonumber),
+                test_count_delta: ($td | tonumber),
+                lessons_triggered: (if $lt == "" then [] else ($lt | split(",")) end),
+                plan_quality_score: (if $pq == "" then null else ($pq | tonumber) end)
+            }' >> "$TELEMETRY_FILE"
+        echo "telemetry: recorded batch $BATCH_NUMBER"
+        ;;
+
+    show)
+        echo "Autonomous Coding Toolkit — Telemetry Dashboard"
+        echo "════════════════════════════════════════════════"
+        echo ""
+
+        if [[ ! -f "$TELEMETRY_FILE" ]] || [[ ! -s "$TELEMETRY_FILE" ]]; then
+            echo "No telemetry data yet. Run some batches first."
+            exit 0
+        fi
+
+        # Summary stats
+        total=$(wc -l < "$TELEMETRY_FILE")
+        passed=$(jq -s '[.[] | select(.passed_gate == true)] | length' "$TELEMETRY_FILE")
+        total_cost=$(jq -s '[.[].cost_usd] | add // 0' "$TELEMETRY_FILE")
+        total_duration=$(jq -s '[.[].duration_seconds] | add // 0' "$TELEMETRY_FILE")
+        avg_cost=$(jq -s 'if length > 0 then ([.[].cost_usd] | add) / length else 0 end' "$TELEMETRY_FILE")
+
+        echo "Runs: $total batches"
+        if [[ "$total" -gt 0 ]]; then
+            pct=$((passed * 100 / total))
+            echo "Success rate: ${pct}% ($passed/$total passed gate on first attempt)"
+        fi
+        printf "Total cost: \$%.2f (\$%.2f/batch average)\n" "$total_cost" "$avg_cost"
+        hours=$(awk "BEGIN {printf \"%.1f\", $total_duration / 3600}")
+        echo "Total time: ${hours} hours"
+
+        # Strategy performance
+        echo ""
+        echo "Strategy Performance:"
+        jq -s '
+            group_by(.strategy) | .[] |
+            {
+                strategy: .[0].strategy,
+                wins: [.[] | select(.passed_gate == true)] | length,
+                total: length
+            } |
+            "  \(.strategy): \(.wins)/\(.total) (\(if .total > 0 then (.wins * 100 / .total) else 0 end)% win rate)"
+        ' "$TELEMETRY_FILE" 2>/dev/null || echo "  (no strategy data)"
+
+        # Top lesson hits
+        echo ""
+        echo "Top Lesson Hits:"
+        jq -s '
+            [.[].lessons_triggered | arrays | .[]] |
+            group_by(.) | map({lesson: .[0], count: length}) |
+            sort_by(-.count) | .[:5] |
+            .[] | "  \(.lesson): \(.count) hits"
+        ' "$TELEMETRY_FILE" 2>/dev/null || echo "  (no lesson data)"
+        ;;
+
+    export)
+        if [[ ! -f "$TELEMETRY_FILE" ]]; then
+            echo "No telemetry data to export." >&2
+            exit 1
+        fi
+        # Anonymize: remove timestamps precision, no file paths
+        jq -s '
+            [.[] | {
+                project_type,
+                batch_type,
+                passed_gate,
+                strategy,
+                duration_seconds,
+                cost_usd,
+                test_count_delta,
+                lessons_triggered,
+                plan_quality_score
+            }]
+        ' "$TELEMETRY_FILE"
+        ;;
+
+    import)
+        if [[ -z "${IMPORT_FILE:-}" || ! -f "${IMPORT_FILE:-}" ]]; then
+            echo "telemetry: import requires a file argument" >&2
+            exit 1
+        fi
+        echo "telemetry: import not yet implemented (planned for community sync)"
+        ;;
+
+    reset)
+        if [[ "$CONFIRM_YES" != true ]]; then
+            echo "telemetry: use --yes to confirm reset" >&2
+            exit 1
+        fi
+        if [[ -f "$TELEMETRY_FILE" ]]; then
+            > "$TELEMETRY_FILE"
+            echo "telemetry: cleared $TELEMETRY_FILE"
+        else
+            echo "telemetry: no telemetry file to reset"
+        fi
+        ;;
+
+    trust)
+        if [[ ! -f "$TELEMETRY_FILE" ]] || [[ ! -s "$TELEMETRY_FILE" ]]; then
+            echo '{"score":0,"level":"new","runs":0,"message":"No telemetry data yet"}'
+            exit 0
+        fi
+
+        jq -s '
+            def trust_level(score; runs):
+                if runs < 10 then "new"
+                elif score < 30 then "new"
+                elif score < 70 then "growing"
+                elif score < 90 then "trusted"
+                else "autonomous"
+                end;
+
+            length as $total |
+            ([.[] | select(.passed_gate == true)] | length) as $passed |
+            (if $total > 0 then ($passed * 100 / $total) else 0 end) as $gate_rate |
+            $gate_rate as $score |
+            trust_level($score; $total) as $level |
+            {
+                score: $score,
+                level: $level,
+                runs: $total,
+                gate_pass_rate: $gate_rate,
+                default_mode: (
+                    if $level == "new" then "human checkpoint every batch"
+                    elif $level == "growing" then "headless with checkpoint every 3rd batch"
+                    elif $level == "trusted" then "headless with notification on failures only"
+                    else "full headless, post-run summary only"
+                    end
+                )
+            }
+        ' "$TELEMETRY_FILE"
+        ;;
+
+    *)
+        echo "Usage: telemetry.sh <record|show|export|import|reset|trust> --project-root <dir>" >&2
+        exit 1
+        ;;
+esac

package/scripts/tests/run-all-tests.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Test runner that executes all test-*.sh files in the same directory
+# Reports per-file pass/fail and exits non-zero if any fail.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TOTAL=0
+PASSED=0
+FAILED=0
+
+# Collect all test files
+mapfile -t TEST_FILES < <(find "$SCRIPT_DIR" -maxdepth 1 -name "test-*.sh" -type f | sort)
+
+if [[ ${#TEST_FILES[@]} -eq 0 ]]; then
+  echo "No test files found matching test-*.sh" >&2
+  exit 1
+fi
+
+# Run each test
+for test_file in "${TEST_FILES[@]}"; do
+  test_name="$(basename "$test_file")"
+  TOTAL=$((TOTAL + 1))
+
+  # Print header
+  echo "═══════════════════════════════════════════"
+  echo "  Running: $test_name"
+  echo "═══════════════════════════════════════════"
+
+  # Run test and capture exit code
+  if bash "$test_file"; then
+    PASSED=$((PASSED + 1))
+    echo ""
+  else
+    FAILED=$((FAILED + 1))
+    echo ""
+  fi
+done
+
+# Print summary
+echo "═══════════════════════════════════════════"
+echo "  TOTAL: $TOTAL test files"
+echo "  PASSED: $PASSED"
+echo "  FAILED: $FAILED"
+echo "═══════════════════════════════════════════"
+
+# Exit non-zero if any failed
+if [[ $FAILED -gt 0 ]]; then
+  exit 1
+fi
+
+exit 0

package/scripts/tests/test-act-cli.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# test-act-cli.sh — Tests for bin/act.js CLI router
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+source "$SCRIPT_DIR/test-helpers.sh"
+
+ACT="$REPO_ROOT/bin/act.js"
+
+# ---------------------------------------------------------------------------
+# version command
+# ---------------------------------------------------------------------------
+version_output=$(node "$ACT" version 2>&1)
+assert_contains "version outputs 'act v'" "act v" "$version_output"
+
+# ---------------------------------------------------------------------------
+# help command
+# ---------------------------------------------------------------------------
+help_output=$(node "$ACT" help 2>&1)
+assert_contains "help outputs usage line" "Usage: act <command>" "$help_output"
+assert_contains "help lists 'plan' command" "plan" "$help_output"
+assert_contains "help lists 'gate' command" "gate" "$help_output"
+
+# ---------------------------------------------------------------------------
+# unknown command exits non-zero
+# ---------------------------------------------------------------------------
+assert_exit "nonexistent command exits 1" 1 node "$ACT" nonexistent-command
+
+# ---------------------------------------------------------------------------
+# validate routes to validate-all.sh (output contains "validate")
+# ---------------------------------------------------------------------------
+# validate-all.sh runs validators — we just confirm it was reached by checking
+# that output contains "validate" (the script name / summary line).
+validate_output=$(node "$ACT" validate 2>&1 || true)
+assert_contains "validate routes to validate-all.sh" "validate" "$validate_output"
+
+# ---------------------------------------------------------------------------
+# lessons without subcommand exits non-zero and shows usage hint
+# ---------------------------------------------------------------------------
+lessons_exit=0
+lessons_output=$(node "$ACT" lessons 2>&1) || lessons_exit=$?
+assert_exit "lessons without subcommand exits 1" 1 node "$ACT" lessons
+assert_contains "lessons shows usage hint" "lessons" "$lessons_output"
+
+report_results