ruby_reactor 0.5.4 → 0.6.0

data/.specify/integrations/claude.manifest.json

@@ -0,0 +1,17 @@
+{
+  "integration": "claude",
+  "version": "0.11.6",
+  "installed_at": "2026-06-23T23:29:12.149990+00:00",
+  "files": {
+    ".claude/skills/speckit-analyze/SKILL.md": "0c6d0525b97b523851a3ea8fc0efdcf477dfa65bef8c4d976b6da2f220f32c86",
+    ".claude/skills/speckit-clarify/SKILL.md": "eb8907c57e9af2c54952370a45e3fb66cb21a64dc7b3d361615bab914c13becf",
+    ".claude/skills/speckit-constitution/SKILL.md": "c1a044aba243ca6aff627fb5e4404feb6f1108d4f7dd174631bee3ae477d6c15",
+    ".claude/skills/speckit-implement/SKILL.md": "042a0415ce60a5b66adf039da431d9a98cb4897ff330635e0bab0becbbaf3cd2",
+    ".claude/skills/speckit-converge/SKILL.md": "a6acccbb6630f04fa716967c68f3be9da96762805ddd2bf284fad36324c5c876",
+    ".claude/skills/speckit-plan/SKILL.md": "fd0e312109109d09d6b691d232925b54df11681e79e1dc333ad49b210d5efb00",
+    ".claude/skills/speckit-checklist/SKILL.md": "b05086a11d4b98dcb85822e8a468ef30b8353f132b6dac1359080b93833c4666",
+    ".claude/skills/speckit-specify/SKILL.md": "ebe19db388407058a6b078b3a66ea7198cb89795dc75680ba3c457f11bc8bf7a",
+    ".claude/skills/speckit-tasks/SKILL.md": "023b1c75a62dc6fd8bff67855ebb82ec54a8104e727571aa72200c8afcc3f99b",
+    ".claude/skills/speckit-taskstoissues/SKILL.md": "aa1151798a551fb52c439ca75c02d4f2e7b40c6c7d11fc025265cf1230c67cb1"
+  }
+}

data/.specify/integrations/speckit.manifest.json

@@ -0,0 +1,17 @@
+{
+  "integration": "speckit",
+  "version": "0.11.6",
+  "installed_at": "2026-06-23T23:29:12.163635+00:00",
+  "files": {
+    ".specify/scripts/bash/common.sh": "af8a16f87b4f9084759c42ff9abf35c0b2a2025dffe58c298758ff86de2923b2",
+    ".specify/scripts/bash/setup-plan.sh": "4eb12c5b00f5c66a7d01b56c90898d320dcef4425d9b96652d57156c84948eda",
+    ".specify/scripts/bash/setup-tasks.sh": "cf21ba2212b4dd5b435c5ea8527500cfd27768b86c0bbc7ebc3207759f118d27",
+    ".specify/scripts/bash/check-prerequisites.sh": "afce0aa8db177320d83aa0b8e3619c06b865fd810781894e4a7a3f81664941ce",
+    ".specify/scripts/bash/create-new-feature.sh": "9ba116b64f0328eb69bc1a195d209074ea38823a73a554160d69df34a74daa65",
+    ".specify/templates/constitution-template.md": "ce7549540fa45543cca797a150201d868e64495fdff39dc38246fb17bd4024b3",
+    ".specify/templates/checklist-template.md": "c37695297e5d3153d64f82c21223509940b13932046c7961c42d1d669516130c",
+    ".specify/templates/tasks-template.md": "fc29a233f6f5a27ca31f1aa46b596af6500c627441c6e62b2bc4a1d721525842",
+    ".specify/templates/spec-template.md": "3945437fc35cd30a5b2bf7beea680337c3516826d3efa5a6b92c4a7eca1ba28e",
+    ".specify/templates/plan-template.md": "cc7f7979cf8d8836ec26492785affd80791d3422a2b745062ec695be8c985ef7"
+  }
+}

data/.specify/memory/constitution.md

@@ -0,0 +1,134 @@
+<!--
+SYNC IMPACT REPORT
+==================
+Version change: [unset] → 1.0.0 (MINOR: initial constitution, all principles defined from scratch)
+
+Modified principles: N/A (first ratification)
+
+Added sections:
+  - Core Principles (5 principles)
+  - Technical Constraints
+  - Development Workflow
+  - Governance
+
+Templates checked:
+  - .specify/templates/plan-template.md   ✅ Constitution Check gate present, no update needed
+  - .specify/templates/spec-template.md   ✅ Aligned with Saga/library constraints
+  - .specify/templates/tasks-template.md  ✅ Task phases align with Red-Green workflow
+
+Deferred TODOs: none
+-->
+
+# RubyReactor Constitution
+
+## Core Principles
+
+### I. Gem-First Design
+
+RubyReactor is a Ruby gem published to RubyGems. Every feature MUST be designed
+as part of the gem's public API — self-contained, independently loadable, and
+free of host-application coupling. New capabilities MUST ship via `lib/` and be
+reachable through `require "ruby_reactor"` without requiring application-level
+monkey-patching. Optional integrations (Sidekiq, OpenTelemetry) MUST be isolated
+behind adapter modules so the gem remains usable in sync-only or minimal
+environments.
+
+**Rationale**: A gem that cannot be required cleanly, or that bleeds host
+concerns into its core, is not a gem — it is a Rails engine in disguise.
+Keeping gem boundaries honest protects downstream consumers.
+
+### II. Saga Pattern Integrity (NON-NEGOTIABLE)
+
+Every workflow defined with RubyReactor MUST support compensation. Steps MUST
+declare rollback logic where side effects are produced. DAG-based dependency
+resolution governs execution order — no step may run before its declared
+dependencies complete. Interrupts (pause/resume) MUST be first-class, not
+bolted on. Partial execution without a recovery path (durability or compensation)
+is forbidden.
+
+**Rationale**: The Saga pattern's value is atomicity-like guarantees without
+distributed transactions. Violating it — e.g., skipping compensation or allowing
+orphaned steps — destroys the core promise and corrupts application state.
+
+### III. Test-First with Real Infrastructure
+
+RSpec is the mandatory test framework. Tests MUST be written and confirmed
+failing before implementation begins (Red-Green-Refactor). Redis MUST be
+reachable for the test suite — mocking Redis or Sidekiq state is forbidden
+for integration and contract tests. The in-memory Sidekiq testing mode
+(`Sidekiq::Testing.inline!`) is acceptable only for unit-level step logic,
+never for async orchestration paths.
+
+**Rationale**: We were burned by mock/real divergence in async and locking
+paths. Real Redis surfaces timing, serialization, and TTL bugs that mocks
+hide. The spec_helper enforces Redis availability at suite start for this
+reason.
+
+### IV. Observability by Default
+
+Every failure MUST carry: reactor name, step name, redacted inputs, and
+failure reason. OpenTelemetry instrumentation MUST be available via middleware
+without requiring it as a hard dependency. The web dashboard MUST remain
+current with the reactor state model. Structured logging is required for all
+async execution paths — log lines MUST be machine-parseable (key=value or JSON).
+
+**Rationale**: Async distributed workflows are black boxes without
+observability. Operators need to reconstruct what happened and why from logs
+and dashboards alone, especially after crash recovery.
+
+### V. Simplicity and Semantic Versioning
+
+YAGNI governs design: add the abstraction when a second real use case exists,
+not before. Complexity MUST be justified in the PR. SemVer is strictly
+enforced: MAJOR for any breaking public API change, MINOR for backward-compatible
+additions, PATCH for fixes and clarifications. Breaking changes MUST include a
+migration note in CHANGELOG.md.
+
+**Rationale**: RubyReactor is a library used in production applications. A
+surprise breaking change in a MINOR bump costs downstream teams debugging time
+they did not budget for. Simplicity keeps the library auditable and the
+upgrade path predictable.
+
+## Technical Constraints
+
+- **Ruby**: >= 3.0.0 required. No polyfills for older Rubies.
+- **Sidekiq**: Core async dependency. Workers live in `lib/ruby_reactor/sidekiq_workers/`.
+- **Redis**: Required for state persistence, locks, semaphores, rate limits, and
+  periods. The gem does NOT manage Redis connections — callers provide them.
+- **dry-validation**: Input validation DSL. Schema definitions stay inside the
+  reactor/step DSL, not scattered across application code.
+- **OpenTelemetry**: Optional instrumentation via the middleware stack
+  (`lib/ruby_reactor/open_telemetry.rb`). MUST NOT be a hard dependency.
+- **RuboCop**: Style enforced via `rubocop-rspec` and `rubocop-rake`. All
+  commits MUST pass `bundle exec rubocop` without `--disable-pending-cops`.
+
+## Development Workflow
+
+- Feature branches target `main`. PRs MUST pass CI (RSpec + RuboCop) before merge.
+- Releases are managed by release-please. Version bump lives in
+  `lib/ruby_reactor/version.rb`. Do not manually edit the version in gemspec.
+- New features MUST update `README.md` documentation and add entries to
+  `CHANGELOG.md` under the correct semantic heading (`Features`, `Bug Fixes`,
+  `documentation`).
+- Class-based step definitions are the preferred authoring style (not inline
+  lambdas). Documentation and examples MUST reflect this.
+- The `demo_app/` directory serves as a living integration example. Changes to
+  public API surface MUST be reflected there.
+
+## Governance
+
+This constitution supersedes all other informal practices. Amendments require:
+
+1. A PR updating this file with rationale.
+2. Version bump per the SemVer policy in Principle V.
+3. Consistency propagation: update all `.specify/templates/` files that reference
+   amended principles before the PR merges.
+
+All PR reviews MUST include a Constitution Check verifying the change does not
+violate any principle. Complexity that appears to violate a principle MUST be
+justified in the `Complexity Tracking` table of the plan.
+
+Compliance review: at each MINOR or MAJOR gem release, confirm this constitution
+still accurately reflects the codebase and update as needed.
+
+**Version**: 1.0.0 | **Ratified**: 2025-10-02 | **Last Amended**: 2026-06-24

data/.specify/scripts/bash/check-prerequisites.sh

@@ -0,0 +1,189 @@
+#!/usr/bin/env bash
+
+# Consolidated prerequisite checking script
+#
+# This script provides unified prerequisite checking for Spec-Driven Development workflow.
+# It replaces the functionality previously spread across multiple scripts.
+#
+# Usage: ./check-prerequisites.sh [OPTIONS]
+#
+# OPTIONS:
+#   --json              Output in JSON format
+#   --require-tasks     Require tasks.md to exist (for implementation phase)
+#   --include-tasks     Include tasks.md in AVAILABLE_DOCS list
+#   --paths-only        Only output path variables (no validation)
+#   --help, -h          Show help message
+#
+# OUTPUTS:
+#   JSON mode: {"FEATURE_DIR":"...", "AVAILABLE_DOCS":["..."]}
+#   Text mode: FEATURE_DIR:... \n AVAILABLE_DOCS: \n ✓/✗ file.md
+#   Paths only: REPO_ROOT: ... \n BRANCH: ... \n FEATURE_DIR: ... etc.
+
+set -e
+
+# Parse command line arguments
+JSON_MODE=false
+REQUIRE_TASKS=false
+INCLUDE_TASKS=false
+PATHS_ONLY=false
+
+for arg in "$@"; do
+    case "$arg" in
+        --json)
+            JSON_MODE=true
+            ;;
+        --require-tasks)
+            REQUIRE_TASKS=true
+            ;;
+        --include-tasks)
+            INCLUDE_TASKS=true
+            ;;
+        --paths-only)
+            PATHS_ONLY=true
+            ;;
+        --help|-h)
+            cat << 'EOF'
+Usage: check-prerequisites.sh [OPTIONS]
+
+Consolidated prerequisite checking for Spec-Driven Development workflow.
+
+OPTIONS:
+  --json              Output in JSON format
+  --require-tasks     Require tasks.md to exist (for implementation phase)
+  --include-tasks     Include tasks.md in AVAILABLE_DOCS list
+  --paths-only        Only output path variables (no prerequisite validation)
+  --help, -h          Show this help message
+
+EXAMPLES:
+  # Check task prerequisites (plan.md required)
+  ./check-prerequisites.sh --json
+  
+  # Check implementation prerequisites (plan.md + tasks.md required)
+  ./check-prerequisites.sh --json --require-tasks --include-tasks
+  
+  # Get feature paths only (no validation)
+  ./check-prerequisites.sh --paths-only
+  
+EOF
+            exit 0
+            ;;
+        *)
+            echo "ERROR: Unknown option '$arg'. Use --help for usage information." >&2
+            exit 1
+            ;;
+    esac
+done
+
+# Source common functions
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get feature paths
+_paths_output=$(get_feature_paths) || { echo "ERROR: Failed to resolve feature paths" >&2; exit 1; }
+eval "$_paths_output"
+unset _paths_output
+
+# If paths-only mode, output paths and exit (no validation)
+if $PATHS_ONLY; then
+    if $JSON_MODE; then
+        # Minimal JSON paths payload (no validation performed)
+        if has_jq; then
+            jq -cn \
+                --arg repo_root "$REPO_ROOT" \
+                --arg branch "$CURRENT_BRANCH" \
+                --arg feature_dir "$FEATURE_DIR" \
+                --arg feature_spec "$FEATURE_SPEC" \
+                --arg impl_plan "$IMPL_PLAN" \
+                --arg tasks "$TASKS" \
+                '{REPO_ROOT:$repo_root,BRANCH:$branch,FEATURE_DIR:$feature_dir,FEATURE_SPEC:$feature_spec,IMPL_PLAN:$impl_plan,TASKS:$tasks}'
+        else
+            printf '{"REPO_ROOT":"%s","BRANCH":"%s","FEATURE_DIR":"%s","FEATURE_SPEC":"%s","IMPL_PLAN":"%s","TASKS":"%s"}\n' \
+                "$(json_escape "$REPO_ROOT")" "$(json_escape "$CURRENT_BRANCH")" "$(json_escape "$FEATURE_DIR")" "$(json_escape "$FEATURE_SPEC")" "$(json_escape "$IMPL_PLAN")" "$(json_escape "$TASKS")"
+        fi
+    else
+        echo "REPO_ROOT: $REPO_ROOT"
+        echo "BRANCH: $CURRENT_BRANCH"
+        echo "FEATURE_DIR: $FEATURE_DIR"
+        echo "FEATURE_SPEC: $FEATURE_SPEC"
+        echo "IMPL_PLAN: $IMPL_PLAN"
+        echo "TASKS: $TASKS"
+    fi
+    exit 0
+fi
+
+# Validate required directories and files
+if [[ ! -d "$FEATURE_DIR" ]]; then
+    echo "ERROR: Feature directory not found: $FEATURE_DIR" >&2
+    echo "Run /speckit-specify first to create the feature structure." >&2
+    exit 1
+fi
+
+if [[ ! -f "$IMPL_PLAN" ]]; then
+    echo "ERROR: plan.md not found in $FEATURE_DIR" >&2
+    echo "Run /speckit-plan first to create the implementation plan." >&2
+    exit 1
+fi
+
+# Check for tasks.md if required
+if $REQUIRE_TASKS && [[ ! -f "$TASKS" ]]; then
+    echo "ERROR: tasks.md not found in $FEATURE_DIR" >&2
+    echo "Run /speckit-tasks first to create the task list." >&2
+    exit 1
+fi
+
+# Build list of available documents
+docs=()
+
+# Always check these optional docs
+[[ -f "$RESEARCH" ]] && docs+=("research.md")
+[[ -f "$DATA_MODEL" ]] && docs+=("data-model.md")
+
+# Check contracts directory (only if it exists and has files)
+if [[ -d "$CONTRACTS_DIR" ]] && [[ -n "$(ls -A "$CONTRACTS_DIR" 2>/dev/null)" ]]; then
+    docs+=("contracts/")
+fi
+
+[[ -f "$QUICKSTART" ]] && docs+=("quickstart.md")
+
+# Include tasks.md if requested and it exists
+if $INCLUDE_TASKS && [[ -f "$TASKS" ]]; then
+    docs+=("tasks.md")
+fi
+
+# Output results
+if $JSON_MODE; then
+    # Build JSON array of documents
+    if has_jq; then
+        if [[ ${#docs[@]} -eq 0 ]]; then
+            json_docs="[]"
+        else
+            json_docs=$(printf '%s\n' "${docs[@]}" | jq -R . | jq -s .)
+        fi
+        jq -cn \
+            --arg feature_dir "$FEATURE_DIR" \
+            --argjson docs "$json_docs" \
+            '{FEATURE_DIR:$feature_dir,AVAILABLE_DOCS:$docs}'
+    else
+        if [[ ${#docs[@]} -eq 0 ]]; then
+            json_docs="[]"
+        else
+            json_docs=$(for d in "${docs[@]}"; do printf '"%s",' "$(json_escape "$d")"; done)
+            json_docs="[${json_docs%,}]"
+        fi
+        printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$(json_escape "$FEATURE_DIR")" "$json_docs"
+    fi
+else
+    # Text output
+    echo "FEATURE_DIR:$FEATURE_DIR"
+    echo "AVAILABLE_DOCS:"
+    
+    # Show status of each potential document
+    check_file "$RESEARCH" "research.md"
+    check_file "$DATA_MODEL" "data-model.md"
+    check_dir "$CONTRACTS_DIR" "contracts/"
+    check_file "$QUICKSTART" "quickstart.md"
+    
+    if $INCLUDE_TASKS; then
+        check_file "$TASKS" "tasks.md"
+    fi
+fi