job-workflow 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9474c65583cf21d485c3468675d4f23124e60e88f98c954bd38256b916d98ffe
-  data.tar.gz: 59d5e0b60a2b52e87ea4da4aab1834d02c63f88cba36f661acd8c74f89a4e6a9
+  metadata.gz: '08ad79c285a78a258aaafdf2cca6141982291f52c00a7c95412a7df728f96217'
+  data.tar.gz: 4fba62aa4a507ab75f8fb33ac21b1fadaa409452f985be9e1eedff0a010a3614
 SHA512:
-  metadata.gz: 4ac034e1b373b28aa52dcffd059bc5b64e5c45fc04d9b07460c24491c2514eabddf839b2dcb2c4a2cfbf36b578e2836e153e9bd6f34cd24f8af543cf06242ce9
-  data.tar.gz: 455b6913137103b6a5871562a6adc0ffca11e9e99543b94ec7e0bda9f2b78c6c76c5cee73baec30ca5b5b5e2fd388d6a4b119c08d7cf1039c20e115e255f58d7
+  metadata.gz: 5b079b1bb1b534b9952de0b431d6fac1658e9581ea30d22cbe5b0737e7c7748f78af68a46880500d8c3da9edc51bf5b4e558adf568ae1f0ce014cf77bd336ab8
+  data.tar.gz: fc2a98038a737cd4bc47c4f029bc2df17d55ec6d2ce16ca031f14a84cce8ac5a9418f20b18fc8174a2e157b74488557e4335bbed9afe71582141adc97ea28a00

data/.agents/instructions/coding-style.md

@@ -0,0 +1,38 @@
+# Coding Style
+
+## Primary sources of truth
+
+- `.rubocop.yml` for Ruby style, complexity, and naming constraints
+- `Steepfile`, `rbs_collection.yaml`, and inline RBS usage for type-checking expectations
+- `.github/copilot-instructions.md` for repository-specific design and testing rules
+
+## Mechanical style constraints
+
+- Ruby string literals use double quotes.
+- RuboCop line length is capped at 120 characters.
+- The repository excludes `examples/**/*` from the root RuboCop config because the example app validates itself separately.
+
+## Design rules
+
+- Keep code small and focused on a single responsibility.
+- Prefer composable behavior over large monolithic methods.
+- Favor immutable workflow inputs through `Arguments`.
+- Use `Output` as the main way to communicate task side effects and downstream data.
+- Preserve clear boundaries between `Workflow`, `Task`, and `Runner`.
+- Avoid breaking public APIs without a documented migration or deprecation path.
+
+## Type and signature rules
+
+- Prefer `rbs-inline` comments in implementation files when type information changes.
+- Do not edit generated `.rbs` files or `sig/` artifacts directly unless maintainers explicitly approve it.
+
+## Test-adjacent implementation rules
+
+- Add only the code necessary for the requested behavior and its directly related fixes.
+- Reuse existing helpers and patterns before adding new abstractions.
+- Comment code only when the behavior is non-obvious.
+- Do not change established naming conventions without approval.
+
+## Unconfirmed items
+
+- Any additional hand-written naming rules beyond Ruby conventions and RuboCop enforcement

data/.agents/instructions/domain.md

@@ -0,0 +1,37 @@
+# Domain
+
+## Repository purpose
+
+JobWorkflow is a workflow orchestration library for Ruby on Rails applications. It provides a declarative DSL on top of ActiveJob so applications can define task graphs, dependencies, fan-out work, retries, throttling, and monitoring.
+
+## Core concepts
+
+- `Workflow`: the ordered graph of tasks for a job class
+- `Task`: one unit of work in a workflow, optionally depending on other tasks
+- `Arguments`: immutable workflow inputs exposed to tasks through `Context`
+- `Context`: the task-facing object used to read arguments, outputs, runtime helpers, and execution state
+- `Output`: the structured result store for completed task outputs
+- `Runner`: the orchestration layer that executes tasks and updates workflow state
+- `SubTaskJob`: the dedicated async job class used for `enqueue: true` fan-out work
+- `WorkflowStatus` / `JobStatus`: read models for workflow and sub-task execution state
+- Monitoring UI: the Rails engine that visualizes workflow definitions and execution DAGs
+
+## Common terminology
+
+- `each task`: a task that fans out over a collection
+- `dependency_wait`: waiting behavior for dependent async work
+- `fan-out`: splitting work into sub-jobs
+- `root execution`: the top-level workflow job, excluding sub-task jobs
+
+## Detailed references
+
+- `guides/GETTING_STARTED.md` for the high-level workflow model
+- `guides/DSL_BASICS.md` for task definitions and dependency rules
+- `guides/TASK_OUTPUTS.md` for output flow and downstream consumption
+- `guides/PARALLEL_PROCESSING.md` for fan-out and aggregation behavior
+- `guides/WORKFLOW_STATUS_QUERY.md` for workflow vs job status read models
+- `guides/MONITORING_UI.md` for the monitoring view of root executions and sub-task jobs
+
+## Unconfirmed items
+
+- Additional external domain vocabulary used by downstream adopters

data/.agents/instructions/environment.md

@@ -0,0 +1,44 @@
+# Environment
+
+## Required local tools
+
+- Ruby and Bundler for gem development
+- SQLite3 for local development and the example app
+- A shell environment that can run the root and example-app Rake tasks
+
+## Root setup
+
+```bash
+bin/setup
+bundle install
+bundle exec rake rbs:install
+```
+
+## Example app setup
+
+From `examples/rails_8_1/`:
+
+```bash
+bundle install
+bundle exec rails db:prepare
+bundle exec rake rbs:install
+```
+
+## Running the example app
+
+- Start the Rails server from `examples/rails_8_1/` with `bin/rails server`
+- Start background job processing with `bin/jobs`
+- Open `/job_workflow` for the monitoring UI and `/jobs` for Mission Control Jobs in the example app
+- For a denser monitoring DAG preview, enqueue `AcceptanceComplexMonitoringDagJob` from `examples/rails_8_1/`
+
+## Useful notes
+
+- The example app is the main place to verify real monitoring UI behavior.
+- The example app has its own lockfile and validation commands; treat it as an additional maintained surface.
+- Use `examples/rails_8_1/README.md` for the full preview sequence.
+- Use `guides/GETTING_STARTED.md` for first-time library setup and `guides/MONITORING_UI.md` for monitoring behavior.
+
+## Unconfirmed items
+
+- Preferred Ruby version manager for maintainers
+- Any editor or shell configuration the team expects

data/.agents/instructions/general.md

@@ -0,0 +1,29 @@
+# General
+
+## Core behavior
+
+- Respond to repository collaborators in Japanese, even though these agent resource files are written in English.
+- Interpret user instructions literally and keep changes scoped to the requested task.
+- Ask for clarification before making risky, ambiguous, or behavior-changing edits.
+- Prefer existing repository conventions over personal defaults.
+
+## Always do
+
+- Read the relevant repository context before editing.
+- Keep changes focused and avoid unrelated cleanup.
+- Report what changed, what was validated, and any unresolved points when finishing work.
+
+## Do not do
+
+- Do not create unrelated refactors while working on a user request.
+- Do not assume undocumented behavior when repository sources do not confirm it.
+- Do not treat generated signatures in `sig/generated/` as the primary editing surface.
+
+## Communication
+
+- Use concise Japanese in user-facing chat.
+- State uncertainty explicitly instead of presenting guesses as facts.
+
+## Unconfirmed items
+
+- Additional organization-wide communication rules beyond this repository

data/.agents/instructions/security.md

@@ -0,0 +1,20 @@
+# Security
+
+## Secrets and sensitive data
+
+- Do not commit API keys, tokens, passwords, private keys, or other secrets.
+- Stop and ask if a value looks like a secret or production credential.
+
+## Restricted operations
+
+- Do not modify files outside the repository root.
+
+## Dependency and code safety
+
+- Prefer existing repository dependencies and tools over introducing new ones.
+- Avoid risky shell operations, destructive git commands, and history rewriting unless explicitly requested.
+- Surface errors instead of silently swallowing them.
+
+## Unconfirmed items
+
+- External secret-management system used by maintainers

data/.agents/instructions/structure.md

@@ -0,0 +1,43 @@
+# Structure
+
+## Repository layout
+
+```text
+.
+├── app/                     # Rails engine assets for the monitoring UI
+├── bin/                     # executable helpers
+├── config/                  # Rails engine and routing configuration
+├── examples/rails_8_1/      # acceptance Rails application used to verify integration
+├── guides/                  # user-facing documentation
+├── lib/                     # main JobWorkflow library code
+├── sig/                     # generated signatures and type artifacts
+├── sig-private/             # private type definitions used by Steep
+├── spec/                    # main RSpec suite
+├── .agents/instructions/    # agent instructions files referenced from AGENTS.md
+└── AGENTS.md                # root agent entry point
+```
+
+## Key areas
+
+- `lib/job_workflow/` holds the core DSL, runtime, adapters, monitoring models, and version file.
+- `lib/job_workflow/monitoring/` contains monitoring presenters, registries, and layout helpers.
+- `app/` and `config/routes.rb` support the monitoring UI engine.
+- `examples/rails_8_1/` is a separate validation surface with its own Rake tasks, lockfile, and specs.
+- `examples/rails_8_1/app/jobs/` contains acceptance workflow definitions.
+- `examples/rails_8_1/spec/jobs/` contains acceptance and integration-oriented example-app specs.
+- `guides/` is the documentation index for feature and operational guides.
+
+## Structure expectations
+
+- Treat this repository as a single package with an embedded example application, not as a monorepo of independent packages.
+- Keep agent-wide documentation at the root unless a future task explicitly introduces subdirectory-specific AGENTS.md files.
+
+## Documentation entry points
+
+- Start with `guides/README.md` to find the right feature guide.
+- Use `guides/MONITORING_UI.md` for monitoring-specific behavior.
+- Use `examples/rails_8_1/README.md` for example-app setup and preview flows.
+
+## Unconfirmed items
+
+- Whether additional future example applications should get their own AGENTS.md

data/.agents/instructions/tech-stack.md

@@ -0,0 +1,40 @@
+# Tech Stack
+
+## Languages and frameworks
+
+- Ruby `>= 3.1.0` for the gem runtime
+- Rails and ActiveJob for the workflow runtime and monitoring engine integration
+- Solid Queue in the example app for asynchronous execution scenarios
+- SQLite in local and example-app development flows
+- RBS Inline plus Steep for type checking
+- RSpec for tests
+- RuboCop with repository plugins for linting
+- SimpleCov for 100% line and branch coverage enforcement
+
+## Primary commands
+
+- Root validation:
+  - `bundle exec rake spec`
+  - `bundle exec rake lint`
+  - `bundle exec rake typecheck`
+- Useful root helpers:
+  - `bundle exec rake lint:fix`
+  - `bundle exec rake lint:fixall`
+  - `bundle exec rake rbs:install`
+  - `bundle exec rake rbs:update`
+  - `bundle exec rake rbs:inline`
+- Example app validation from `examples/rails_8_1/`:
+  - `bundle exec rake spec`
+  - `bundle exec rake lint`
+  - `bundle exec rake typecheck`
+
+## Architecture summary
+
+- `Workflow`, `Task`, `Runner`, `Arguments`, `Context`, and `Output` form the core execution model.
+- Queue adapters isolate runtime-specific job lookup and persistence behavior.
+- Monitoring code lives under `lib/job_workflow/monitoring/` and is rendered through the Rails engine in `app/`.
+- The example Rails app is the main integration harness for real ActiveJob and Solid Queue behavior.
+
+## Important command rule
+
+- Use the repository Rake tasks instead of calling `rspec`, `rubocop`, or `steep` directly for final validation.

data/.agents/instructions/testing.md

@@ -0,0 +1,46 @@
+# Testing
+
+## Required validation
+
+- Every functional change must include new or updated specs that cover the changed behavior.
+- Root repository changes must pass:
+  - `bundle exec rake spec`
+  - `bundle exec rake lint`
+  - `bundle exec rake typecheck`
+- Root coverage must remain at `100%` line coverage and `100%` branch coverage.
+
+## Example app validation
+
+- If a change touches `examples/rails_8_1/`, also run inside that directory:
+  - `bundle exec rake spec`
+  - `bundle exec rake lint`
+  - `bundle exec rake typecheck`
+- Example app coverage must also stay at `100%` line coverage and `100%` branch coverage.
+
+## Validation scope
+
+- If the change only touches root library, engine, guides, or specs outside `examples/rails_8_1/`, run the root validation set.
+- If the change touches both root code and `examples/rails_8_1/`, run both validation sets.
+- If the change alters behavior, update the relevant guide examples as well as tests.
+
+## Test-writing rules
+
+- Use `bundle exec rake spec`, not `bundle exec rspec`.
+- Define a named subject with `subject(:name)`.
+- Keep `describe` / `context` nesting at three levels or fewer.
+- Prefer one expectation per example unless a matcher like `have_attributes` or a combined matcher makes the assertion a single behavior check.
+- Test through public APIs only; do not use `instance_variable_set`, `instance_variable_get`, or similar reflection in specs.
+- Keep `let` usage lean and split contexts when conditions differ.
+
+## Completion rule
+
+- Do not report a code change as ready until the required validation commands for the touched surfaces have succeeded.
+
+## Reference material
+
+- Use `guides/TESTING_STRATEGY.md` for testing guidance beyond the mandatory checks.
+- Use `guides/MONITORING_UI.md` and feature-specific guides when behavior-oriented expectations need clarification.
+
+## Unconfirmed items
+
+- Whether any additional external CI jobs run outside the repository-local Rake tasks

data/.agents/instructions/workflow.md

@@ -0,0 +1,39 @@
+# Workflow
+
+## Branches
+
+- Use a dedicated branch for work.
+- Preferred branch prefixes are `feature/<short-desc>` and `fix/<short-desc>`.
+
+## Commits
+
+- Use Conventional Commits in `type(scope): short summary` format.
+- Valid types include `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, and `perf`.
+- Keep the subject line within 72 characters.
+- Update `CHANGELOG.md` before creating a commit when the change should be reflected in release notes.
+
+## Pull requests
+
+- Keep one PR focused on one logical change.
+- PR creation and merge are normally done by the user unless they explicitly delegate that step.
+- A completion handoff should include validation results, coverage, lint status, typecheck status, major changed files, and any recommended follow-up.
+
+## Before changing behavior
+
+- Check `guides/README.md` first to find the relevant feature guide.
+- Use feature guides such as `guides/DSL_BASICS.md`, `guides/TASK_OUTPUTS.md`, `guides/PARALLEL_PROCESSING.md`, `guides/DEPENDENCY_WAIT.md`, and `guides/MONITORING_UI.md` before changing semantics in those areas.
+
+## Release preparation
+
+- Record shipped changes in `CHANGELOG.md`, starting from `## [Unreleased]` before they are cut into a release section.
+- Keep version-related files in sync when preparing a release.
+
+## Review expectations
+
+- Explain why a change is necessary.
+- Keep PRs small enough to review without mixing unrelated work.
+
+## Unconfirmed items
+
+- Reviewer assignment rules outside the repository instructions
+- Whether release tagging always happens from `main`

data/.rubocop.yml

@@ -41,7 +41,7 @@ Metrics/BlockLength:
 Metrics/ClassLength:
   Enabled: true
   CountComments: false
-  Max: 100
+  Max: 124
   CountAsOne:
     - array
     - hash
@@ -88,4 +88,3 @@ Style/StringLiteralsInInterpolation:
 
 ThreadSafety/ClassAndModuleAttributes:
   Enabled: false
-

data/AGENTS.md

@@ -0,0 +1,23 @@
+# AGENTS.md
+
+This repository uses AGENTS.md as a thin hub. Read the required instructions files before making changes.
+
+## Required instructions
+
+- @.agents/instructions/general.md
+- @.agents/instructions/structure.md
+- @.agents/instructions/tech-stack.md
+- @.agents/instructions/security.md
+- @.agents/instructions/testing.md
+- @.agents/instructions/workflow.md
+
+## Load when needed
+
+- .agents/instructions/domain.md — JobWorkflow concepts and terminology
+- .agents/instructions/environment.md — local setup and example app workflow
+- .agents/instructions/coding-style.md — design rules, style constraints, and implementation patterns
+
+## Repository notes
+
+- Repository-specific reusable agent assets should live under `.agents/skills/`.
+- No subdirectory-level AGENTS.md files are defined at the moment. Use this root entry point unless a later task adds a more specific AGENTS.md.

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 ## [Unreleased]
 
+## [0.6.1] - 2026-06-01
+
+### Fixed
+
+- Fix monitoring UI task state rendering so tasks recorded as completed in ActiveJob continuation data no longer appear as `pending` when they have no outputs or sub-task statuses
+
+## [0.6.0] - 2026-05-24
+
+### Added
+
+- Add `JobWorkflow::SubTaskJob` for `enqueue: true` task fan-out so each-task sub-jobs run on a dedicated job class instead of reusing the workflow DSL job class directly
+- Add a JobWorkflow monitoring UI engine with an execution DAG overview for browsing workflow definitions, root executions, DAG state, arguments, outputs, fan-out progress, and linked Mission Control Jobs rows
+
+### Changed
+
+- **Breaking:** `WorkflowStatus.find` / `find_by` are now root-workflow-only APIs. Sub-task job IDs are excluded and should be tracked via `JobStatus`.
+
+### Fixed
+
+- Route enqueued each-task execution through `SubTaskJob`, restoring workflow/task context from the parent workflow job and keeping parent/sub-job identity separate during async execution
+- Extend queue-adapter and workflow-status hydration so monitoring can paginate root workflow executions, hydrate sub-task detail on demand, and keep partially completed fan-out tasks visible as `running` until the workflow actually settles
+
+### Removed
+
+- Remove `enqueue: { concurrency: N }`. Async map task fan-out is still controlled by `enqueue`, but execution caps are now configured exclusively with `throttle`.
+
 ## [0.5.0] - 2026-05-13
 
 ### Added

data/README.md

@@ -1,6 +1,6 @@
 # JobWorkflow
 
-> ⚠️ **Early Stage (v0.5.0):** This library is in active development. APIs and features may change in breaking ways without notice. Use in production at your own risk and expect potential breaking changes in future releases.
+> ⚠️ **Early Stage (v0.6.1):** This library is in active development. APIs and features may change in breaking ways without notice. Use in production at your own risk and expect potential breaking changes in future releases.
 
 ## Overview
 

data/app/controllers/job_workflow/monitoring/application_controller.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  module Monitoring
+    # Resolve the host app controller at load time so engine controllers inherit
+    # the app's existing authentication and access control hooks.
+    class ApplicationController < JobWorkflow::Monitoring.resolved_base_controller_class.constantize
+      layout "job_workflow/monitoring/application"
+    end
+  end
+end

data/app/controllers/job_workflow/monitoring/executions_controller.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  module Monitoring
+    class ExecutionsController < ApplicationController
+      def index
+        @workflow = WorkflowRegistry.find(params[:workflow_job_class_name])
+        return render plain: "Workflow definition not found.", status: :not_found if @workflow.nil?
+
+        @page = ExecutionRegistry.page_for(
+          job_class_name: @workflow.name,
+          cursor: params[:cursor]
+        )
+        @executions = @page.executions
+      end
+
+      def show
+        @workflow = WorkflowRegistry.find(params[:workflow_job_class_name])
+        return render plain: "Workflow definition not found.", status: :not_found if @workflow.nil?
+
+        @execution = ExecutionRegistry.find(params[:id])
+        return if @execution && @execution.job_class_name == @workflow.name
+
+        render plain: "Workflow execution is no longer available.", status: :not_found
+      end
+    end
+  end
+end

data/app/controllers/job_workflow/monitoring/workflows_controller.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  module Monitoring
+    class WorkflowsController < ApplicationController
+      def index
+        @workflows = Monitoring.workflows
+      end
+    end
+  end
+end

data/app/views/job_workflow/monitoring/executions/index.html.erb

@@ -0,0 +1,57 @@
+<section class="d-flex flex-column flex-lg-row justify-content-between align-items-lg-end gap-3 mb-4">
+  <div>
+    <div class="text-body-secondary small mb-1">Workflow</div>
+    <h1 class="display-6 fw-semibold mb-2"><%= @workflow.name %></h1>
+    <p class="text-body-secondary mb-0">Paginated root executions. sub task jobs appear only inside execution detail.</p>
+  </div>
+  <div>
+    <%= link_to "Back to workflows", root_path, class: "btn btn-outline-secondary" %>
+  </div>
+</section>
+
+<div class="card jw-card">
+  <div class="card-body p-0">
+    <% if @executions.empty? %>
+      <div class="p-4 text-body-secondary">No currently available workflow executions.</div>
+    <% else %>
+      <div class="table-responsive">
+        <table class="table table-hover align-middle mb-0">
+          <thead class="table-light">
+            <tr>
+              <th class="ps-4">Status</th>
+              <th>Current task</th>
+              <th>Queue</th>
+              <th>Job</th>
+              <th class="text-end pe-4">Detail</th>
+            </tr>
+          </thead>
+          <tbody>
+            <% @executions.each do |execution| %>
+              <% status_class = case execution.workflow_status
+                               when :succeeded then "text-bg-success"
+                               when :failed then "text-bg-danger"
+                               when :running then "text-bg-primary"
+                               else "text-bg-secondary"
+                               end %>
+              <tr>
+                <td class="ps-4"><span class="badge <%= status_class %>"><%= execution.workflow_status %></span></td>
+                <td><%= execution.current_task_name || "-" %></td>
+                <td><span class="jw-mono"><%= execution.queue_name || "-" %></span></td>
+                <td class="jw-mono"><%= execution.job_id %></td>
+                <td class="text-end pe-4">
+                  <%= link_to "Open", workflow_execution_path(@workflow.name, execution.job_id), class: "btn btn-sm btn-primary" %>
+                </td>
+              </tr>
+            <% end %>
+          </tbody>
+        </table>
+      </div>
+    <% end %>
+  </div>
+</div>
+
+<% if @page.next_cursor %>
+  <div class="d-flex justify-content-end mt-3">
+    <%= link_to "Next page", workflow_executions_path(@workflow.name, cursor: @page.next_cursor), class: "btn btn-outline-primary" %>
+  </div>
+<% end %>