trak_flow 0.1.3

data/docs/api/ruby-library.md

@@ -0,0 +1,349 @@
+# Ruby Library Reference
+
+TrakFlow can be used as a Ruby library for programmatic task management.
+
+## Installation
+
+```ruby
+# Gemfile
+gem 'trak_flow'
+```
+
+## Quick Start
+
+```ruby
+require 'trak_flow'
+
+# Initialize with default configuration
+trak = TrakFlow.new
+
+# Create a task
+task = trak.create_task(
+  title: "Implement feature X",
+  type: "feature",
+  priority: 1
+)
+puts "Created: #{task.id}"
+
+# List open tasks
+tasks = trak.list_tasks(status: "open")
+tasks.each { |t| puts "#{t.id}: #{t.title}" }
+
+# Update a task
+trak.start_task(task.id)
+trak.close_task(task.id, summary: "Implemented in PR #42")
+```
+
+## Configuration
+
+### Default Configuration
+
+```ruby
+trak = TrakFlow.new
+# Uses .trak_flow/ in current directory
+```
+
+### Custom Configuration
+
+```ruby
+trak = TrakFlow.new(
+  data_dir: "/path/to/data",
+  config: {
+    default_priority: 2,
+    gc_retention: "7d"
+  }
+)
+```
+
+### Configuration from File
+
+```ruby
+trak = TrakFlow.from_config("/path/to/config.json")
+```
+
+## Core Classes
+
+### TrakFlow
+
+Main entry point for all operations.
+
+```ruby
+trak = TrakFlow.new(options = {})
+```
+
+#### Task Methods
+
+| Method | Description |
+|--------|-------------|
+| `create_task(attrs)` | Create a new task |
+| `find_task(id)` | Find task by ID |
+| `list_tasks(filters)` | List tasks with filters |
+| `update_task(id, attrs)` | Update task attributes |
+| `start_task(id)` | Mark as in_progress |
+| `close_task(id, summary:)` | Mark as closed |
+| `block_task(id, reason:)` | Mark as blocked |
+| `reopen_task(id)` | Reopen closed task |
+| `delete_task(id)` | Delete task |
+
+#### Plan Methods
+
+| Method | Description |
+|--------|-------------|
+| `create_plan(title, description:)` | Create a Plan |
+| `add_step(plan_id, title, attrs)` | Add step to Plan |
+| `start_plan(plan_id, title:)` | Create persistent Workflow |
+| `execute_plan(plan_id, title:)` | Create ephemeral Workflow |
+| `list_plans` | List all Plans |
+| `list_workflows(plan_id:)` | List Workflows |
+
+#### Dependency Methods
+
+| Method | Description |
+|--------|-------------|
+| `add_dependency(source, target, type:)` | Add dependency |
+| `remove_dependency(source, target)` | Remove dependency |
+| `ready_tasks(filters)` | Find tasks with no blockers |
+| `dependency_tree(task_id)` | Get dependency tree |
+
+#### Label Methods
+
+| Method | Description |
+|--------|-------------|
+| `add_label(task_id, label)` | Add label to task |
+| `remove_label(task_id, label)` | Remove label |
+| `labels_for(task_id)` | Get task's labels |
+| `all_labels` | List all labels |
+
+### TrakFlow::Models::Task
+
+Represents a task.
+
+```ruby
+task = trak.find_task("tf-abc123")
+
+# Properties
+task.id           # => "tf-abc123"
+task.title        # => "Implement feature"
+task.description  # => "Detailed description"
+task.status       # => "in_progress"
+task.priority     # => 1
+task.type         # => "feature"
+task.assignee     # => "claude"
+task.parent_id    # => nil
+task.created_at   # => Time
+task.updated_at   # => Time
+task.closed_at    # => nil
+task.notes        # => "..."
+task.content_hash # => "a1b2c3d4"
+
+# Plan/Workflow properties
+task.plan           # => false
+task.source_plan_id # => nil
+task.ephemeral      # => false
+
+# Predicates
+task.open?        # => false
+task.closed?      # => false
+task.in_progress? # => true
+task.blocked?     # => false
+task.plan?        # => false
+task.workflow?    # => false
+task.ephemeral?   # => false
+task.executable?  # => true
+task.discardable? # => false
+```
+
+### TrakFlow::Storage::Database
+
+SQLite storage layer.
+
+```ruby
+db = TrakFlow::Storage::Database.new("/path/to/trak_flow.db")
+
+# Query methods
+db.find_task(id)
+db.list_tasks(filters)
+db.find_ready_tasks
+db.find_plans
+db.find_workflows(plan_id:)
+
+# Write methods
+db.insert_task(task)
+db.update_task(task)
+db.delete_task(id)
+
+# Dependency methods
+db.add_dependency(source, target, type)
+db.remove_dependency(source, target)
+db.dependencies_for(task_id)
+```
+
+### TrakFlow::Storage::Jsonl
+
+JSONL file storage.
+
+```ruby
+jsonl = TrakFlow::Storage::Jsonl.new("/path/to/issues.jsonl")
+
+# Load all tasks
+tasks = jsonl.load_all
+
+# Append a task
+jsonl.append(task)
+
+# Rewrite entire file
+jsonl.save_all(tasks)
+```
+
+## Examples
+
+### Create and Manage Tasks
+
+```ruby
+require 'trak_flow'
+
+trak = TrakFlow.new
+
+# Create a feature with subtasks
+feature = trak.create_task(
+  title: "User Authentication",
+  type: "epic",
+  priority: 1
+)
+
+login = trak.create_task(
+  title: "Login page",
+  parent_id: feature.id
+)
+
+logout = trak.create_task(
+  title: "Logout functionality",
+  parent_id: feature.id
+)
+
+# Add dependencies
+trak.add_dependency(login.id, logout.id)
+
+# Find ready work
+ready = trak.ready_tasks
+puts "Ready to work on: #{ready.map(&:title)}"
+
+# Complete the workflow
+trak.start_task(login.id)
+trak.close_task(login.id, summary: "Implemented login")
+
+# Now logout is ready
+ready = trak.ready_tasks
+puts "Now ready: #{ready.map(&:title)}"
+```
+
+### Work with Plans
+
+```ruby
+require 'trak_flow'
+
+trak = TrakFlow.new
+
+# Create a release plan
+plan = trak.create_plan("Release Process")
+trak.add_step(plan.id, "Update version number")
+trak.add_step(plan.id, "Update CHANGELOG")
+trak.add_step(plan.id, "Run tests")
+trak.add_step(plan.id, "Create release tag")
+trak.add_step(plan.id, "Publish gem")
+
+# Start a release workflow
+workflow = trak.start_plan(plan.id, title: "Release v1.0.0")
+
+# Work through the steps
+workflow.tasks.each do |task|
+  puts "Starting: #{task.title}"
+  trak.start_task(task.id)
+  # ... do the work ...
+  trak.close_task(task.id)
+  puts "Completed: #{task.title}"
+end
+
+# Summarize the workflow
+trak.summarize_workflow(workflow.id, summary: "Released v1.0.0")
+```
+
+### Filtering and Querying
+
+```ruby
+require 'trak_flow'
+
+trak = TrakFlow.new
+
+# Filter by multiple criteria
+bugs = trak.list_tasks(
+  status: "open",
+  type: "bug",
+  priority: [0, 1]  # Critical or High
+)
+
+# Filter by label
+frontend = trak.list_tasks(label: "frontend")
+
+# Complex queries using the database directly
+db = trak.database
+high_priority_ready = db.list_tasks.select do |task|
+  task.priority <= 1 && db.is_ready?(task.id)
+end
+```
+
+### Dependency Analysis
+
+```ruby
+require 'trak_flow'
+
+trak = TrakFlow.new
+
+# Get dependency tree
+tree = trak.dependency_tree("tf-abc123")
+
+puts "Blocked by:"
+tree[:blocked_by].each { |t| puts "  - #{t.title}" }
+
+puts "Blocks:"
+tree[:blocks].each { |t| puts "  - #{t.title}" }
+
+# Check for cycles
+if trak.would_create_cycle?("tf-a", "tf-b")
+  puts "Warning: would create a cycle!"
+end
+```
+
+## Error Handling
+
+```ruby
+require 'trak_flow'
+
+trak = TrakFlow.new
+
+begin
+  task = trak.find_task("invalid-id")
+rescue TrakFlow::NotFoundError => e
+  puts "Task not found: #{e.message}"
+end
+
+begin
+  trak.create_task(title: "")  # Empty title
+rescue TrakFlow::ValidationError => e
+  puts "Validation failed: #{e.message}"
+end
+
+begin
+  trak.add_dependency("tf-a", "tf-a")  # Self-reference
+rescue TrakFlow::DependencyError => e
+  puts "Invalid dependency: #{e.message}"
+end
+```
+
+## Thread Safety
+
+The library is designed for single-threaded use. For concurrent access:
+
+1. Use separate `TrakFlow` instances per thread
+2. Or use the MCP server for concurrent access
+3. The SQLite database handles concurrent reads safely

data/docs/api/task-model.md

@@ -0,0 +1,341 @@
+# Task Model Reference
+
+The Task model is the core data structure in TrakFlow.
+
+## Class: TrakFlow::Models::Task
+
+### Initialization
+
+```ruby
+task = TrakFlow::Models::Task.new(
+  title: "Task title",
+  description: "Optional description",
+  type: "task",
+  priority: 2,
+  assignee: nil,
+  parent_id: nil,
+  plan: false,
+  ephemeral: false
+)
+```
+
+### Attributes
+
+#### Required Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `title` | String | Task title (required) |
+
+#### Auto-Generated Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `id` | String | Unique ID (e.g., `tf-abc123`) |
+| `created_at` | Time | Creation timestamp |
+| `updated_at` | Time | Last update timestamp |
+| `content_hash` | String | Hash of task content |
+
+#### Optional Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `description` | String | `nil` | Detailed description |
+| `status` | String | `"open"` | Current status |
+| `priority` | Integer | `2` | Priority level (0-4) |
+| `type` | String | `"task"` | Task type |
+| `assignee` | String | `nil` | Assigned user/agent |
+| `parent_id` | String | `nil` | Parent task ID |
+| `closed_at` | Time | `nil` | When task was closed |
+| `notes` | String | `""` | Free-form notes |
+
+#### Plan/Workflow Attributes
+
+| Attribute | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `plan` | Boolean | `false` | Is this a Plan blueprint |
+| `source_plan_id` | String | `nil` | Source Plan for Workflows |
+| `ephemeral` | Boolean | `false` | Is this ephemeral |
+
+### Status Values
+
+| Status | Description |
+|--------|-------------|
+| `open` | Ready to work on |
+| `in_progress` | Currently being worked on |
+| `blocked` | Waiting on something |
+| `deferred` | Postponed for later |
+| `closed` | Completed |
+| `tombstone` | Archived (permanent) |
+| `pinned` | Highlighted for visibility |
+
+### Type Values
+
+| Type | Description |
+|------|-------------|
+| `task` | General task (default) |
+| `bug` | Bug fix |
+| `feature` | New feature |
+| `epic` | Large initiative |
+| `chore` | Maintenance work |
+
+### Priority Levels
+
+| Level | Name | Description |
+|-------|------|-------------|
+| 0 | Critical | Urgent, drop everything |
+| 1 | High | Important, do soon |
+| 2 | Medium | Normal priority (default) |
+| 3 | Low | Do when time permits |
+| 4 | Backlog | Future consideration |
+
+## Predicate Methods
+
+```ruby
+task = TrakFlow::Models::Task.new(title: "Example")
+
+# Status predicates
+task.open?        # status == "open"
+task.closed?      # status == "closed" or "tombstone"
+task.in_progress? # status == "in_progress"
+task.blocked?     # status == "blocked"
+task.deferred?    # status == "deferred"
+
+# Type predicates
+task.bug?         # type == "bug"
+task.feature?     # type == "feature"
+task.epic?        # type == "epic"
+task.chore?       # type == "chore"
+
+# Plan/Workflow predicates
+task.plan?        # plan == true
+task.workflow?    # source_plan_id present and not a plan
+task.ephemeral?   # ephemeral == true
+
+# Capability predicates
+task.executable?  # not a plan (can be executed)
+task.discardable? # ephemeral (can be discarded)
+```
+
+## Instance Methods
+
+### Status Transitions
+
+```ruby
+task.start!       # -> in_progress
+task.block!       # -> blocked
+task.defer!       # -> deferred
+task.close!       # -> closed
+task.reopen!      # -> open
+task.archive!     # -> tombstone
+```
+
+### Content Management
+
+```ruby
+# Update timestamp
+task.touch!
+
+# Append to notes with trace entry
+task.append_trace("STARTED", "Beginning implementation")
+# Adds: [2024-01-15T10:00:00Z] [STARTED] Beginning implementation
+
+# Compute content hash
+task.compute_hash!
+```
+
+### Serialization
+
+```ruby
+# Convert to Hash
+hash = task.to_h
+
+# Convert to JSON
+json = task.to_json
+
+# Create from Hash
+task = TrakFlow::Models::Task.from_hash(hash)
+
+# Create from JSON
+task = TrakFlow::Models::Task.from_json(json)
+```
+
+## Validation
+
+Tasks are validated on creation and update:
+
+```ruby
+task = TrakFlow::Models::Task.new(title: "")
+task.valid?  # => false
+task.errors  # => ["Title is required"]
+
+task = TrakFlow::Models::Task.new(
+  title: "Test",
+  status: "invalid"
+)
+task.valid?  # => false
+task.errors  # => ["Invalid status: invalid"]
+```
+
+### Validation Rules
+
+| Rule | Error Message |
+|------|---------------|
+| Title required | "Title is required" |
+| Valid status | "Invalid status: {status}" |
+| Valid priority | "Invalid priority: {priority}" |
+| Valid type | "Invalid type: {type}" |
+| Plans can't be ephemeral | "Plans cannot be ephemeral" |
+| Plans stay open | "Plans cannot change status" |
+| Plans can't derive from Plans | "Plans cannot be derived from other Plans" |
+
+## ID Generation
+
+IDs are generated using content hashing:
+
+```ruby
+task = TrakFlow::Models::Task.new(title: "Example")
+task.generate_id!
+task.id  # => "tf-a1b2c3d4"
+```
+
+The ID is derived from:
+- Title
+- Description
+- Type
+- Creation timestamp
+- Random salt (for uniqueness)
+
+### ID Format
+
+```
+tf-xxxxxxxx
+```
+
+- `tf-` prefix identifies TrakFlow tasks
+- 8 character hex hash
+
+## JSON Representation
+
+```json
+{
+  "id": "tf-abc123",
+  "title": "Implement feature X",
+  "description": "Detailed description here",
+  "status": "in_progress",
+  "priority": 1,
+  "type": "feature",
+  "assignee": "claude",
+  "parent_id": null,
+  "created_at": "2024-01-15T10:00:00Z",
+  "updated_at": "2024-01-15T14:30:00Z",
+  "closed_at": null,
+  "content_hash": "a1b2c3d4",
+  "plan": false,
+  "source_plan_id": null,
+  "ephemeral": false,
+  "notes": ""
+}
+```
+
+## Content Hash
+
+The content hash enables:
+
+1. **Change detection** - Know when content was modified
+2. **Deduplication** - Identify identical tasks
+3. **Sync support** - Merge changes from multiple sources
+
+### Hash Computation
+
+```ruby
+# Automatically computed on save
+task.compute_hash!
+
+# Hash is based on:
+# - title
+# - description
+# - type
+# - priority
+# - assignee
+# - status
+# - parent_id
+# - plan
+# - source_plan_id
+# - ephemeral
+# - notes
+
+# Excluded from hash:
+# - id
+# - created_at
+# - updated_at
+# - closed_at
+# - content_hash itself
+```
+
+## Examples
+
+### Creating Different Task Types
+
+```ruby
+# Bug
+bug = TrakFlow::Models::Task.new(
+  title: "Fix null pointer exception",
+  type: "bug",
+  priority: 0
+)
+
+# Feature
+feature = TrakFlow::Models::Task.new(
+  title: "Add OAuth support",
+  type: "feature",
+  priority: 1,
+  description: "Support Google and GitHub OAuth"
+)
+
+# Epic with children
+epic = TrakFlow::Models::Task.new(
+  title: "User Management",
+  type: "epic"
+)
+
+child = TrakFlow::Models::Task.new(
+  title: "Login page",
+  parent_id: epic.id
+)
+```
+
+### Creating a Plan
+
+```ruby
+plan = TrakFlow::Models::Task.new(
+  title: "Deploy Checklist",
+  plan: true
+)
+
+plan.plan?       # => true
+plan.executable? # => false
+```
+
+### Status Workflow
+
+```ruby
+task = TrakFlow::Models::Task.new(title: "Example")
+
+task.status      # => "open"
+
+task.start!
+task.status      # => "in_progress"
+
+task.block!
+task.status      # => "blocked"
+task.notes       # Contains trace entry
+
+task.reopen!
+task.status      # => "open"
+
+task.start!
+task.close!
+task.status      # => "closed"
+task.closed_at   # => Time.now
+```