Design: Task lifecycle events, states, and observer notification system

[ahogappa]

Summary

Define Taski's event and state model clearly to provide a consistent observer notification system for progress displays, logging, and user hooks.

Prerequisites: This issue assumes the following are already completed:

• Fiber-based lazy dependency resolution #155 (Fiber-based lazy dependency resolution) — Section API removed, Fiber executor in place
• Simplify progress display configuration by removing environment variables #146 (Simplify progress display configuration) — Environment variables removed
• Simplify clean API: remove standalone Task.clean and Task.new, add block support to run_and_clean #158 (Simplify clean API) — Task.clean / Task.new removed, run_and_clean block support added

---

State Diagrams

Run Phase

stateDiagram-v2
    [*] --> pending

    pending --> running : task starts
    pending --> skipped : not executed

    running --> completed : success
    running --> failed : error

    completed --> [*]
    failed --> [*]
    skipped --> [*]

Loading

Clean Phase

stateDiagram-v2
    [*] --> pending

    pending --> running : clean starts

    running --> completed : success
    running --> failed : error

    completed --> [*]
    failed --> [*]

Loading

---

Unified State Set

Both Run and Clean phases use the same state names:

State	Description
pending	Initial state, waiting to be executed
running	Task is currently executing
completed	Task finished successfully
failed	Task finished with error
skipped	Task was not executed (Run phase only)

skipped Reasons

The skipped state means "this task was not executed." The reason can be determined by observers via Pull (checking dependency graph and dependency states):

• Not accessed at runtime: Static analysis detected the task as a possible dependency, but the runtime code path never accessed it (e.g., if branch not taken, rescue block not entered). This is a natural result of Fiber-based lazy resolution — only actually accessed dependencies are executed.
• Dependency failed: A task this depends on failed, so this task could not run

This keeps skipped as a simple factual statement ("not executed") rather than encoding the reason in the state.

Removed States

• enqueued / clean_enqueued: Removed. The current Scheduler uses enqueued as an intermediate state, but running is sufficient. Once a task begins execution, it is considered running.

Clean State Unification

The current clean states (:cleaning, :clean_completed, :clean_failed) are unified to use the same names as run states (:running, :completed, :failed). The phase context (:run or :clean) distinguishes which phase the state belongs to.

Clean State Special Case

• nil: Tasks that were skipped or failed in Run phase don't have a Clean phase

---

Push/Pull Pattern

Push (Notification)

Notify identifiers, state transition, phase, and timestamp:

notify_task_updated(task_class, previous_state:, current_state:, phase:, timestamp:)

All transient/mutable information is pushed. The facade itself holds zero mutable domain state.

Pull (Query)

Any component that needs execution-related information pulls immutable data from ExecutionFacade:

facade.root_task_class         # Root task (immutable)
facade.dependency_graph        # DependencyGraph (immutable, single source for all dependency/tree data)
facade.output_stream.read(task_class, limit: nil)  # Captured output (accumulating)

ExecutionFacade is the single pull target — observers, Executor, and any other component that needs execution data should pull from here.

Design Principle: Stateless Facade

The facade holds no mutable domain state. The split is:

Type	Where	Examples
Mutable/transient	Push (in notifications)	phase, previous_state, current_state, timestamp
Immutable	Pull (from facade)	dependency_graph, root_task_class
Accumulating	Pull (from facade)	output_stream

Key Decisions

1. previous_state in notifications: Allows observers to determine state transitions directly

   • pending→running: Task started
   • pending→skipped: Task not executed (not accessed at runtime, or dependency failed)
   • running→completed: Success
   • running→failed: Error

2. phase in notifications: Included in every task_updated so observers always know which phase a state transition belongs to, without needing to track phase state themselves. Eliminates facade.current_phase as mutable state.

3. state_for is unnecessary: State is pushed via notification

4. No error in notifications: Error details (message, backtrace) are logged via a direct path from Executor → Taski::Logging, not through the observer notification system. Ruby's standard exception propagation handles user-facing error display at the top level. Including error in the notification would create inconsistent signatures — pending→running and pending→skipped transitions have no error, only running→failed does.

5. No duration in notifications: Duration is not a fundamental piece of data — it's derived from timestamps. Observers calculate duration themselves:

   • Record timestamp on pending→running transition
   • Compute duration = timestamp - start_time on running→completed/failed transition

   This keeps the notification signature clean and uniform across all transitions. TaskTiming in TaskWrapper (which existed solely to calculate and pass duration_ms to observers) is removed.

6. All task candidates known before execution: Static analysis detects all possible task candidates including their dependency trees. The only thing determined at runtime is which tasks are NOT executed (skipped) — this is determined by Fiber-based lazy resolution (only accessed dependencies execute).

7. Single DependencyGraph: The dependency graph and tree display metadata are derived from the same static analysis data. Instead of maintaining two separate structures (dependency_graph + task_tree), a single DependencyGraph serves as the sole source for all dependency and tree-related queries. Layout observers derive display metadata (depth, position, tree prefixes) from the graph — the graph itself does not carry display concerns.

---

Event Catalog (8 Events)

Category	Events	Count
Lifecycle	ready, start, stop	3
Phase	phase_started(phase), phase_completed(phase)	2
Task	task_updated	1
Group	group_started, group_completed	2

Event Signatures

# Lifecycle (3)
notify_ready()                # Preparation complete (Pull for root_task, graph, all tasks)
notify_start()
notify_stop()

# Phase (2)
notify_phase_started(phase)   # phase = :run or :clean
notify_phase_completed(phase)

# Task (1)
notify_task_updated(task_class, previous_state:, current_state:, phase:, timestamp:)

# Group (2)
notify_group_started(task_class, group_name, phase:, timestamp:)
notify_group_completed(task_class, group_name, phase:, timestamp:)

Execution Order

ready → start → phase_started(:run) → task_updated... → phase_completed(:run) → phase_started(:clean) → ... → phase_completed(:clean) → stop

Removed Events (vs current ExecutionContext)

• notify_task_registered → Removed (all task candidates known before execution via Pull at ready)
• notify_task_started / notify_task_completed / notify_task_skipped → Merged into notify_task_updated
• notify_clean_started / notify_clean_completed → Merged into notify_task_updated with phase context
• notify_set_root_task / notify_set_output_capture → Merged into notify_ready

---

Observer Design

Base Class

class TaskObserver
  attr_accessor :context  # Pull window: ExecutionFacade provides immutable data

  # Methods to implement (8 types)
  def on_ready; end
  def on_start; end
  def on_stop; end
  def on_phase_started(phase); end
  def on_phase_completed(phase); end
  def on_task_updated(task_class, previous_state:, current_state:, phase:, timestamp:); end
  def on_group_started(task_class, group_name, phase:, timestamp:); end
  def on_group_completed(task_class, group_name, phase:, timestamp:); end
end

Usage Example

class MyLayout < TaskObserver
  def on_ready
    @graph = @context.dependency_graph       # Single source for all dependency/tree data
    @root = @context.root_task_class
    @start_times = {}
  end

  def on_task_updated(task_class, previous_state:, current_state:, phase:, timestamp:)
    case [previous_state, current_state]
    when [:pending, :running]
      @start_times[task_class] = timestamp
    when [:pending, :skipped]
      mark_skipped(task_class)
    when [:running, :completed], [:running, :failed]
      duration = timestamp - @start_times[task_class]
      render_completion(task_class, current_state, duration)
    end
  end
end

# ExecutionFacade auto-injects at registration
facade.add_observer(my_layout)
# → my_layout.context = self

---

ExecutionFacade

Architectural Intent

The core motivation of this refactoring is to consolidate scattered execution-related information into a single object. Currently, the dependency tree is built independently in multiple places (Scheduler, Layout::Base, etc.), and runtime information is spread across ExecutionContext, Scheduler, TaskWrapper, and Layout.

ExecutionFacade absorbs the current ExecutionContext and becomes the single source of truth for all execution-related information. It is created once per execution and referenced by any component that needs execution data.

Key insight: The dependency graph is immutable — it is built once from static analysis results and never changes during execution. What changes is each task's state, which is pushed via notifications. The facade itself holds no mutable domain state — all transient information (phase, state transitions, timestamps) flows through notifications.

Single DependencyGraph

Currently, dependency data is computed independently in multiple places:

• DependencyGraph — builds graph via Analyzer.analyze() recursively
• Layout::Base#build_tree_node — re-runs Analyzer.analyze() to build a tree
• Scheduler#build_dependency_graph — builds its own graph via BFS

These all derive from the same static analysis data. In the new design, DependencyGraph is the single data structure built once by ExecutionFacade. It provides:

• Graph queries: all_tasks, dependencies_for(task_class), sorted (topological order), cyclic?
• Tree traversal: parent-child relationships derived from the graph structure

Layout observers derive their own display metadata (depth, is_last flags, tree prefixes) from the graph in on_ready. The graph itself does not carry display concerns.

Initialization: Static Analysis → ExecutionFacade

ExecutionFacade receives static analysis results and builds the dependency graph at initialization:

# Static analysis is performed once
analysis_result = StaticAnalysis::Analyzer.analyze(root_task_class)

# ExecutionFacade builds the dependency graph from the analysis result
facade = ExecutionFacade.new(
  root_task_class: root_task_class,
  analysis_result: analysis_result,
  output_hub: output_hub
)
# Internally builds:
#   - dependency_graph  (single source: circular detection, execution order, tree traversal)

The graph is built once and frozen. Consumers pull what they need:

• Layout pulls dependency_graph and derives display metadata (depth, tree prefixes) in on_ready
• Any component pulls what it needs without rebuilding

Before:  Information scattered, static analysis re-run in multiple places
  Scheduler       → builds dependency graph (BFS from cached_dependencies)
  Layout::Base    → re-runs static analysis to build tree
                    TaskState class tracks per-task state (run_state, clean_state, duration, error)
  ExecutionContext → observer dispatch + output capture
  TaskWrapper     → state, timing, error

After:  Static analysis → ExecutionFacade builds DependencyGraph once
  StaticAnalysis::Analyzer.analyze(root)
        │
        ▼
  ExecutionFacade  (single source of truth, created once per execution)
  ├── dependency_graph    (immutable — single source for graph & tree queries)
  ├── root_task_class     (immutable)
  ├── output_stream       (OutputHub, accumulating)
  ├── observer notification dispatch (stateless — passes data through)
  └── NO mutable domain state
  
  Layout derives display metadata from dependency_graph in on_ready:
  └── depth, is_last, tree prefixes (computed once, stored in Layout)

  Referenced by:
  ├── Executor    → triggers notifications (phase, state transitions)
  ├── Layout      → receives notifications + pulls dependency_graph, output_stream
  └── any component that needs execution data

Note: This intentionally creates a fat model. The goal is to first gather all scattered information into one place, understand the full picture, and then decompose into well-separated components in a future refactoring.

API

class ExecutionFacade
  def initialize(root_task_class:, analysis_result:, output_hub:)
    @root_task_class = root_task_class
    @output_hub = output_hub

    # Build single immutable structure from static analysis
    @dependency_graph = build_dependency_graph(analysis_result)

    @observers = []
  end

  # --- Pull API (immutable data only) ---

  attr_reader :root_task_class      # Immutable
  attr_reader :dependency_graph     # Immutable — single source for all dependency/tree data

  def output_stream                 # Accumulating
    @output_hub
  end

  # --- Push API (stateless dispatch — no domain state stored) ---

  def add_observer(observer)
    observer.context = self
    @observers << observer
  end

  def notify_task_updated(task_class, previous_state:, current_state:, phase:, timestamp:)
    dispatch(:on_task_updated, task_class,
             previous_state:, current_state:, phase:, timestamp:)
  end

  # ... other notify_* methods

  private

  def dispatch(method, *args, **kwargs)
    @observers.each do |observer|
      observer.send(method, *args, **kwargs) if observer.respond_to?(method)
    end
  end
end

---

Output Handling

Design

Both stdout and stderr are captured (per-fiber scoping already implemented by #155):

Source	Destination	Captured
Task stdout (puts)	OutputHub	Yes
Task stderr (warn)	OutputHub	Yes
Layout/Progress display	original_stderr	No

OutputHub Implementation

class OutputHub
  MAX_RECENT_LINES = 30

  def store_output_lines(task_class, data)
    lines = data.lines.map(&:chomp)
    lines.each do |line|
      # Immediate log output
      Taski::Logging.output(task_class, line)

      # Store in ring buffer
      @ring_buffer[task_class] ||= []
      @ring_buffer[task_class] << line
      @ring_buffer[task_class] = @ring_buffer[task_class].last(MAX_RECENT_LINES)
    end
  end

  # Public API: read
  # limit: nil for entire buffer, or last N lines
  def read(task_class, limit: nil)
    lines = @ring_buffer[task_class] || []
    limit ? lines.last(limit) : lines
  end
end

Error Logging

Error details (message, backtrace) are logged via a direct path, not through the observer notification system:

# In Executor: when a task fails
rescue => error
  Taski::Logging.error(task_class, error)   # Direct path: log error details immediately
  wrapper.mark_failed(error)                 # Triggers notify_task_updated(state: :failed)
end

Data Flow	Path	Content
State transition	Observer notification (task_updated)	task_class, previous_state, current_state, phase, timestamp
Error details	Direct: Executor → Taski::Logging	Error message, backtrace, task class
Task output	Direct: OutputHub → Taski::Logging	stdout/stderr lines with task class

Responsibility

Class	Responsibility	Data	Public API
OutputHub	Capture + Log + Ring buffer	@ring_buffer (per task)	read(task_class, limit:)
Layout/Progress	Display only (Pull graph + notifications)	None	-
LoggerObserver	Event logging (state transitions only)	None	-

---

Two Types of Dependencies

Type	Purpose	Implementation	Characteristics
Static	Display, circular detection	StaticAnalysis::Analyzer.analyze()	Includes all possible dependencies from all code paths
Runtime	Actual execution	Fiber-based lazy resolution	Only actually accessed dependencies are executed

The gap between static and runtime dependencies is the set of skipped tasks. Static analysis detects all possible tasks; at runtime, Fiber lazy resolution only executes the ones actually accessed. The rest are marked skipped.

---

Removed Classes / Code

TaskTiming — Remove

The TaskTiming class in TaskWrapper (tracks start_time, end_time, calculates duration_ms) is removed. With the new design:

• Timing: Each task_updated notification includes timestamp:. Observers record the timestamp at pending→running and compute duration at running→completed/failed by calculating the difference.
• TaskTiming existed solely to calculate and pass duration_ms to observers. With timestamp-based notifications, this is no longer needed.
• Remove @timing and @clean_timing instance variables from TaskWrapper.

Layout::Base::TaskState — Remove

The current TaskState class in Layout::Base (tracks run_state, clean_state, run_duration, clean_duration, run_error, clean_error per task) is removed. With the new design:

• State: Pushed via task_updated notifications — each observer tracks what it needs
• Duration: Calculated by observers from timestamp in notifications
• Error: Logged via direct path (Executor → Taski::Logging), not stored per-task

Observers are responsible for maintaining their own view of task state based on notifications they receive.

Tree Building Code in Layout — Remove

All tree building and dependency analysis code must be removed from Layout classes. This logic is replaced by a single DependencyGraph built once by ExecutionFacade. Layout observers derive display metadata from the graph in on_ready.

Layout::Base — remove the following methods:

• build_tree_node — recursive tree node construction (replaced by dependency_graph)
• get_task_dependencies — calls StaticAnalysis::Analyzer.analyze() (re-runs static analysis)
• collect_all_dependencies / collect_dependencies_recursive — dependency collection
• on_root_task_set — no longer needed (replaced by on_ready pulling from Facade)
• set_root_task — no longer needed (root_task available via Facade Pull)
• @tasks hash (TaskState tracking) — observers track their own state
• apply_state_transition — replaced by unified task_updated notification handling

Layout::Simple — remove:

• build_tree_structure — orchestrates tree building
• register_tasks_from_tree — registers tasks from tree into @tasks
• on_root_task_set override

Layout::Tree — remove:

• build_tree_structure — orchestrates tree building
• register_tree_nodes — registers tree nodes with depth/position metadata
• on_root_task_set override
• Rebuild display metadata from facade.dependency_graph in on_ready

Scheduler#build_dependency_graph — Remove

Scheduler currently builds its own dependency graph via BFS from cached_dependencies. This is replaced by pulling dependency_graph from ExecutionFacade.

Scheduler state constants — Remove

• STATE_ENQUEUED / CLEAN_STATE_ENQUEUED: No longer needed (unified into running)

ExecutionContext — Remove (absorbed into ExecutionFacade)

All functionality (observer dispatch, output capture management) moves to ExecutionFacade. Individual notify_* methods are replaced by the unified event catalog.

Current methods to remove/merge:

• notify_task_registered → removed (Pull at ready)
• notify_task_started / notify_task_completed / notify_task_skipped → merged into notify_task_updated
• notify_clean_started / notify_clean_completed → merged into notify_task_updated
• notify_set_root_task / notify_set_output_capture → merged into notify_ready
• notify_start / notify_stop → kept as notify_start / notify_stop
• trigger_execution / trigger_clean / execution_trigger= / clean_trigger= → kept (execution coordination)
• THREAD_LOCAL_KEY / self.current / self.current= → updated (Fiber-local context)

---

Implementation Plan

Phase 1: Unify State Constants

• Remove STATE_ENQUEUED / CLEAN_STATE_ENQUEUED from Scheduler — unify into running
• Change clean state values in Layout::Base#apply_state_transition: :cleaning → :running, :clean_completed → :completed, :clean_failed → :failed
• Add phase context to distinguish run vs clean states

Phase 2: Introduce ExecutionFacade

• Create ExecutionFacade class absorbing ExecutionContext
• Receive static analysis result and build DependencyGraph at initialization (single source for all dependency and tree data)
• Add Pull API: root_task_class, dependency_graph, output_stream (all immutable/accumulating)
• Add Push API: stateless observer dispatch (migrated from ExecutionContext)
• Remove ExecutionContext (replaced by ExecutionFacade)

Phase 3: Unify Events

• Remove notify_task_registered (available via Pull at ready)
• Merge task events into notify_task_updated(task_class, previous_state:, current_state:, phase:, timestamp:)
• Merge notify_set_root_task, notify_set_output_capture into notify_ready
• Add notify_phase_started(phase) / notify_phase_completed(phase)

Phase 4: Introduce Observer Base Class

• Create TaskObserver base class
• Auto-inject context in add_observer

Phase 5: Pull-based Observer

• Layout inherits TaskObserver
• Use @context.dependency_graph in on_ready to derive display metadata (depth, is_last, tree prefixes)
• Remove all tree building code from Layout (see Tree Building Code in Layout — Remove)
• Remove TaskState class from Layout::Base (see Layout::Base::TaskState — Remove)
• Remove Scheduler#build_dependency_graph (see Scheduler#build_dependency_graph — Remove)

Phase 6: Remove TaskTiming

• Remove TaskTiming class from TaskWrapper
• Remove @timing and @clean_timing instance variables
• Observers use timestamp: from notifications to calculate duration

Phase 7: Add skipped State for Unaccessed Tasks

• After run phase completes, identify tasks detected by static analysis but never executed at runtime
• Mark these as :skipped via task_updated notification
• Mark tasks whose dependencies failed as :skipped

Phase 8: Output Processing

• Add OutputHub#read(task_class, limit: nil) method
• Expose facade.output_stream
• Centralize output routing through OutputHub

Phase 9: Update Tests

---

Critical Files

File	Role
lib/taski/execution/execution_facade.rb	ExecutionFacade: single source of truth (new, replaces execution_context.rb)
lib/taski/execution/execution_context.rb	To be removed (absorbed into ExecutionFacade)
lib/taski/execution/task_observer.rb	Observer base class (new)
lib/taski/execution/scheduler.rb	Remove build_dependency_graph, remove enqueued states (pulls from Facade instead)
lib/taski/static_analysis/analyzer.rb	Static analysis — results fed into ExecutionFacade
lib/taski/static_analysis/dependency_graph.rb	Single DependencyGraph structure (built by ExecutionFacade from analysis, provides graph & tree queries)
lib/taski/progress/layout/base.rb	Remove tree building, TaskState (display only, derives metadata from DependencyGraph)
lib/taski/progress/layout/simple.rb	Remove build_tree_structure, register_tasks_from_tree
lib/taski/progress/layout/tree.rb	Remove build_tree_structure, register_tree_nodes
lib/taski/execution/task_wrapper.rb	Remove TaskTiming, @timing, @clean_timing. State holder + state transition trigger
lib/taski/execution/executor.rb	Phase event trigger

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#55 - feat: add tree-based progress display for task execution [merged]
#65 - Introduce ExecutionContext to decouple progress display from Executor [merged]
#77 - feat: implement clean execution with reverse dependency order [merged]
#80 - refactor: improve run_and_clean implementation and display [merged]
#150 - Refactor: Move Layout/Template to Progress namespace with improved architecture [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Approach

• Create stateless ExecutionFacade as the single source of truth, absorbing and replacing ExecutionContext entirely - facade holds zero mutable domain state
• Build single immutable DependencyGraph (not separate task_tree or section_candidates) - Layout derives display metadata from graph in on_ready
• Consolidate to 8 events with task_updated(task_class, previous_state:, current_state:, phase:, timestamp:) including phase in every notification
• Unify state model: run and clean phases use same state values (:pending, :running, :completed, :failed), add :skipped state, remove :enqueued

Observations

Taski uses an Observer pattern centered on ExecutionContext which dispatches events to registered observers via duck-typed method calls. Task states are managed as symbols in TaskWrapper (:pending, :running, :completed) with separate clean-phase state constants (:cleaning, :clean_completed, :clean_failed). BaseProgressDisplay serves as the observer base class, tracking both run and clean lifecycles separately with a TaskProgress class that maintains per-task state. Currently, execution-related information is scattered: Scheduler builds its own dependency graph, Layout classes re-run static analysis for tree building, and ExecutionContext tracks runtime dependencies separately. The ticket specifies consolidating all this into a stateless ExecutionFacade which builds a single immutable DependencyGraph from static analysis and provides both Push (notifications with phase context) and Pull (query) APIs.

Assumptions

Assumption 1: Should `:skipped` be a terminal state or transitional?

Options Considered:

1. Terminal state - skipped tasks cannot transition to other states
2. Transitional state - could be "unskipped" if conditions change

Chosen Option: 1

Rationale: Terminal state aligns with Taski's execution model where Section selection is determined once during the run phase.

Assumption 2: Should we create formal Event classes or keep the current symbol/method dispatch?

Options Considered:

1. Create Event class hierarchy with typed payloads
2. Keep current symbol/method dispatch approach with documented contracts

Chosen Option: 2

Rationale: The current approach is simple, extensible, and allows observers to implement only methods they care about. Adding formal Event classes would require significant refactoring with minimal benefit.

Assumption 3: Should tree building responsibility move from displays?

Options Considered:

1. Move to ExecutionContext (mixes static analysis with runtime execution)
2. Build task_tree as separate structure in facade
3. Single DependencyGraph that provides all graph and tree queries

Chosen Option: 3

Rationale: Per the updated ticket, a single DependencyGraph serves as the sole source for all dependency and tree-related queries. Layout observers derive display metadata (depth, position, tree prefixes) from the graph in on_ready. The graph itself does not carry display concerns.

Assumption 4: How should ExecutionFacade relate to ExecutionContext?

Options Considered:

1. Add query methods to ExecutionContext (minimal change)
2. Create ExecutionFacade as a new class that wraps ExecutionContext
3. Create ExecutionFacade that completely replaces ExecutionContext

Chosen Option: 3

Rationale: Per the ticket, ExecutionFacade absorbs ExecutionContext entirely. ExecutionContext is removed and all its responsibilities (observer dispatch) move to ExecutionFacade, which also owns the immutable DependencyGraph built from static analysis.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Unify State Constants

Unify run and clean phase state constants to use the same state names and remove the intermediate enqueued states.

Task 1: Unify Clean State Constants

Change clean phase state constants to match run phase states for consistency.

• Update lib/taski/execution/task_wrapper.rb to use unified state constants for clean phase
• Change :cleaning → :running, :clean_completed → :completed, :clean_failed → :failed in clean state handling
• Update mark_clean_running, mark_clean_completed, mark_clean_failed methods to use unified constants
• Track phase context separately from state values (state is what, phase is when)

Task 2: Remove Enqueued States

Remove STATE_ENQUEUED and CLEAN_STATE_ENQUEUED intermediate states from Scheduler.

• Update lib/taski/execution/scheduler.rb to remove STATE_ENQUEUED constant
• Tasks transition directly from :pending to :running when sent to worker pool
• Update next_ready_tasks logic to check for :pending state only (not enqueued)
• The :running state now serves the double-execution prevention purpose (non-pending tasks won't be picked up)

Task 3: Update Progress Display State Handling

Update state handling in progress displays to use unified state names.

• Update apply_state_transition in lib/taski/execution/base_progress_display.rb to handle unified state names
• Remove separate clean state cases (:cleaning, :clean_completed, :clean_failed)
• Use phase parameter from notifications to differentiate run vs clean phase state changes
• Update TaskProgress to track run_state and clean_state using same value set (:pending, :running, :completed, :failed)

Task 4: Document State Machine

Create explicit documentation of valid state transitions as code comments.

• Add state machine documentation to lib/taski/execution/task_wrapper.rb header comments
• Document unified state set: :pending, :running, :completed, :failed, :skipped
• Document run phase transitions: pending→running→completed/failed, pending→skipped
• Document clean phase transitions: pending→running→completed/failed
• Note that skipped is run-phase only; tasks skipped/failed in run don't execute clean

🤖 Prompt for AI agents

Unify state model across run and clean phases, remove enqueued states, and
document the state machine.

**Unify Clean State Constants:**
- In `lib/taski/execution/task_wrapper.rb`, update clean phase state constants
to match run phase states
- Change `:cleaning` → `:running`, `:clean_completed` → `:completed`,
`:clean_failed` → `:failed` in clean state handling
- Update methods `mark_clean_running`, `mark_clean_completed`,
`mark_clean_failed` to use unified constants
- Track phase context separately from state values (state represents what
happened, phase represents when)

**Remove Enqueued States:**
- In `lib/taski/execution/scheduler.rb`, remove `STATE_ENQUEUED` constant
- Tasks transition directly from `:pending` to `:running` when sent to worker
pool
- Update `next_ready_tasks` logic to check for `:pending` state only (not
enqueued)
- The `:running` state serves double-execution prevention (non-pending tasks
won't be picked up again)

**Update Progress Display State Handling:**
- In `lib/taski/execution/base_progress_display.rb`, update
`apply_state_transition` method to handle unified state names
- Remove separate clean state cases (`:cleaning`, `:clean_completed`,
`:clean_failed`)
- Use phase parameter from notifications to differentiate run vs clean phase
state changes
- Update `TaskProgress` to track run_state and clean_state using same value set
(`:pending`, `:running`, `:completed`, `:failed`)

**Document State Machine:**
- Add comprehensive state machine documentation to header comments of
`lib/taski/execution/task_wrapper.rb`
- Document unified state set: `:pending`, `:running`, `:completed`, `:failed`,
`:skipped`
- Document run phase transitions: pending→running→completed/failed,
pending→skipped
- Document clean phase transitions: pending→running→completed/failed
- Note that skipped is run-phase only; tasks skipped/failed in run don't execute
clean

Phase 2: Introduce ExecutionFacade

Create ExecutionFacade as a stateless single source of truth that absorbs ExecutionContext, receives static analysis results, and builds the immutable DependencyGraph at initialization.

Task 1: Create ExecutionFacade Class

Create the new ExecutionFacade class with initialization from static analysis results.

• Create lib/taski/execution/execution_facade.rb with ExecutionFacade class
• Constructor accepts root_task_class:, analysis_result:, output_hub:
• Store @root_task_class, @output_hub, initialize @observers = []
• No mutable domain state: facade holds zero mutable state (no @current_phase)
• Add thread-safe observer access using Monitor

Task 2: Build Single DependencyGraph from Static Analysis

Build the single immutable DependencyGraph at initialization.

• Add private build_dependency_graph(analysis_result) method
• DependencyGraph provides: all_tasks, dependencies_for(task_class), sorted (topological order), cyclic?
• DependencyGraph provides tree traversal: parent-child relationships derived from graph structure
• Freeze the structure after building to ensure immutability
• This single structure replaces scattered building in Scheduler and Layout classes

Task 3: Add Pull API

Add query methods for observers to access immutable and accumulating data.

• Add attr_reader :root_task_class (immutable)
• Add attr_reader :dependency_graph (immutable - single source for all dependency/tree data)
• Add output_stream method returning @output_hub (accumulating)
• No current_phase accessor - phase is pushed via notifications, not pulled
• No task_tree or section_candidates - observers derive display metadata from dependency_graph

Task 4: Migrate Observer Dispatch from ExecutionContext

Move the observer pattern implementation from ExecutionContext to ExecutionFacade.

• Add add_observer(observer) method that sets observer.context = self and appends to @observers
• Add private dispatch(method, *args, **kwargs) method for thread-safe observer notification
• Dispatch is stateless - passes data through without storing
• Migrate thread-local context storage (THREAD_LOCAL_KEY, current, current=) from ExecutionContext
• Migrate runtime dependency tracking if needed for clean phase

Task 5: Remove ExecutionContext

Remove ExecutionContext class after migrating all functionality to ExecutionFacade.

• Delete lib/taski/execution/execution_context.rb
• Update all references to ExecutionContext throughout codebase to use ExecutionFacade
• Update lib/taski/execution/executor.rb to create and use ExecutionFacade
• Update lib/taski/section.rb to use ExecutionFacade for runtime dependency registration
• Update lib/taski/task.rb context access if present

🤖 Prompt for AI agents

Create stateless ExecutionFacade that absorbs ExecutionContext entirely, builds
single immutable DependencyGraph from static analysis, and provides both push
(notifications) and pull (query) APIs.

**Create ExecutionFacade Class:**
- Create `lib/taski/execution/execution_facade.rb` with `ExecutionFacade` class
- Constructor accepts `root_task_class:`, `analysis_result:`, `output_hub:`
- Store `@root_task_class`, `@output_hub`, initialize `@observers = []`
- **No mutable domain state**: facade holds zero mutable state (no
`@current_phase`)
- Add thread-safe observer access using Monitor

**Build Single DependencyGraph:**
- Add private `build_dependency_graph(analysis_result)` method
- DependencyGraph provides: `all_tasks`, `dependencies_for(task_class)`,
`sorted` (topological order), `cyclic?`
- DependencyGraph provides tree traversal: parent-child relationships derived
from graph structure
- Freeze the structure after building to ensure immutability
- This single structure replaces scattered building in Scheduler and Layout
classes

**Add Pull API:**
- Add `attr_reader :root_task_class` (immutable)
- Add `attr_reader :dependency_graph` (immutable - single source for all
dependency/tree data)
- Add `output_stream` method returning `@output_hub` (accumulating)
- **No `current_phase` accessor** - phase is pushed via notifications, not
pulled
- **No `task_tree` or `section_candidates`** - observers derive display metadata
from dependency_graph

**Migrate Observer Dispatch:**
- Add `add_observer(observer)` method that sets `observer.context = self` and
appends to `@observers`
- Add private `dispatch(method, *args, **kwargs)` method for thread-safe
observer notification
- Dispatch is stateless - passes data through without storing
- Migrate thread-local context storage (`THREAD_LOCAL_KEY`, `current`,
`current=`) from ExecutionContext
- Migrate runtime dependency tracking if needed for clean phase

**Remove ExecutionContext:**
- Delete `lib/taski/execution/execution_context.rb`
- Update all references to `ExecutionContext` throughout codebase to use
`ExecutionFacade`
- Update `lib/taski/execution/executor.rb` to create and use ExecutionFacade
- Update `lib/taski/section.rb` to use ExecutionFacade for runtime dependency
registration
- Update `lib/taski/task.rb` context access if present

Phase 3: Unify Events

Consolidate multiple granular events into an 8-event system with task_updated carrying state transitions and phase context.

Task 1: Add Ready Event

Create notify_ready event that signals preparation is complete and pull APIs are available.

• Add notify_ready method to lib/taski/execution/execution_facade.rb
• Merge notify_set_root_task and notify_set_output_capture into initialization before ready
• Ready signals: root_task_class, dependency_graph, output_stream are all queryable
• Dispatch to observers as on_ready method call

Task 2: Add Phase Events

Add explicit phase start/complete events for run and clean phases.

• Add notify_phase_started(phase) and notify_phase_completed(phase) to ExecutionFacade
• Phase parameter is :run or :clean
• Do not store phase in facade - phase context is stateless, observers track if needed
• Executor calls these when entering/exiting each phase
• Dispatch to observers as on_phase_started(phase) and on_phase_completed(phase)

Task 3: Consolidate Task Events into task_updated

Replace granular task events with unified notify_task_updated that includes phase context.

• Add notify_task_updated(task_class, previous_state:, current_state:, phase:, timestamp:) to ExecutionFacade
• Include phase: in every notification so observers know which phase without tracking state
• Do NOT include error or duration (stateless push, errors via direct logging path)
• Remove: notify_task_registered, notify_task_started, notify_task_completed, notify_clean_started, notify_clean_completed
• Dispatch to observers as on_task_updated(task_class, previous_state:, current_state:, phase:, timestamp:)
• Observers detect transitions: pending→running (started), running→completed (success), running→failed (error), pending→skipped (not executed)

Task 4: Update Group Events with Phase Context

Update group events to include phase context.

• Update notify_group_started(task_class, group_name, phase:, timestamp:)
• Update notify_group_completed(task_class, group_name, phase:, timestamp:)
• Phase is included in group events for consistency with task_updated
• Dispatch to observers as on_group_started(task_class, group_name, phase:, timestamp:) and on_group_completed(task_class, group_name, phase:, timestamp:)

Task 5: Document Event Catalog

Create comprehensive documentation of the unified 8-event system.

• Add event catalog documentation to lib/taski/execution/execution_facade.rb header comments
• Document 8 events: ready, start, stop, phase_started, phase_completed, task_updated, group_started, group_completed
• Document task_updated signature: (task_class, previous_state:, current_state:, phase:, timestamp:)
• Document group_started/completed signatures include phase: and timestamp:
• Document push vs pull: events push state transitions with phase, observers pull immutable data from facade
• Document execution order: ready → start → phase_started(:run) → task_updated... → phase_completed(:run) → ... → stop

🤖 Prompt for AI agents

Consolidate multiple granular events into a unified 8-event system with
`task_updated` as the core notification carrying state transitions and phase
context.

**Add Ready Event:**
- In `lib/taski/execution/execution_facade.rb`, add `notify_ready` method
- Merge `notify_set_root_task` and `notify_set_output_capture` into
initialization before ready
- Ready signals: root_task_class, dependency_graph, output_stream are all
queryable
- Dispatch to observers as `on_ready` method call

**Add Phase Events:**
- Add `notify_phase_started(phase)` and `notify_phase_completed(phase)` to
ExecutionFacade
- Phase parameter is `:run` or `:clean`
- **Do not store phase in facade** - phase context is stateless, observers track
if needed
- Executor calls these when entering/exiting each phase
- Dispatch to observers as `on_phase_started(phase)` and
`on_phase_completed(phase)`

**Consolidate Task Events:**
- Add `notify_task_updated(task_class, previous_state:, current_state:, phase:,
timestamp:)` to ExecutionFacade
- **Include `phase:` in every notification** so observers know which phase
without tracking state
- Do NOT include error or duration (stateless push, errors via direct logging
path)
- Remove: `notify_task_registered`, `notify_task_started`,
`notify_task_completed`, `notify_clean_started`, `notify_clean_completed`
- Dispatch to observers as `on_task_updated(task_class, previous_state:,
current_state:, phase:, timestamp:)`
- Observers detect transitions: `pending→running` (started), `running→completed`
(success), `running→failed` (error), `pending→skipped` (not executed)

**Update Group Events with Phase Context:**
- Update `notify_group_started(task_class, group_name, phase:, timestamp:)`
- Update `notify_group_completed(task_class, group_name, phase:, timestamp:)`
- Phase is included in group events for consistency with task_updated
- Dispatch to observers as `on_group_started(task_class, group_name, phase:,
timestamp:)` and `on_group_completed(task_class, group_name, phase:,
timestamp:)`

**Document Event Catalog:**
- Add event catalog documentation to header comments of
`lib/taski/execution/execution_facade.rb`
- Document 8 events: ready, start, stop, phase_started, phase_completed,
task_updated, group_started, group_completed
- Document `task_updated` signature: `(task_class, previous_state:,
current_state:, phase:, timestamp:)`
- Document `group_started/completed` signatures include `phase:` and
`timestamp:`
- Document push vs pull: events push state transitions with phase, observers
pull immutable data from facade
- Document execution order: ready → start → phase_started(:run) →
task_updated... → phase_completed(:run) → ... → stop

Phase 4: Introduce Observer Base Class

Create TaskObserver base class with auto-injected context.

Task 1: Create TaskObserver Base Class

Create base class for observers that provides context access and documents the interface.

• Create lib/taski/execution/task_observer.rb with TaskObserver base class
• Add attr_accessor :context for auto-injection of ExecutionFacade
• Define empty hook methods for all 8 events:
  • on_ready, on_start, on_stop
  • on_phase_started(phase), on_phase_completed(phase)
  • on_task_updated(task_class, previous_state:, current_state:, phase:, timestamp:)
  • on_group_started(task_class, group_name, phase:, timestamp:)
  • on_group_completed(task_class, group_name, phase:, timestamp:)
• Document that subclasses override only methods they care about

Task 2: Create Logger Observer Example

Implement a reference LoggerObserver showing event consumption pattern.

• Create lib/taski/execution/logger_observer.rb extending TaskObserver
• Log state transitions with timestamp, task name, previous_state → current_state, phase
• Use phase: parameter from notification directly (no @context.current_phase)
• Query @context.dependency_graph in on_ready to log total task count
• Note: LoggerObserver does NOT log error details or output; those use direct paths
• Support configurable output destination (file, STDOUT)

🤖 Prompt for AI agents

Create TaskObserver base class with auto-injected context and implement a
reference logger observer demonstrating the event consumption pattern with phase
context.

**Create TaskObserver Base Class:**
- Create `lib/taski/execution/task_observer.rb` with `TaskObserver` base class
- Add `attr_accessor :context` for auto-injection of ExecutionFacade
- Define empty hook methods for all 8 events:
  - `on_ready`
  - `on_start`
  - `on_stop`
  - `on_phase_started(phase)`
  - `on_phase_completed(phase)`
- `on_task_updated(task_class, previous_state:, current_state:, phase:,
timestamp:)`
  - `on_group_started(task_class, group_name, phase:, timestamp:)`
  - `on_group_completed(task_class, group_name, phase:, timestamp:)`
- Document that subclasses should override only the methods they care about

**Create Logger Observer Example:**
- Create `lib/taski/execution/logger_observer.rb` extending TaskObserver
- Log state transitions with timestamp, task name, previous_state →
current_state, and phase
- Use `phase:` parameter from notification directly (no
`@context.current_phase`)
- Query `@context.dependency_graph` in `on_ready` to log total task count
- Note: LoggerObserver does NOT log error details or output; those use direct
paths
- Support configurable output destination (file, STDOUT)

Phase 5: Pull-based Observer

Update Layout classes to use pull-based pattern, deriving display metadata from dependency_graph.

Task 1: Update BaseProgressDisplay to Use TaskObserver Pattern

Refactor BaseProgressDisplay to implement the new observer interface.

• Update lib/taski/execution/base_progress_display.rb to extend TaskObserver
• Replace register_task, update_task handlers with on_task_updated(task_class, previous_state:, current_state:, phase:, timestamp:)
• Use phase: parameter from notification to determine run vs clean context
• Calculate duration from timestamp difference (record start time on pending→running, compute on running→completed/failed)
• Remove methods: set_root_task, on_root_task_set, register_section_impl, on_section_impl_registered

Task 2: Remove TaskProgress/TaskState Class from BaseProgressDisplay

Remove the TaskProgress tracking class as observers now track their own state from notifications.

• Remove TaskProgress inner class from lib/taski/execution/base_progress_display.rb
• Remove @tasks hash that stored TaskProgress per task
• Observers maintain minimal internal state derived from task_updated notifications
• Duration calculated from timestamps, errors logged via direct path (not stored per-task)

Task 3: Remove Tree Building Code from Layout Classes

Remove all tree building and dependency analysis code from Layout classes.

• From lib/taski/execution/base_progress_display.rb remove: build_tree_node, get_task_dependencies (calls Analyzer), collect_section_candidates, mark_unselected_candidates_completed, mark_subtree_completed, mark_task_as_skipped
• From lib/taski/execution/base_progress_display.rb remove: @section_candidates, @section_candidate_subtrees instance variables
• From lib/taski/execution/simple_progress_display.rb remove: build_tree_structure, register_tasks_from_tree, on_root_task_set override
• From lib/taski/execution/tree_progress_display.rb remove: build_tree_structure, register_tree_nodes, on_root_task_set override, @tree_nodes, @node_depths, @node_is_last

Task 4: Update Displays to Derive Metadata from DependencyGraph in on_ready

Update display classes to derive display metadata from the single DependencyGraph.

• In on_ready, pull @graph = @context.dependency_graph as single source for all dependency/tree data
• Derive display metadata (depth, is_last flags, tree prefixes) from graph's parent-child relationships
• Store derived metadata locally in the Layout (e.g., @depths, @tree_prefixes)
• TreeProgressDisplay uses derived metadata for rendering hierarchy
• SimpleProgressDisplay uses graph for task counting/progress calculation
• Section candidates are detected from graph structure (nested classes of Section tasks)

Task 5: Remove Scheduler's build_dependency_graph

Update Scheduler to pull dependency_graph from ExecutionFacade instead of building its own.

• Remove build_dependency_graph(root_task_class) method from lib/taski/execution/scheduler.rb
• Remove BFS traversal code that builds @dependencies and @task_states from cached_dependencies
• Scheduler receives dependency_graph from ExecutionFacade at initialization or via accessor
• Update next_ready_tasks to query the facade's dependency_graph
• Keep runtime dependency merging for clean phase if needed

🤖 Prompt for AI agents

Refactor Layout classes to use pull-based pattern, removing all tree building
logic and TaskProgress tracking, pulling single immutable DependencyGraph from
ExecutionFacade and deriving display metadata from it.

**Update BaseProgressDisplay:**
- In `lib/taski/execution/base_progress_display.rb`, extend TaskObserver
- Replace `register_task` and `update_task` handlers with
`on_task_updated(task_class, previous_state:, current_state:, phase:,
timestamp:)`
- Use `phase:` parameter from notification to determine run vs clean context
- Calculate duration from timestamp difference (record start time on
`pending→running`, compute on `running→completed/failed`)
- Remove methods: `set_root_task`, `on_root_task_set`, `register_section_impl`,
`on_section_impl_registered`

**Remove TaskProgress Class:**
- Remove `TaskProgress` inner class from
`lib/taski/execution/base_progress_display.rb`
- Remove `@tasks` hash that stored TaskProgress per task
- Observers maintain minimal internal state derived from `task_updated`
notifications
- Duration calculated from timestamps, errors logged via direct path (not stored
per-task)

**Remove Tree Building Code:**
- From `lib/taski/execution/base_progress_display.rb` remove: `build_tree_node`,
`get_task_dependencies`, `collect_section_candidates`,
`mark_unselected_candidates_completed`, `mark_subtree_completed`,
`mark_task_as_skipped`
- From `lib/taski/execution/base_progress_display.rb` remove:
`@section_candidates`, `@section_candidate_subtrees` instance variables
- From `lib/taski/execution/simple_progress_display.rb` remove:
`build_tree_structure`, `register_tasks_from_tree`, `on_root_task_set` override
- From `lib/taski/execution/tree_progress_display.rb` remove:
`build_tree_structure`, `register_tree_nodes`, `on_root_task_set` override,
`@tree_nodes`, `@node_depths`, `@node_is_last`

**Update Displays to Derive Metadata from DependencyGraph:**
- In `on_ready`, pull `@graph = @context.dependency_graph` as single source for
all dependency/tree data
- Derive display metadata (depth, `is_last` flags, tree prefixes) from graph's
parent-child relationships
- Store derived metadata locally in the Layout (e.g., `@depths`,
`@tree_prefixes`)
- TreeProgressDisplay uses derived metadata for rendering hierarchy
- SimpleProgressDisplay uses graph for task counting/progress calculation
- Section candidates are detected from graph structure (nested classes of
Section tasks)

**Remove Scheduler's build_dependency_graph:**
- Remove `build_dependency_graph(root_task_class)` method from
`lib/taski/execution/scheduler.rb`
- Remove BFS traversal code that builds `@dependencies` and `@task_states` from
`cached_dependencies`
- Scheduler receives `dependency_graph` from ExecutionFacade at initialization
or via accessor
- Update `next_ready_tasks` to query the facade's dependency_graph
- Keep runtime dependency merging for clean phase if needed

Phase 6: Remove TaskTiming

Remove TaskTiming class from TaskWrapper as observers now calculate duration from timestamps.

Task 1: Remove TaskTiming Class

Remove the TaskTiming class that tracked start/end times and calculated duration.

• Remove TaskTiming inner class from lib/taski/execution/task_wrapper.rb
• Remove @timing and @clean_timing instance variables
• TaskTiming existed solely to calculate and pass duration_ms to observers
• With timestamp-based notifications, this is no longer needed

Task 2: Update TaskWrapper State Transitions

Update state transition methods to not depend on TaskTiming.

• Update mark_running, mark_completed, mark_failed to not interact with timing
• Update mark_clean_running, mark_clean_completed, mark_clean_failed similarly
• State transitions trigger notifications via facade; observers calculate duration themselves
• Keep minimal state in TaskWrapper: just current state values

🤖 Prompt for AI agents

Remove TaskTiming class from TaskWrapper as observers now calculate duration
from timestamps in notifications.

**Remove TaskTiming Class:**
- Remove `TaskTiming` inner class from `lib/taski/execution/task_wrapper.rb`
- Remove `@timing` and `@clean_timing` instance variables
- TaskTiming existed solely to calculate and pass `duration_ms` to observers
- With timestamp-based notifications, this is no longer needed

**Update TaskWrapper State Transitions:**
- Update `mark_running`, `mark_completed`, `mark_failed` to not interact with
timing
- Update `mark_clean_running`, `mark_clean_completed`, `mark_clean_failed`
similarly
- State transitions trigger notifications via facade; observers calculate
duration themselves
- Keep minimal state in TaskWrapper: just current state values

Phase 7: Add skipped State for Unaccessed Tasks

Introduce :skipped state for tasks not executed due to Section selection or dependency failure.

Task 1: Add Skipped State Constant

Add :skipped as a formal state constant.

• Add STATE_SKIPPED = :skipped constant to lib/taski/execution/task_wrapper.rb
• Add mark_skipped method that transitions a :pending task to :skipped state
• Ensure skipped is terminal (no transitions out of skipped)
• Skipped only applies to run phase; tasks don't have clean phase if skipped

Task 2: Mark Unselected Section Candidates as Skipped

Update Section selection to mark unselected candidates as :skipped.

• Update lib/taski/section.rb register_impl_selection method
• Query facade's dependency_graph to determine which tasks are Section impl candidates
• For each candidate that is NOT the selected impl, trigger task_updated(pending→skipped, phase: :run)
• Also mark the entire subtree of unselected candidates as skipped (dependencies not needed)

Task 3: Mark Dependency-Failed Tasks as Skipped

Mark tasks whose dependencies failed as :skipped since they cannot execute.

• In Executor or Scheduler, when a task fails, identify dependent tasks that cannot run
• Transition those dependents from :pending to :skipped via task_updated
• This propagates through the dependency chain (if A fails, B depends on A, C depends on B → both B and C are skipped)
• Skipped reason is inferrable by observers: check if any dependency has :failed state

Task 4: Update Display Rendering for Skipped State

Update progress displays to render skipped tasks appropriately.

• Handle pending→skipped transition in on_task_updated to update visual state
• Use skipped icon (⊘) for skipped tasks, dimmed styling
• In TreeProgressDisplay, skipped impl candidates show "(not selected)" suffix
• Skipped state replaces the previous mark_task_as_skipped display hack that used :completed

🤖 Prompt for AI agents

Introduce `:skipped` state for tasks not executed due to Section selection or
dependency failure, and update displays to render skipped tasks appropriately.

**Add Skipped State Constant:**
- In `lib/taski/execution/task_wrapper.rb`, add `STATE_SKIPPED = :skipped`
constant
- Add `mark_skipped` method that transitions a `:pending` task to `:skipped`
state
- Ensure skipped is terminal (no transitions out of skipped)
- Skipped only applies to run phase; tasks don't have clean phase if skipped

**Mark Unselected Section Candidates as Skipped:**
- Update `lib/taski/section.rb` `register_impl_selection` method
- Query facade's `dependency_graph` to determine which tasks are Section impl
candidates
- For each candidate that is NOT the selected impl, trigger
`task_updated(pending→skipped, phase: :run)`
- Also mark the entire subtree of unselected candidates as skipped (dependencies
not needed)

**Mark Dependency-Failed Tasks as Skipped:**
- In Executor or Scheduler, when a task fails, identify dependent tasks that
cannot run
- Transition those dependents from `:pending` to `:skipped` via `task_updated`
- This propagates through the dependency chain (if A fails, B depends on A, C
depends on B → both B and C are skipped)
- Skipped reason is inferrable by observers: check if any dependency has
`:failed` state

**Update Display Rendering for Skipped State:**
- Handle `pending→skipped` transition in `on_task_updated` to update visual
state
- Use skipped icon (`⊘`) for skipped tasks, dimmed styling
- In TreeProgressDisplay, skipped impl candidates show "(not selected)" suffix
- Skipped state replaces the previous `mark_task_as_skipped` display hack that
used `:completed`

Phase 8: Output Processing

Implement OutputHub with proper read API and capture both stdout and stderr.

Task 1: Capture stderr in Addition to stdout

Update output capture to intercept stderr alongside stdout.

• In Executor's setup_output_capture, replace both $stdout and $stderr
• Store original streams: @original_stdout = $stdout, @original_stderr = $stderr
• Both stdout and stderr route to OutputHub
• Layout/Progress display writes to @original_stderr (not captured)

Task 2: Implement OutputHub Read API

Add the read(task_class, limit:) method to OutputHub for observers to query output.

• Update OutputHub (or create if using TaskOutputRouter) to provide read(task_class, limit: nil) method
• limit: nil returns all buffered lines, limit: N returns last N lines
• Maintain ring buffer per task with MAX_RECENT_LINES = 30
• Method is thread-safe for concurrent access from multiple observers

Task 3: Add Direct Error Logging Path

Implement direct error logging from Executor to Taski::Logging.

• In Executor, when task fails: call Taski::Logging.error(task_class, error) directly
• This logs error message, backtrace, and task class immediately
• Separate from observer notification which only sends current_state: :failed
• Error details are NOT stored per-task or passed through observer system

Task 4: Add Direct Output Logging Path

Implement direct output logging from OutputHub to Taski::Logging.

• In OutputHub's store_output_lines, call Taski::Logging.output(task_class, line) for each line
• This provides immediate logging of task output
• Separate from ring buffer storage used by progress displays
• LoggerObserver does NOT handle output logging (it's a direct path)

🤖 Prompt for AI agents

Implement OutputHub with proper read API and capture both stdout and stderr,
with direct logging paths for errors and output.

**Capture stderr:**
- In Executor's `setup_output_capture`, replace both `$stdout` and `$stderr`
- Store original streams: `@original_stdout = $stdout`, `@original_stderr =
$stderr`
- Both stdout and stderr route to OutputHub
- Layout/Progress display writes to `@original_stderr` (not captured)

**Implement OutputHub Read API:**
- Update OutputHub (or create if using TaskOutputRouter) to provide
`read(task_class, limit: nil)` method
- `limit: nil` returns all buffered lines, `limit: N` returns last N lines
- Maintain ring buffer per task with `MAX_RECENT_LINES = 30`
- Method is thread-safe for concurrent access from multiple observers

**Add Direct Error Logging Path:**
- In Executor, when task fails: call `Taski::Logging.error(task_class, error)`
directly
- This logs error message, backtrace, and task class immediately
- Separate from observer notification which only sends `current_state: :failed`
- Error details are NOT stored per-task or passed through observer system

**Add Direct Output Logging Path:**
- In OutputHub's `store_output_lines`, call `Taski::Logging.output(task_class,
line)` for each line
- This provides immediate logging of task output
- Separate from ring buffer storage used by progress displays
- LoggerObserver does NOT handle output logging (it's a direct path)

Phase 9: Update Tests

Update test suite to cover the new event/state model and ExecutionFacade.

Task 1: Update ExecutionContext Tests for ExecutionFacade

Migrate existing ExecutionContext tests to ExecutionFacade.

• Update test/test_execution_context.rb to test ExecutionFacade instead
• Test observer registration with auto-injected context
• Test all 8 event dispatches: ready, start, stop, phase_started, phase_completed, task_updated, group_started, group_completed
• Test thread-local context storage (current, current=)
• Test that facade is stateless (no mutable domain state)

Task 2: Test Unified State Model

Add tests for the unified state model with all transitions.

• Test state constants are unified (no separate clean state values)
• Test run phase transitions: pending→running→completed, pending→running→failed, pending→skipped
• Test clean phase transitions: pending→running→completed, pending→running→failed
• Test that enqueued state no longer exists
• Test that skipped is terminal (cannot transition out)

Task 3: Test Pull API

Add tests for ExecutionFacade's pull API methods.

• Test dependency_graph is immutable and provides correct task relationships
• Test dependency_graph provides tree traversal (parent-child relationships)
• Test root_task_class returns correct root task
• Test output_stream.read(task_class, limit:) returns captured output
• Test that no current_phase accessor exists (phase is pushed, not pulled)

Task 4: Test Skipped State Scenarios

Add tests for skipped state in Section selection and dependency failure scenarios.

• Test that unselected Section candidates receive pending→skipped transition
• Test that subtrees of unselected candidates are also marked skipped
• Test that tasks depending on failed tasks receive pending→skipped transition
• Test that skipped tasks do not execute clean phase

🤖 Prompt for AI agents

Update test suite to comprehensively cover the new event/state model and
stateless ExecutionFacade functionality.

**Update ExecutionContext Tests:**
- Update `test/test_execution_context.rb` to test ExecutionFacade instead
- Test observer registration with auto-injected context
- Test all 8 event dispatches: ready, start, stop, phase_started,
phase_completed, task_updated (with phase:), group_started (with phase:),
group_completed (with phase:)
- Test thread-local context storage (`current`, `current=`)
- Test that facade is stateless (no mutable domain state)

**Test Unified State Model:**
- Test state constants are unified (no separate clean state values)
- Test run phase transitions: pending→running→completed, pending→running→failed,
pending→skipped
- Test clean phase transitions: pending→running→completed,
pending→running→failed
- Test that enqueued state no longer exists
- Test that skipped is terminal (cannot transition out)

**Test Pull API:**
- Test `dependency_graph` is immutable and provides correct task relationships
- Test `dependency_graph` provides tree traversal (parent-child relationships)
- Test `root_task_class` returns correct root task
- Test `output_stream.read(task_class, limit:)` returns captured output
- Test that no `current_phase` accessor exists (phase is pushed, not pulled)

**Test Skipped State Scenarios:**
- Test that unselected Section candidates receive `pending→skipped` transition
- Test that subtrees of unselected candidates are also marked skipped
- Test that tasks depending on failed tasks receive `pending→skipped` transition
- Test that skipped tasks do not execute clean phase

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Unify state model across run and clean phases, remove enqueued states, and
document the state machine.

**Unify Clean State Constants:**
- In `lib/taski/execution/task_wrapper.rb`, update clean phase state constants
to match run phase states
- Change `:cleaning` → `:running`, `:clean_completed` → `:completed`,
`:clean_failed` → `:failed` in clean state handling
- Update methods `mark_clean_running`, `mark_clean_completed`,
`mark_clean_failed` to use unified constants
- Track phase context separately from state values (state represents what
happened, phase represents when)

**Remove Enqueued States:**
- In `lib/taski/execution/scheduler.rb`, remove `STATE_ENQUEUED` constant
- Tasks transition directly from `:pending` to `:running` when sent to worker
pool
- Update `next_ready_tasks` logic to check for `:pending` state only (not
enqueued)
- The `:running` state serves double-execution prevention (non-pending tasks
won't be picked up again)

**Update Progress Display State Handling:**
- In `lib/taski/execution/base_progress_display.rb`, update
`apply_state_transition` method to handle unified state names
- Remove separate clean state cases (`:cleaning`, `:clean_completed`,
`:clean_failed`)
- Use phase parameter from notifications to differentiate run vs clean phase
state changes
- Update `TaskProgress` to track run_state and clean_state using same value set
(`:pending`, `:running`, `:completed`, `:failed`)

**Document State Machine:**
- Add comprehensive state machine documentation to header comments of
`lib/taski/execution/task_wrapper.rb`
- Document unified state set: `:pending`, `:running`, `:completed`, `:failed`,
`:skipped`
- Document run phase transitions: pending→running→completed/failed,
pending→skipped
- Document clean phase transitions: pending→running→completed/failed
- Note that skipped is run-phase only; tasks skipped/failed in run don't execute
clean
===============================================================================

Task: 2

Create stateless ExecutionFacade that absorbs ExecutionContext entirely, builds
single immutable DependencyGraph from static analysis, and provides both push
(notifications) and pull (query) APIs.

**Create ExecutionFacade Class:**
- Create `lib/taski/execution/execution_facade.rb` with `ExecutionFacade` class
- Constructor accepts `root_task_class:`, `analysis_result:`, `output_hub:`
- Store `@root_task_class`, `@output_hub`, initialize `@observers = []`
- **No mutable domain state**: facade holds zero mutable state (no
`@current_phase`)
- Add thread-safe observer access using Monitor

**Build Single DependencyGraph:**
- Add private `build_dependency_graph(analysis_result)` method
- DependencyGraph provides: `all_tasks`, `dependencies_for(task_class)`,
`sorted` (topological order), `cyclic?`
- DependencyGraph provides tree traversal: parent-child relationships derived
from graph structure
- Freeze the structure after building to ensure immutability
- This single structure replaces scattered building in Scheduler and Layout
classes

**Add Pull API:**
- Add `attr_reader :root_task_class` (immutable)
- Add `attr_reader :dependency_graph` (immutable - single source for all
dependency/tree data)
- Add `output_stream` method returning `@output_hub` (accumulating)
- **No `current_phase` accessor** - phase is pushed via notifications, not
pulled
- **No `task_tree` or `section_candidates`** - observers derive display metadata
from dependency_graph

**Migrate Observer Dispatch:**
- Add `add_observer(observer)` method that sets `observer.context = self` and
appends to `@observers`
- Add private `dispatch(method, *args, **kwargs)` method for thread-safe
observer notification
- Dispatch is stateless - passes data through without storing
- Migrate thread-local context storage (`THREAD_LOCAL_KEY`, `current`,
`current=`) from ExecutionContext
- Migrate runtime dependency tracking if needed for clean phase

**Remove ExecutionContext:**
- Delete `lib/taski/execution/execution_context.rb`
- Update all references to `ExecutionContext` throughout codebase to use
`ExecutionFacade`
- Update `lib/taski/execution/executor.rb` to create and use ExecutionFacade
- Update `lib/taski/section.rb` to use ExecutionFacade for runtime dependency
registration
- Update `lib/taski/task.rb` context access if present
===============================================================================

Task: 3

Consolidate multiple granular events into a unified 8-event system with
`task_updated` as the core notification carrying state transitions and phase
context.

**Add Ready Event:**
- In `lib/taski/execution/execution_facade.rb`, add `notify_ready` method
- Merge `notify_set_root_task` and `notify_set_output_capture` into
initialization before ready
- Ready signals: root_task_class, dependency_graph, output_stream are all
queryable
- Dispatch to observers as `on_ready` method call

**Add Phase Events:**
- Add `notify_phase_started(phase)` and `notify_phase_completed(phase)` to
ExecutionFacade
- Phase parameter is `:run` or `:clean`
- **Do not store phase in facade** - phase context is stateless, observers track
if needed
- Executor calls these when entering/exiting each phase
- Dispatch to observers as `on_phase_started(phase)` and
`on_phase_completed(phase)`

**Consolidate Task Events:**
- Add `notify_task_updated(task_class, previous_state:, current_state:, phase:,
timestamp:)` to ExecutionFacade
- **Include `phase:` in every notification** so observers know which phase
without tracking state
- Do NOT include error or duration (stateless push, errors via direct logging
path)
- Remove: `notify_task_registered`, `notify_task_started`,
`notify_task_completed`, `notify_clean_started`, `notify_clean_completed`
- Dispatch to observers as `on_task_updated(task_class, previous_state:,
current_state:, phase:, timestamp:)`
- Observers detect transitions: `pending→running` (started), `running→completed`
(success), `running→failed` (error), `pending→skipped` (not executed)

**Update Group Events with Phase Context:**
- Update `notify_group_started(task_class, group_name, phase:, timestamp:)`
- Update `notify_group_completed(task_class, group_name, phase:, timestamp:)`
- Phase is included in group events for consistency with task_updated
- Dispatch to observers as `on_group_started(task_class, group_name, phase:,
timestamp:)` and `on_group_completed(task_class, group_name, phase:,
timestamp:)`

**Document Event Catalog:**
- Add event catalog documentation to header comments of
`lib/taski/execution/execution_facade.rb`
- Document 8 events: ready, start, stop, phase_started, phase_completed,
task_updated, group_started, group_completed
- Document `task_updated` signature: `(task_class, previous_state:,
current_state:, phase:, timestamp:)`
- Document `group_started/completed` signatures include `phase:` and
`timestamp:`
- Document push vs pull: events push state transitions with phase, observers
pull immutable data from facade
- Document execution order: ready → start → phase_started(:run) →
task_updated... → phase_completed(:run) → ... → stop
===============================================================================

Task: 4

Create TaskObserver base class with auto-injected context and implement a
reference logger observer demonstrating the event consumption pattern with phase
context.

**Create TaskObserver Base Class:**
- Create `lib/taski/execution/task_observer.rb` with `TaskObserver` base class
- Add `attr_accessor :context` for auto-injection of ExecutionFacade
- Define empty hook methods for all 8 events:
  - `on_ready`
  - `on_start`
  - `on_stop`
  - `on_phase_started(phase)`
  - `on_phase_completed(phase)`
- `on_task_updated(task_class, previous_state:, current_state:, phase:,
timestamp:)`
  - `on_group_started(task_class, group_name, phase:, timestamp:)`
  - `on_group_completed(task_class, group_name, phase:, timestamp:)`
- Document that subclasses should override only the methods they care about

**Create Logger Observer Example:**
- Create `lib/taski/execution/logger_observer.rb` extending TaskObserver
- Log state transitions with timestamp, task name, previous_state →
current_state, and phase
- Use `phase:` parameter from notification directly (no
`@context.current_phase`)
- Query `@context.dependency_graph` in `on_ready` to log total task count
- Note: LoggerObserver does NOT log error details or output; those use direct
paths
- Support configurable output destination (file, STDOUT)
===============================================================================

Task: 5

Refactor Layout classes to use pull-based pattern, removing all tree building
logic and TaskProgress tracking, pulling single immutable DependencyGraph from
ExecutionFacade and deriving display metadata from it.

**Update BaseProgressDisplay:**
- In `lib/taski/execution/base_progress_display.rb`, extend TaskObserver
- Replace `register_task` and `update_task` handlers with
`on_task_updated(task_class, previous_state:, current_state:, phase:,
timestamp:)`
- Use `phase:` parameter from notification to determine run vs clean context
- Calculate duration from timestamp difference (record start time on
`pending→running`, compute on `running→completed/failed`)
- Remove methods: `set_root_task`, `on_root_task_set`, `register_section_impl`,
`on_section_impl_registered`

**Remove TaskProgress Class:**
- Remove `TaskProgress` inner class from
`lib/taski/execution/base_progress_display.rb`
- Remove `@tasks` hash that stored TaskProgress per task
- Observers maintain minimal internal state derived from `task_updated`
notifications
- Duration calculated from timestamps, errors logged via direct path (not stored
per-task)

**Remove Tree Building Code:**
- From `lib/taski/execution/base_progress_display.rb` remove: `build_tree_node`,
`get_task_dependencies`, `collect_section_candidates`,
`mark_unselected_candidates_completed`, `mark_subtree_completed`,
`mark_task_as_skipped`
- From `lib/taski/execution/base_progress_display.rb` remove:
`@section_candidates`, `@section_candidate_subtrees` instance variables
- From `lib/taski/execution/simple_progress_display.rb` remove:
`build_tree_structure`, `register_tasks_from_tree`, `on_root_task_set` override
- From `lib/taski/execution/tree_progress_display.rb` remove:
`build_tree_structure`, `register_tree_nodes`, `on_root_task_set` override,
`@tree_nodes`, `@node_depths`, `@node_is_last`

**Update Displays to Derive Metadata from DependencyGraph:**
- In `on_ready`, pull `@graph = @context.dependency_graph` as single source for
all dependency/tree data
- Derive display metadata (depth, `is_last` flags, tree prefixes) from graph's
parent-child relationships
- Store derived metadata locally in the Layout (e.g., `@depths`,
`@tree_prefixes`)
- TreeProgressDisplay uses derived metadata for rendering hierarchy
- SimpleProgressDisplay uses graph for task counting/progress calculation
- Section candidates are detected from graph structure (nested classes of
Section tasks)

**Remove Scheduler's build_dependency_graph:**
- Remove `build_dependency_graph(root_task_class)` method from
`lib/taski/execution/scheduler.rb`
- Remove BFS traversal code that builds `@dependencies` and `@task_states` from
`cached_dependencies`
- Scheduler receives `dependency_graph` from ExecutionFacade at initialization
or via accessor
- Update `next_ready_tasks` to query the facade's dependency_graph
- Keep runtime dependency merging for clean phase if needed
===============================================================================

Task: 6

Remove TaskTiming class from TaskWrapper as observers now calculate duration
from timestamps in notifications.

**Remove TaskTiming Class:**
- Remove `TaskTiming` inner class from `lib/taski/execution/task_wrapper.rb`
- Remove `@timing` and `@clean_timing` instance variables
- TaskTiming existed solely to calculate and pass `duration_ms` to observers
- With timestamp-based notifications, this is no longer needed

**Update TaskWrapper State Transitions:**
- Update `mark_running`, `mark_completed`, `mark_failed` to not interact with
timing
- Update `mark_clean_running`, `mark_clean_completed`, `mark_clean_failed`
similarly
- State transitions trigger notifications via facade; observers calculate
duration themselves
- Keep minimal state in TaskWrapper: just current state values
===============================================================================

Task: 7

Introduce `:skipped` state for tasks not executed due to Section selection or
dependency failure, and update displays to render skipped tasks appropriately.

**Add Skipped State Constant:**
- In `lib/taski/execution/task_wrapper.rb`, add `STATE_SKIPPED = :skipped`
constant
- Add `mark_skipped` method that transitions a `:pending` task to `:skipped`
state
- Ensure skipped is terminal (no transitions out of skipped)
- Skipped only applies to run phase; tasks don't have clean phase if skipped

**Mark Unselected Section Candidates as Skipped:**
- Update `lib/taski/section.rb` `register_impl_selection` method
- Query facade's `dependency_graph` to determine which tasks are Section impl
candidates
- For each candidate that is NOT the selected impl, trigger
`task_updated(pending→skipped, phase: :run)`
- Also mark the entire subtree of unselected candidates as skipped (dependencies
not needed)

**Mark Dependency-Failed Tasks as Skipped:**
- In Executor or Scheduler, when a task fails, identify dependent tasks that
cannot run
- Transition those dependents from `:pending` to `:skipped` via `task_updated`
- This propagates through the dependency chain (if A fails, B depends on A, C
depends on B → both B and C are skipped)
- Skipped reason is inferrable by observers: check if any dependency has
`:failed` state

**Update Display Rendering for Skipped State:**
- Handle `pending→skipped` transition in `on_task_updated` to update visual
state
- Use skipped icon (`⊘`) for skipped tasks, dimmed styling
- In TreeProgressDisplay, skipped impl candidates show "(not selected)" suffix
- Skipped state replaces the previous `mark_task_as_skipped` display hack that
used `:completed`
===============================================================================

Task: 8

Implement OutputHub with proper read API and capture both stdout and stderr,
with direct logging paths for errors and output.

**Capture stderr:**
- In Executor's `setup_output_capture`, replace both `$stdout` and `$stderr`
- Store original streams: `@original_stdout = $stdout`, `@original_stderr =
$stderr`
- Both stdout and stderr route to OutputHub
- Layout/Progress display writes to `@original_stderr` (not captured)

**Implement OutputHub Read API:**
- Update OutputHub (or create if using TaskOutputRouter) to provide
`read(task_class, limit: nil)` method
- `limit: nil` returns all buffered lines, `limit: N` returns last N lines
- Maintain ring buffer per task with `MAX_RECENT_LINES = 30`
- Method is thread-safe for concurrent access from multiple observers

**Add Direct Error Logging Path:**
- In Executor, when task fails: call `Taski::Logging.error(task_class, error)`
directly
- This logs error message, backtrace, and task class immediately
- Separate from observer notification which only sends `current_state: :failed`
- Error details are NOT stored per-task or passed through observer system

**Add Direct Output Logging Path:**
- In OutputHub's `store_output_lines`, call `Taski::Logging.output(task_class,
line)` for each line
- This provides immediate logging of task output
- Separate from ring buffer storage used by progress displays
- LoggerObserver does NOT handle output logging (it's a direct path)
===============================================================================

Task: 9

Update test suite to comprehensively cover the new event/state model and
stateless ExecutionFacade functionality.

**Update ExecutionContext Tests:**
- Update `test/test_execution_context.rb` to test ExecutionFacade instead
- Test observer registration with auto-injected context
- Test all 8 event dispatches: ready, start, stop, phase_started,
phase_completed, task_updated (with phase:), group_started (with phase:),
group_completed (with phase:)
- Test thread-local context storage (`current`, `current=`)
- Test that facade is stateless (no mutable domain state)

**Test Unified State Model:**
- Test state constants are unified (no separate clean state values)
- Test run phase transitions: pending→running→completed, pending→running→failed,
pending→skipped
- Test clean phase transitions: pending→running→completed,
pending→running→failed
- Test that enqueued state no longer exists
- Test that skipped is terminal (cannot transition out)

**Test Pull API:**
- Test `dependency_graph` is immutable and provides correct task relationships
- Test `dependency_graph` provides tree traversal (parent-child relationships)
- Test `root_task_class` returns correct root task
- Test `output_stream.read(task_class, limit:)` returns captured output
- Test that no `current_phase` accessor exists (phase is pushed, not pulled)

**Test Skipped State Scenarios:**
- Test that unselected Section candidates receive `pending→skipped` transition
- Test that subtrees of unselected candidates are also marked skipped
- Test that tasks depending on failed tasks receive `pending→skipped` transition
- Test that skipped tasks do not execute clean phase

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

I've updated the plan above based on your feedback. Ready to proceed when you are!

[coderabbitai]

I've updated the plan above based on your feedback. Ready to proceed when you are!