ruby_reactor 0.6.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ab75328ca5dda28377061047d7ac45c1515266e6e1386778470e57a2b21a674
-  data.tar.gz: 8877cc95bc390355f86a02abff2a1a405c9d021b055d842306ac78abd4145efe
+  metadata.gz: abde4c2dc313b2e5d4a74873f1fc337743e6847e8f47fcbd121fd1a72be1d557
+  data.tar.gz: defd25588b78022c339ffd105d4e304d80e676498272c887cafecb60f100dc7e
 SHA512:
-  metadata.gz: 778ed5734e8fbc634e00d93d5af7282d4dd44665b0345d07589b94a3eb866f7e85e1e7b12346369c4066d8d62462ff0b84b621f7c7fc268285aeb3680013e56f
-  data.tar.gz: bf90e0ee6d4da42d7ea783fb81039f978d1deb41e5b2936f1bcb51aecc49952fd05eb7ae90b98fe8ad76352931df48fcd7b978506d6cf53751a4168794d6acbf
+  metadata.gz: 595c701f476086c166d0e157c062e0bea0e6fb243b1c5466017bf488461b987b44c70b56e081770c586a1d83519311c58da9769ae83e302fb7d17d1cdc8f37fb
+  data.tar.gz: 7dadad987df2ec6d9c1b44e93ed328f07d77660310726dceeb1ee8957cc9e63b73bd3c2338792280bfc780a95650bcac12b384af3d2aad83b3309aa4896f6d0d

data/.claude/skills/demo-app-e2e-verify/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: "demo-app-e2e-verify"
+description: "Boot demo_app via docker-compose, run demo_reactors.rake, auto-derive acceptance criteria from the reactor/rake source, and cross-check actual behavior against both the RubyReactor API and dashboard at localhost:[port]/ruby_reactor. Writes findings + a fix plan to a tmp report."
+argument-hint: "Optional: specific rake task(s)/reactor(s) to focus on (default: all)"
+compatibility: "Requires docker compose and the demo_app/lib/tasks/demo_reactors.rake tasks"
+metadata:
+  author: "project"
+user-invocable: true
+disable-model-invocation: false
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+If non-empty, scope the run to the named rake task(s)/reactor(s) instead of `demo:all`.
+Otherwise run everything.
+
+## Purpose
+
+End-to-end confidence check for `demo_app`: does what the rake demos claim to do actually
+show up correctly in the RubyReactor API and dashboard? This is not a spec-kit workflow —
+it derives its own expectations from the current code rather than from `specs/`.
+
+## Step 1: Bring the stack up
+
+1. `docker compose ps` to see what's already running; avoid tearing down containers the
+   user didn't ask to stop.
+2. `docker compose up -d demo-redis demo-sidekiq demo-app` (skip `redis-test`/`teley`
+   unless already running — they're not needed for this check). If it fails with a
+   container name conflict (`container_name` is static, and this repo runs from multiple
+   git worktrees sharing one docker daemon), check `docker ps -a --filter name=ruby_reactor`
+   — if the conflicting containers are `Exited` (not running), it's safe to `docker rm`
+   them and retry; never `rm` a container that's currently `Up` without asking, it may
+   belong to another worktree's active session.
+3. Poll `docker compose ps` / container healthchecks until `demo-redis` and `demo-sidekiq`
+   report healthy, and until the Rails server inside `demo-app` responds. Use a
+   short polling loop (not a fixed sleep) against `http://localhost:3789/ruby_reactor` —
+   treat a non-timeout HTTP response (even a 404/500) as "server is up", empty/refused as
+   "still booting". Cap the wait (e.g. ~90s) and report clearly if it never comes up.
+4. Read the exposed host port for `demo-app` from `docker-compose.yml` at runtime rather
+   than assuming `3789` — the file may have changed.
+
+## Step 2: Auto-learn the expected behavior (before running anything)
+
+For each rake task in scope, build an acceptance-criteria list by reading the source, not
+by assuming:
+
+1. Read `demo_app/lib/tasks/demo_reactors.rake` — for each in-scope task, note: which
+   reactor(s) it calls, what inputs/scenarios it loops over (e.g. `fail_at` values), and
+   what output markers it prints for success/failure/background/pause (`✅`, `❌`, `⏳`,
+   etc.).
+2. Read the corresponding reactor class(es) in `demo_app/app/reactors/`. For each step,
+   note: what triggers it to succeed/fail/halt/skip/retry-veto, what its rollback (undo)
+   does if it has side effects, and any locks/rate-limits/periods/interrupts it declares.
+3. From that, derive one acceptance criterion per scenario, e.g.:
+   - "`fail_at: nil` → task prints ✅, reactor status is `success`, `execution_trace`
+     contains every step in dependency order, `error` is nil."
+   - "`fail_at: :capture_payment` → task prints ❌, reactor status is `failed`/`halted`,
+     steps after `capture_payment` never ran, steps before it with side effects appear in
+     `undo_stack` (or show a compensation trace), `error` mentions the trigger."
+   - For background/async reactors: expect a `DispatchResult`/`⏳` print, then (after
+     `drain`/wait) a terminal status reachable via the API.
+   - For interrupt/pause reactors: expect `be_paused`-equivalent status and
+     `ready_interrupts`/`current_step` matching the interrupt step.
+4. Keep this list in memory (or a scratch note) — it is what Step 4 checks results against.
+   If a reactor's behavior can't be inferred confidently from its source, say so explicitly
+   rather than guessing an expectation.
+
+## Step 3: Run the demos
+
+1. Execute the in-scope rake task(s) inside the running container:
+   `docker compose exec -T demo-app bin/rails demo:<task>` (or `demo:all` by default).
+2. Capture full stdout. Extract, per scenario run: reactor class, inputs used (especially
+   any `fail_at`/scenario discriminator), the printed outcome marker, and any
+   `execution_id`/`context_id`/`order_id` printed — these are the join key to the API in
+   Step 4. If a task doesn't print an id, look up the id via the API list endpoint
+   (Step 4.1) by class name + recency instead of skipping verification.
+3. For async/background scenarios, allow Sidekiq (already running as `demo-sidekiq`) time
+   to process, then re-check rather than asserting immediately. `demo:all` runs heavy
+   background tasks back-to-back (`map`'s ~30 jobs, `ar`'s ~100 product jobs, the lock/
+   semaphore/coordination holds) — an async/await step later in the chain (e.g.
+   `async_step_demo`, `async_reactor_demo`) can hit `async_wait_timeout` purely from
+   Sidekiq queue backlog, not a real bug. Before reporting an async timeout as a finding,
+   re-run that one task in isolation (`bin/rails demo:<task>`) once the queue has drained
+   — if it passes clean alone, it's a demo-ordering/concurrency artifact (note it under
+   Suggestions, e.g. "raise Sidekiq concurrency" or "reorder demo:all"), not a code bug.
+
+### Splitting the run across agents (avoid context overload)
+
+For `demo:all` (or any multi-task scope), don't run Steps 2-5 for every task in one
+context — the full run is ~19 tasks / 80+ scenarios and will blow past a useful context
+budget long before the report is written. Instead:
+
+1. Do Step 1 (stack up) and a first pass of Step 2 yourself: skim
+   `demo_reactors.rake` and `git status`/`git log` for the reactors involved to identify
+   which ones are new/actively-changing right now (untracked files, recent commits touching
+   `app/reactors/`) — those get priority full-depth verification.
+2. Group the remaining tasks (e.g. by rake task, or a few related tasks per group) and
+   fan them out to parallel background agents, each self-contained: give it the exact
+   `docker compose exec` command, the port, which reactors/tasks it owns, the acceptance-
+   criteria method from Step 2, and the Step 4/5 validation + fix instructions verbatim.
+   Tell each agent explicitly which scenarios warrant full API depth-check (`GET .../<id>`
+   against every field) versus which can be validated via stdout markers plus a 1-2
+   scenario spot-check — exhaustively hitting the API for every scenario in a large group
+   is what overloads context, not running the scenarios themselves.
+3. Have each agent write its own findings; collect and merge into the single report in
+   Step 6 yourself (or have one agent own the merge) rather than re-deriving everything in
+   your own context.
+
+## Step 4: Validate against both data sources
+
+For every scenario captured in Step 3, check it against **both**:
+
+**(a) The API** (`http://localhost:<port>/ruby_reactor/api/reactors`):
+- `GET /ruby_reactor/api/reactors` — list; confirm the run's reactor/context appears.
+  Known limitation to watch for: the storage adapter's `scan_reactors` caps at `count: 50`
+  via Redis `SCAN` with no chronological ordering — on a run with 50+ total executions
+  (e.g. `demo:all`), some earlier ones can be genuinely absent from the list endpoint even
+  though `GET .../<id>` finds them directly by id. Don't assume "missing from the list" ==
+  "reactor didn't run" — try the direct id lookup before concluding it's a bug, but if it
+  IS a real gap, it's a known gem-level finding (no `limit`/`cursor` param threaded through
+  `lib/ruby_reactor/web/api.rb` → `lib/ruby_reactor/storage/redis_adapter.rb` `scan_reactors`).
+- `GET /ruby_reactor/api/reactors/<id>` — confirm `status`, `current_step`,
+  `execution_trace` (`steps`), `undo_stack`, `retry_count`/`step_attempts`, `error`,
+  `coordination`, and `structure` match the acceptance criterion from Step 2. Compare
+  step ordering and dependency edges against `structure`/`depends_on`, not just final
+  status.
+- **Cross-check the rake task's own printer branches against every outcome type the
+  reactor can actually produce**, not just its final API status. A common bug class here:
+  a `run_*` helper in the rake task branches on `DispatchResult` / `success?` / `failure?`
+  but is missing a `halted?` (or `skipped?`) branch, so a reactor that legitimately halts
+  (e.g. a dedup/period-lock halt, which is `Halt < Success`) falls through to the
+  `success?` branch and prints a misleading `✅ SUCCESS: nil` while the API correctly shows
+  `status: "halted"`. Read every `run_*`/`report_demo_result` helper the in-scope tasks use
+  and check its branch list covers everything the reactor's `signals`/return values allow.
+
+**(b) The dashboard** (`http://localhost:<port>/ruby_reactor`):
+- Confirm the root path serves the SPA (HTTP 200, HTML with its mount point) — a broken
+  dashboard build is itself a finding.
+- Where practical, fetch the same reactor's dashboard state the UI would render (it is
+  backed by the same API, so this mainly confirms the mount + asset pipeline are healthy
+  end-to-end, not just the API module in isolation). Note any divergence between what the
+  rake stdout claimed and what the API/dashboard actually recorded — that divergence is
+  the primary class of bug this skill hunts for.
+
+Also check for **coverage gaps**: any reactor in `demo_app/app/reactors/` with no
+corresponding rake task (nothing exercises it), and any acceptance criterion from Step 2
+that neither data source could confirm (e.g. no id was ever discoverable).
+
+## Step 5: For every bug found, propose a fix and a regression test
+
+A finding is not done at "here's what's wrong" — for each confirmed bug/error:
+
+1. **Root-cause it**: trace the mismatch to the actual code (a step's outcome, the API
+   serializer, storage, the dashboard build) rather than stopping at "API returned X,
+   expected Y". Name the file(s)/line(s) responsible.
+2. **Propose a concrete fix**: a diff-level description (or, if the fix is small and
+   unambiguous, apply it — see below) of what changes and why, referencing the gem's
+   principles (`.specify/memory/constitution.md`) where relevant (e.g. don't silently
+   widen behavior beyond what the demo actually needs).
+3. **Propose the regression test** that would have caught it, and place it correctly:
+   - **Bug in gem behavior** (executor, signals, storage, adapters, DSL, the `Web::API`
+     serializer, etc.) → a unit/integration spec under `spec/` (mirror the existing
+     layout, e.g. `spec/ruby_reactor/web/` for API bugs, `spec/ruby_reactor/executor/`
+     for execution-order bugs) using the gem's normal spec helpers — **not** the
+     `RubyReactor::RSpec` demo helpers, those are for `demo_app`.
+   - **Bug only reachable through the demo reactor's own definition, the rake task, or
+     dashboard integration** → a spec under `demo_app/spec/reactors/`, `type: :reactor`,
+     using only the built-in surface from `lib/ruby_reactor/rspec.rb` (see
+     `speckit-demo-tests` skill for the exact matcher/helper list and the "no hand-rolled
+     scaffolding" rule — apply the same constraint here).
+   - If the bug spans both (a gem defect that happens to surface via a demo reactor),
+     propose **both**: a gem-level spec pinning the underlying behavior, and a demo spec
+     confirming the demo reactor now reports it correctly.
+4. Do not apply gem-behavior fixes automatically without asking — surface them in the
+   report. You MAY apply a fix that is confined to `demo_app/` (a demo reactor, the rake
+   task, or a demo spec) directly if it's unambiguous, then note that it was applied and
+   re-verify it in this same run. Never silently skip proposing the regression test even
+   when you don't apply the fix itself.
+
+## Step 6: Write the report
+
+Write findings to `demo_app/tmp/demo_verification/<UTC timestamp>-report.md` (create the
+directory if needed; it's already gitignored via `demo_app/.gitignore`). Structure:
+
+```markdown
+# Demo App E2E Verification — <timestamp>
+
+## Scope
+<tasks/reactors run, port used, docker services status>
+
+## Acceptance criteria checked
+<the Step 2 list, one line per scenario>
+
+## Results
+| Reactor | Scenario | Rake output | API result | Dashboard | Verdict |
+|---|---|---|---|---|---|
+...
+
+## Errors found
+<concrete mismatches: expected vs actual, with the reactor/context id and relevant
+API JSON excerpt or rake stdout excerpt, plus root cause (file/line)>
+
+## Suggestions / improvements
+<non-broken but worth-fixing observations: missing rake coverage, confusing output,
+missing undo, etc.>
+
+## Fix plan
+<per error: ordered, concrete steps to resolve it — file(s) to touch, what changes,
+whether it was already applied — followed by the regression test proposed for it
+(file path + what it asserts) and whether it was added/passing>
+```
+
+Keep the table terse; put raw JSON/log excerpts in fenced code blocks under "Errors
+found", not inline in the table.
+
+## Step 7: Summarize to the user
+
+Report: report file path, pass/fail counts, and the top few errors (if any) inline —
+each with its proposed fix and regression test location — so the user doesn't have to
+open the file to know whether anything broke or what to do about it. If everything
+passed, say so plainly — don't manufacture findings. Do not tear down the docker services
+unless the user asks; mention they're still running.

data/.claude/skills/speckit-demo-tests/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: "speckit-demo-tests"
+description: "Generate the demo_app example reactor, rake task, and RSpec spec required by Constitution Principle VI for the current spec-kit feature, or for a context the user describes when no feature is active."
+argument-hint: "Optional: what to demo/test (required if no active speckit feature is detected)"
+compatibility: "Requires spec-kit project structure with .specify/ directory; writes into demo_app/"
+metadata:
+  author: "project"
+user-invocable: true
+disable-model-invocation: false
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Purpose
+
+Constitution Principle VI ("Demo-App Proof of Feature", `.specify/memory/constitution.md`)
+requires every feature to ship three artifacts together: an example reactor in
+`demo_app/app/reactors/`, a task entry in `demo_app/lib/tasks/demo_reactors.rake`, and a
+spec in `demo_app/spec/reactors/` written **only** with the built-in RSpec surface from
+`lib/ruby_reactor/rspec.rb`. This skill produces all three in one pass.
+
+## Step 1: Determine the context
+
+Try to detect the current spec-kit feature first; only fall back to the user for context
+if detection fails.
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --paths-only` from the repo
+   root and parse `FEATURE_DIR` and `BRANCH`.
+2. **Speckit detected** if `FEATURE_DIR` resolves to an existing directory under `specs/`
+   containing a `spec.md`. In that case:
+   - Read `spec.md` (and `plan.md`/`data-model.md` if present) in `FEATURE_DIR`.
+   - Extract the functional requirements (`FR-###`) and Given/When/Then acceptance
+     scenarios that describe observable, runnable behavior — the ones a reactor run can
+     demonstrate (happy path, a failure/compensation path, and any distinctive semantics
+     like pause/resume, skip, halt, retry).
+   - This extracted behavior is the context for Step 2. Do not ask the user anything
+     unless the spec is ambiguous about what a runnable example should exercise.
+3. **No speckit detected** (script fails, no `FEATURE_DIR`, or no `spec.md`) — the
+   feature being tested must come from the user:
+   - If `$ARGUMENTS` is non-empty, treat it as the context describing what to build a
+     demo/test for.
+   - If `$ARGUMENTS` is empty, use `AskUserQuestion` (or a plain question if that tool is
+     unavailable) to ask what reactor behavior/feature the demo and spec should cover.
+     Do not invent a feature — block here until the user answers.
+
+## Step 2: Study existing conventions before writing anything
+
+Read 1-2 existing examples so the new files match house style exactly:
+
+- One existing reactor from `demo_app/app/reactors/` whose shape is closest to the new
+  one (e.g. a failure/compensation demo, a background demo, an interrupt demo — pick by
+  relevance to the context from Step 1).
+- Its matching spec in `demo_app/spec/reactors/`.
+- The full built-in matcher/helper surface: skim `lib/ruby_reactor/rspec.rb` and its
+  `lib/ruby_reactor/rspec/*.rb` files (`helpers.rb`, `test_subject.rb`, `matchers.rb`,
+  `sidekiq_helpers.rb`, `async_test_helpers.rb`). Confirm the exact set currently
+  available — do not rely on a memorized list, the gem may have grown matchers since.
+- The tail of `demo_app/lib/tasks/demo_reactors.rake`, in particular the `desc "All demo
+  reactors"` / `task all: [...]` entry — the new task name must be appended to that
+  dependency list.
+
+## Step 3: Generate the example reactor
+
+Create `demo_app/app/reactors/<name>_reactor.rb` (snake_case file matching the
+`CamelCase` class name), where `<name>` is derived from the context (ask the user only
+if the right name is genuinely ambiguous). Requirements:
+
+- Class-based step definitions, matching Development Workflow conventions (no inline
+  lambdas as the primary authoring style).
+- Exercises the feature end-to-end: the happy path, and — where the feature has one — a
+  failure/compensation path, typically toggled via a `fail_at:`-style input like other
+  demo reactors already do.
+- If the feature under test is signal-specific (Halt, Skipped, retry veto, pause/resume,
+  locks, rate limits, periods), the example MUST produce that outcome observably (e.g. a
+  step that calls `halt!`/`skip!`/`fail!(..., retry: false)` under a controllable input),
+  not just something that happens to compile.
+- Do not duplicate an existing demo reactor's purpose — if one already covers this
+  behavior, extend it or say so instead of creating a near-duplicate file.
+
+## Step 4: Register the rake task
+
+Edit `demo_app/lib/tasks/demo_reactors.rake`:
+
+- Add a `desc "<Reactor> — <one-line of what it demonstrates>"` /
+  `task <name>: [:environment, :flush_redis] do ... end` block, following the existing
+  print-the-outcome pattern (`✅ SUCCESS`, `❌ FAILED`, `⏳ BACKGROUND`, etc. — match
+  whatever branch the existing tasks use for `DispatchResult`/`success?`/`failure?`).
+- Run through the same scenarios the spec will assert (e.g. loop over `fail_at`
+  values) so `rake demo:<name>` is a working live demonstration on its own.
+- Append `:<name>` to the `task all: [...]` dependency list so it runs as part of
+  `rake demo:all`.
+
+## Step 5: Write the spec using only the built-in RSpec surface
+
+Create `demo_app/spec/reactors/<name>_reactor_spec.rb`:
+
+- `RSpec.describe <ReactorClass>, type: :reactor do ... end`.
+- Build the subject with `test_reactor(described_class, inputs)` (see
+  `lib/ruby_reactor/rspec/helpers.rb`).
+- Use only the `TestSubject` API (`lib/ruby_reactor/rspec/test_subject.rb`) — e.g.
+  `mock_step`, `failing_at`, `map`, `composed`, `async_step`, `async_reactor`, `resume`,
+  `step_result`, `ensure_executed!`, `process_pending_jobs` — and only the matchers
+  defined in `lib/ruby_reactor/rspec/matchers.rb` (`be_success`, `be_failure`,
+  `have_run_step(...).after(...)`, `have_retried_step`, `have_validation_error`,
+  `be_paused`, `be_paused_at`, `have_ready_interrupts`, `be_halted`, `be_skipped`,
+  `be_locked`, `have_available_tokens`, `have_held_tokens`, `have_rate_limit_count`,
+  `be_period_marked`, and the ordered-lock matchers) plus `drain_async_jobs` /
+  `pending_async_jobs` from `sidekiq_helpers.rb` for async paths.
+- **Forbidden**: any direct `RubyReactor::Executor`/`Storage`/Redis call, manual Sidekiq
+  job draining, stubbing reactor internals, or any other hand-rolled scaffolding in this
+  spec file.
+- **If an assertion needs a matcher or helper that does not exist yet**: add it to the
+  appropriate file under `lib/ruby_reactor/rspec/` in this same change (with its own
+  unit coverage if the gem's own spec suite conventions call for it), then use it from
+  the demo spec. Do not work around the gap with ad-hoc internals — that is what
+  Principle VI explicitly forbids.
+- Cover at least: the happy path (`be_success`, step ordering via `have_run_step`), and
+  the failure/compensation or signal-specific path identified in Step 1.
+
+## Step 6: Validate
+
+Run, from `demo_app/`:
+
+- `bundle exec rspec spec/reactors/<name>_reactor_spec.rb` — must pass.
+- `bundle exec rake demo:<name>` — must run cleanly and print observable outcomes.
+- `bundle exec rubocop app/reactors/<name>_reactor.rb lib/tasks/demo_reactors.rake spec/reactors/<name>_reactor_spec.rb` (from the repo root, or wherever the project's rubocop config resolves) — fix violations before finishing.
+
+If any command fails, fix the generated files and re-run — do not report success on
+files that don't pass.
+
+## Step 7: Summarize
+
+Report to the user:
+
+- Files created/edited (reactor, rake task block + `all` list update, spec).
+- How to run the demo (`rake demo:<name>`) and the spec.
+- Whether any new matcher/helper was added to `lib/ruby_reactor/rspec/` and why.
+- Confirmation that validation (Step 6) passed.

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.6.0"
+  ".": "0.7.1"
 }

data/.specify/feature.json

@@ -1,3 +1,3 @@
 {
-  "feature_directory": "specs/001-cross-service-reactor-sagas"
+  "feature_directory": "specs/001-reactor-signal-semantics"
 }

data/.specify/memory/constitution.md

@@ -1,20 +1,25 @@
 <!--
 SYNC IMPACT REPORT
 ==================
-Version change: [unset] → 1.0.0 (MINOR: initial constitution, all principles defined from scratch)
+Version change: 1.1.0 → 1.2.0 (MINOR: Principle VI expanded with a 4th requirement —
+  docker-compose.yml currency + docker-run acceptance tests)
 
-Modified principles: N/A (first ratification)
+Modified principles:
+  - Principle VI: Demo-App Proof of Feature — added requirement 4, "Docker acceptance
+    run" (docker-compose.yml MUST track demo_app's services; demo: rake tasks are the
+    project's acceptance suite, runnable via `docker compose run`)
 
-Added sections:
-  - Core Principles (5 principles)
-  - Technical Constraints
-  - Development Workflow
-  - Governance
+Added sections: none (existing Principle VI section extended)
+
+Removed sections: none
 
 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
+  - .specify/templates/plan-template.md   ✅ Constitution Check gate is generic ("Gates determined
+                                             based on constitution file") — no edit required
+  - .specify/templates/spec-template.md   ✅ No principle-specific content — no edit required
+  - .specify/templates/tasks-template.md  ✅ Already covers demo-app polish tasks — no edit required
+  - .specify/templates/checklist-template.md ✅ Generic — no edit required
+  - .specify/extensions.yml               ✅ No before/after_constitution hooks registered
 
 Deferred TODOs: none
 -->
@@ -89,6 +94,58 @@ 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.
 
+### VI. Demo-App Proof of Feature (NON-NEGOTIABLE)
+
+Every user-facing feature or public API change MUST ship with a runnable example
+in `demo_app/`. Three artifacts are required together — a change is incomplete if
+any one is missing:
+
+1. **Example reactor**: a reactor (or step) demonstrating the feature MUST live in
+   `demo_app/app/reactors/`, one file per reactor, named `<snake_case>_reactor.rb`
+   matching its class name. The example MUST exercise the feature end to end —
+   including its failure and compensation path where the feature has one — and MUST
+   use class-based step definitions per the Development Workflow rule.
+2. **Rake entry**: the example MUST be registered as a task in
+   `demo_app/lib/tasks/demo_reactors.rake` under the `demo:` namespace, with a `desc`
+   line describing what it demonstrates, and depending on `[:environment, :flush_redis]`
+   so each run starts from clean Redis state. The task MUST print observable outcomes
+   (success, failure, background dispatch, pause) so an operator can verify behavior
+   without a debugger.
+3. **Spec**: a matching spec MUST live at
+   `demo_app/spec/reactors/<reactor>_spec.rb`, declared `type: :reactor`, and MUST use
+   **only** the built-in test surface exported by `lib/ruby_reactor/rspec.rb` — the
+   helpers (`test_reactor`, `drain_async_jobs`), the `TestSubject` API
+   (`mock_step`, `failing_at`, `map`, `composed`, `async_step`, `resume`,
+   `step_result`, `ensure_executed!`), and the matchers (`be_success`, `be_failure`,
+   `have_run_step(...).after(...)`, `have_retried_step`, `have_validation_error`,
+   `be_paused`, `be_paused_at`, `have_ready_interrupts`, `be_halted`, `be_skipped`,
+   `be_locked`, `have_available_tokens`, `have_held_tokens`, `have_rate_limit_count`,
+   `be_period_marked`, and the ordered-lock matchers).
+
+Hand-rolled test scaffolding is forbidden in `demo_app/spec/reactors/`: no direct
+`RubyReactor::Executor`/`Storage` calls, no bespoke Sidekiq draining, no manual Redis
+assertions, no stubbing of reactor internals. If an assertion cannot be expressed with
+the built-in surface, the missing matcher or helper MUST be added to
+`lib/ruby_reactor/rspec/` in the same change — extending the shared test API, not
+bypassing it.
+
+4. **Docker acceptance run**: `docker-compose.yml` MUST stay current with `demo_app`'s
+   runtime dependencies (Redis, Sidekiq, the Rails service itself) so that
+   `docker compose run --rm demo-app bin/rails demo:<task>` runs the new rake task
+   end to end against real Redis, with no manual setup beyond `docker compose up`.
+   A new demo service or environment variable required by a feature MUST be added to
+   `docker-compose.yml` in the same change. The `demo:` rake tasks in
+   `demo_app/lib/tasks/demo_reactors.rake` constitute the project's acceptance test
+   suite for user-facing behavior — CI or a release checklist MAY invoke them via
+   `docker compose run` to confirm the demo still passes before a MINOR/MAJOR release.
+
+**Rationale**: `demo_app/` is the only place the gem is consumed the way users consume
+it. An example that is written but never listed is never run; a spec written with
+private internals passes while the public API is broken. Forcing every feature through
+the public reactor DSL, a runnable rake task, and the shipped matchers means the
+documented API, the demo, and the test surface are validated by the same change — and
+gaps in the matcher library surface as work instead of as workarounds.
+
 ## Technical Constraints
 
 - **Ruby**: >= 3.0.0 required. No polyfills for older Rubies.
@@ -113,7 +170,17 @@ upgrade path predictable.
 - 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.
+  public API surface MUST be reflected there per Principle VI — example reactor in
+  `demo_app/app/reactors/`, rake task in `demo_app/lib/tasks/demo_reactors.rake`,
+  and a spec in `demo_app/spec/reactors/` using only the built-in RSpec matchers
+  and helpers from `lib/ruby_reactor/rspec.rb`.
+- PR reviews MUST reject any feature change whose demo example is missing, unlisted
+  in the rake file, or tested with hand-rolled scaffolding instead of the shipped
+  matcher library.
+- `docker-compose.yml` MUST be kept current with `demo_app`'s services (Redis,
+  Sidekiq, Rails) so `docker compose up` and `docker compose run --rm demo-app
+  bin/rails demo:<task>` are the supported way to run the `demo:` rake tasks as
+  acceptance tests, with no host-side Ruby/Redis setup required.
 
 ## Governance
 
@@ -131,4 +198,4 @@ 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
+**Version**: 1.2.0 | **Ratified**: 2025-10-02 | **Last Amended**: 2026-09-09

data/.specify/templates/tasks-template.md

@@ -158,6 +158,13 @@ Examples of foundational tasks (adjust based on your project):
 - [ ] TXXX Security hardening
 - [ ] TXXX Run quickstart.md validation
 
+**Constitution Principle VI — Demo-App Proof of Feature (required for any public API change):**
+
+- [ ] TXXX [P] Example reactor in `demo_app/app/reactors/<name>_reactor.rb`
+- [ ] TXXX Register `demo:<name>` task in `demo_app/lib/tasks/demo_reactors.rake` (desc + `[:environment, :flush_redis]`)
+- [ ] TXXX Spec in `demo_app/spec/reactors/<name>_reactor_spec.rb` (`type: :reactor`), using only built-in matchers/helpers from `lib/ruby_reactor/rspec.rb`
+- [ ] TXXX If an assertion needs a matcher that does not exist, add it to `lib/ruby_reactor/rspec/` — never bypass the shared test API
+
 ---
 
 ## Dependencies & Execution Order