trak_flow 0.1.3 → 0.2.0

data/docs/mcp/overview.md

@@ -18,20 +18,42 @@ require 'trak_flow'
 require 'trak_flow/mcp'
 
 # Start the MCP server over STDIO
-TrakFlow::Mcp::Server.new.run
+TrakFlow::Mcp::Server.new.start_stdio
 ```
 
 ### HTTP/SSE Transport (For Remote Access)
 
+Requires the optional `rackup` gem plus a Rack server that supports
+`rack.hijack` (Puma, Falcon, WEBrick, ...) in your bundle.
+
 ```ruby
 require 'trak_flow'
 require 'trak_flow/mcp'
 
-# Start with HTTP/SSE transport
+# Start with HTTP/SSE transport on whatever Rack server the bundle carries
 server = TrakFlow::Mcp::Server.new
-server.run_http(port: 9292)
+server.start_http(port: 3333)
+
+# Or name the server explicitly (also settable via config mcp.handler
+# or the TF_MCP__HANDLER environment variable)
+server.start_http(port: 3333, handler: "puma")
+```
+
+### Embedding in an Existing Rack Application
+
+If your application already runs its own Rack server, don't start a second
+one — mount the MCP transport as a plain Rack app:
+
+```ruby
+# config.ru of the host application
+map "/mcp" do
+  run TrakFlow::Mcp::Server.new.rack_app
+end
 ```
 
+One process, one server — the host's server choice (Puma, Falcon, ...)
+applies, as long as it supports `rack.hijack` for SSE.
+
 ## Architecture
 
 ```mermaid
@@ -49,7 +71,7 @@ graph LR
 
     subgraph "TrakFlow Core"
         DB[(SQLite)]
-        JSONL[issues.jsonl]
+        JSONL[tasks.jsonl]
     end
 
     LLM <--> Client
@@ -191,13 +213,12 @@ Currently, the MCP server does not implement authentication. For production use:
 
 ## Configuration
 
-Environment variables:
+Environment variables (via [anyway_config](https://github.com/palkan/anyway_config), prefix `TF_`):
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `TRAK_FLOW_DIR` | Data directory | `.trak_flow` |
-| `TRAK_FLOW_MCP_PORT` | HTTP port | `9292` |
-| `TRAK_FLOW_MCP_HOST` | HTTP host | `127.0.0.1` |
+| `TF_MCP__PORT` | HTTP port | `3333` |
+| `TF_MCP__HANDLER` | Rackup handler name for the HTTP server (e.g. `puma`, `falcon`) | auto-detect from bundle |
 
 ## Next Steps
 

data/examples/cli_demo.sh

@@ -281,7 +281,7 @@ echo "The JSONL file is Git-friendly for version control."
 echo ""
 
 run_cmd "ls -la .trak_flow/"
-run_cmd "head -5 .trak_flow/issues.jsonl"
+run_cmd "head -5 .trak_flow/tasks.jsonl"
 
 pause
 

data/examples/mcp/Gemfile.lock

@@ -1,14 +1,12 @@
 PATH
   remote: .
   specs:
-    trak_flow (0.1.0)
+    trak_flow (0.1.4)
       anyway_config (~> 2.0)
       debug_me
       fast-mcp
       oj (~> 3.16)
       pastel (~> 0.8)
-      puma (~> 6.0)
-      rackup (~> 2.0)
       sequel (~> 5.0)
       sqlite3 (~> 2.0)
       thor (~> 1.3)
@@ -20,7 +18,7 @@ GEM
   specs:
     addressable (2.8.8)
       public_suffix (>= 2.0.2, < 8.0)
-    ansi (1.5.0)
+    ansi (1.6.0)
     anyway_config (2.7.2)
       ruby-next-core (~> 1.0)
     ast (2.4.3)
@@ -59,6 +57,17 @@ GEM
       dry-inflector (~> 1.0)
       dry-logic (~> 1.4)
       zeitwerk (~> 2.6)
+    event_stream_parser (1.0.0)
+    faraday (2.14.3)
+      faraday-net_http (>= 2.0, < 3.5)
+      json
+      logger
+    faraday-multipart (1.2.0)
+      multipart-post (~> 2.0)
+    faraday-net_http (3.4.4)
+      net-http (~> 0.5)
+    faraday-retry (2.4.0)
+      faraday (~> 2.0)
     fast-mcp (1.6.0)
       addressable (~> 2.8)
       base64
@@ -66,66 +75,113 @@ GEM
       json (~> 2.0)
       mime-types (~> 3.4)
       rack (>= 2.0, < 4.0)
+    fasterer (0.11.0)
+      ruby_parser (>= 3.19.1)
+    hana (1.3.7)
+    http-2 (1.2.2)
+    httpx (1.8.3)
+      http-2 (>= 1.2.0)
     json (2.18.0)
-    language_server-protocol (3.17.0.5)
+    json-schema (6.2.0)
+      addressable (~> 2.8)
+      bigdecimal (>= 3.1, < 5)
+    json_schemer (2.5.0)
+      bigdecimal
+      hana (~> 1.3)
+      regexp_parser (~> 2.0)
+      simpleidn (~> 0.2)
+    language_server-protocol (3.17.0.6)
     lint_roller (1.1.0)
     logger (1.7.0)
+    marcel (1.2.1)
     mime-types (3.7.0)
       logger
       mime-types-data (~> 3.2025, >= 3.2025.0507)
     mime-types-data (3.2025.0924)
     minitest (5.27.0)
-    minitest-reporters (1.7.1)
+    minitest-reporters (1.8.0)
       ansi
       builder
-      minitest (>= 5.0)
+      minitest (>= 5.0, < 7)
       ruby-progressbar
+    multipart-post (2.4.1)
+    net-http (0.9.1)
+      uri (>= 0.11.1)
     nio4r (2.7.5)
     oj (3.16.13)
       bigdecimal (>= 3.0)
       ostruct (>= 0.2)
     ostruct (0.6.3)
-    parallel (1.27.0)
-    parser (3.3.10.0)
+    parallel (2.2.0)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
       racc
     pastel (0.8.0)
       tty-color (~> 0.5)
-    prism (1.7.0)
-    public_suffix (7.0.0)
-    puma (6.6.1)
+    prism (1.9.0)
+    public_suffix (7.0.5)
+    puma (8.0.2)
       nio4r (~> 2.0)
     racc (1.8.1)
     rack (3.2.4)
     rackup (2.3.1)
       rack (>= 3)
     rainbow (3.1.1)
-    rake (13.3.1)
+    rake (13.4.2)
+    reek (6.5.0)
+      dry-schema (~> 1.13)
+      logger (~> 1.6)
+      parser (~> 3.3.0)
+      rainbow (>= 2.0, < 4.0)
+      rexml (~> 3.1)
     regexp_parser (2.11.3)
-    rubocop (1.82.1)
-      json (~> 2.3)
+    rexml (3.4.4)
+    rubocop (1.90.0)
+      json (>= 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
-      parallel (~> 1.10)
+      parallel (>= 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.48.0, < 2.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.49.0)
+    rubocop-ast (1.50.0)
       parser (>= 3.3.7.2)
       prism (~> 1.7)
     ruby-next-core (1.1.2)
     ruby-progressbar (1.13.0)
+    ruby_llm (1.16.0)
+      base64
+      event_stream_parser (~> 1)
+      faraday (>= 1.10.0)
+      faraday-multipart (>= 1)
+      faraday-net_http (>= 1)
+      faraday-retry (>= 1)
+      marcel (~> 1)
+      ruby_llm-schema (~> 0)
+      zeitwerk (~> 2)
+    ruby_llm-mcp (1.0.1)
+      httpx (~> 1.4)
+      json-schema (>= 5.0, < 7)
+      json_schemer (~> 2.4)
+      ruby_llm (~> 1.9)
+      zeitwerk (~> 2)
+    ruby_llm-schema (0.4.0)
+    ruby_parser (3.22.0)
+      racc (~> 1.5)
+      sexp_processor (~> 4.16)
     sequel (5.100.0)
       bigdecimal
+    sexp_processor (4.17.5)
     simplecov (0.22.0)
       docile (~> 1.1)
       simplecov-html (~> 0.11)
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
+    simpleidn (0.3.0)
     sqlite3 (2.9.0-arm64-darwin)
     strings (0.2.1)
       strings-ansi (~> 0.2)
@@ -144,6 +200,7 @@ GEM
       tty-screen (~> 0.8)
     unicode-display_width (2.6.0)
     unicode_utils (1.4.0)
+    uri (1.1.1)
     zeitwerk (2.7.4)
 
 PLATFORMS
@@ -151,75 +208,104 @@ PLATFORMS
 
 DEPENDENCIES
   bundler
+  fasterer
   minitest (~> 5.0)
   minitest-reporters (~> 1.6)
+  puma (>= 7.2.1)
+  rackup
   rake (~> 13.0)
+  reek
   rubocop (~> 1.0)
+  ruby_llm
+  ruby_llm-mcp
   simplecov (~> 0.22)
   trak_flow!
 
 CHECKSUMS
   addressable (2.8.8) sha256=7c13b8f9536cf6364c03b9d417c19986019e28f7c00ac8132da4eb0fe393b057
-  ansi (1.5.0)
-  anyway_config (2.7.2)
+  ansi (1.6.0)
+  anyway_config (2.7.2) sha256=30f6b087c0b41afdd43fe46c81d65a16f052a8489dab453abaeb4ea67aa74bad
   ast (2.4.3)
   base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
   bigdecimal (3.3.1) sha256=eaa01e228be54c4f9f53bf3cc34fe3d5e845c31963e7fcc5bedb05a4e7d52218
   builder (3.3.0)
-  concurrent-ruby (1.3.6)
-  debug_me (1.1.3)
+  concurrent-ruby (1.3.6) sha256=6b56837e1e7e5292f9864f34b69c5a2cbc75c0cf5338f1ce9903d10fa762d5ab
+  debug_me (1.1.3) sha256=ae8cf61993350d9b3cbe337a7f9a0f595be5b4976c10891a4e1eacc63d09f717
   docile (1.4.1)
-  dry-configurable (1.3.0)
-  dry-core (1.2.0)
-  dry-inflector (1.2.0)
-  dry-initializer (3.2.0)
-  dry-logic (1.6.0)
-  dry-schema (1.14.1)
-  dry-types (1.8.3)
-  fast-mcp (1.6.0)
+  dry-configurable (1.3.0) sha256=882d862858567fc1210d2549d4c090f34370fc1bb7c5c1933de3fe792e18afa8
+  dry-core (1.2.0) sha256=0cc5a7da88df397f153947eeeae42e876e999c1e30900f3c536fb173854e96a1
+  dry-inflector (1.2.0) sha256=22f5d0b50fd57074ae57e2ca17e3b300e57564c218269dcf82ff3e42d3f38f2e
+  dry-initializer (3.2.0) sha256=37d59798f912dc0a1efe14a4db4a9306989007b302dcd5f25d0a2a20c166c4e3
+  dry-logic (1.6.0) sha256=da6fedbc0f90fc41f9b0cc7e6f05f5d529d1efaef6c8dcc8e0733f685745cea2
+  dry-schema (1.14.1) sha256=2fcd7539a7099cacae6a22f6a3a2c1846fe5afeb1c841cde432c89c6cb9b9ff1
+  dry-types (1.8.3) sha256=b5d97a45e0ed273131c0c3d5bc9f5633c2d1242e092ee47401ce7d5eab65c1bc
+  event_stream_parser (1.0.0) sha256=a2683bab70126286f8184dc88f7968ffc4028f813161fb073ec90d171f7de3c8
+  faraday (2.14.3) sha256=1882247e6766615c8220b4392bf1d27f6ebb63d8e28267587cef1fb0bf37f278
+  faraday-multipart (1.2.0) sha256=7d89a949693714176f612323ca13746a2ded204031a6ba528adee788694ef757
+  faraday-net_http (3.4.4) sha256=0e78af151747ed1b00f33e25973b4bc220d7f16c00c39676817c8b12331eb588
+  faraday-retry (2.4.0) sha256=7b79c48fb7e56526faf247b12d94a680071ff40c9fda7cf1ec1549439ad11ebe
+  fast-mcp (1.6.0) sha256=d68abb45d2daab9e7ae2934417460e4bf9ac87493c585dc5bb626f1afb7d12c4
+  fasterer (0.11.0)
+  hana (1.3.7) sha256=5425db42d651fea08859811c29d20446f16af196308162894db208cac5ce9b0d
+  http-2 (1.2.2) sha256=81b5d45f50fd4cd5f8c5d09651184bec9401e3ef169c3eb3e5b003d5614a92b9
+  httpx (1.8.3) sha256=cb88f2285c4ef17164d803a640dc393d28722cba7f282ad0e7f9f926cd02dc47
   json (2.18.0) sha256=b10506aee4183f5cf49e0efc48073d7b75843ce3782c68dbeb763351c08fd505
-  language_server-protocol (3.17.0.5)
+  json-schema (6.2.0) sha256=e8bff46ed845a22c1ab2bd0d7eccf831c01fe23bb3920caa4c74db4306813666
+  json_schemer (2.5.0) sha256=2f01fb4cce721a4e08dd068fc2030cffd0702a7f333f1ea2be6e8991f00ae396
+  language_server-protocol (3.17.0.6)
   lint_roller (1.1.0)
   logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
-  mime-types (3.7.0)
-  mime-types-data (3.2025.0924)
+  marcel (1.2.1) sha256=1678e9360e32f9eafa917c80029e2f6d10b2715c66a4b87b6d0da9b9cd1f859f
+  mime-types (3.7.0) sha256=dcebf61c246f08e15a4de34e386ebe8233791e868564a470c3fe77c00eed5e56
+  mime-types-data (3.2025.0924) sha256=f276bca15e59f35767cbcf2bc10e023e9200b30bd6a572c1daf7f4cc24994728
   minitest (5.27.0)
-  minitest-reporters (1.7.1)
+  minitest-reporters (1.8.0)
+  multipart-post (2.4.1) sha256=9872d03a8e552020ca096adadbf5e3cb1cd1cdd6acd3c161136b8a5737cdb4a8
+  net-http (0.9.1) sha256=25ba0b67c63e89df626ed8fac771d0ad24ad151a858af2cc8e6a716ca4336996
   nio4r (2.7.5)
-  oj (3.16.13)
-  ostruct (0.6.3)
-  parallel (1.27.0)
-  parser (3.3.10.0)
-  pastel (0.8.0)
-  prism (1.7.0)
-  public_suffix (7.0.0) sha256=f7090b5beb0e56f9f10d79eed4d5fbe551b3b425da65877e075dad47a6a1b095
-  puma (6.6.1)
+  oj (3.16.13) sha256=b114bcb83ef884f1736b3112108f77cf9ca90aa8111a775318cc5d7a6a1e0303
+  ostruct (0.6.3) sha256=95a2ed4a4bd1d190784e666b47b2d3f078e4a9efda2fccf18f84ddc6538ed912
+  parallel (2.2.0)
+  parser (3.3.12.0)
+  pastel (0.8.0) sha256=481da9fb7d2f6e6b1a08faf11fa10363172dc40fd47848f096ae21209f805a75
+  prism (1.9.0)
+  public_suffix (7.0.5) sha256=1a8bb08f1bbea19228d3bed6e5ed908d1cb4f7c2726d18bd9cadf60bc676f623
+  puma (8.0.2)
   racc (1.8.1)
-  rack (3.2.4)
+  rack (3.2.4) sha256=5d74b6f75082a643f43c1e76b419c40f0e5527fcfee1e669ac1e6b73c0ccb6f6
   rackup (2.3.1)
   rainbow (3.1.1)
-  rake (13.3.1)
-  regexp_parser (2.11.3)
-  rubocop (1.82.1)
-  rubocop-ast (1.49.0)
-  ruby-next-core (1.1.2)
+  rake (13.4.2)
+  reek (6.5.0)
+  regexp_parser (2.11.3) sha256=ca13f381a173b7a93450e53459075c9b76a10433caadcb2f1180f2c741fc55a4
+  rexml (3.4.4)
+  rubocop (1.90.0)
+  rubocop-ast (1.50.0)
+  ruby-next-core (1.1.2) sha256=1b095fe2e45929f2581b3ecdb8d92b601ce4d72c12a466057c10e23b6f0c4512
   ruby-progressbar (1.13.0)
-  sequel (5.100.0)
+  ruby_llm (1.16.0) sha256=26bd5310cf2ce55f74a60f8aae0b0d0327b586ff4532c84828103c3b2b905a18
+  ruby_llm-mcp (1.0.1) sha256=22121bfdea1874935debdd9cee0235d02473885ce8347cf745a323f0707fd248
+  ruby_llm-schema (0.4.0) sha256=e930f5a5316f9301bff3fb7fe572e44727d05bb8e50621001bbb49a47d63b8da
+  ruby_parser (3.22.0)
+  sequel (5.100.0) sha256=cb0329b62287a01db68eead46759c14497a3fae01b174e2c41da108a9e9b4a12
+  sexp_processor (4.17.5)
   simplecov (0.22.0)
   simplecov-html (0.13.2)
   simplecov_json_formatter (0.1.4)
-  sqlite3 (2.9.0-arm64-darwin)
-  strings (0.2.1)
-  strings-ansi (0.2.0)
-  thor (1.4.0)
-  trak_flow (0.1.0)
-  tty-color (0.6.0)
-  tty-cursor (0.7.1)
-  tty-screen (0.8.2)
-  tty-spinner (0.9.3)
-  tty-table (0.12.0)
-  unicode-display_width (2.6.0)
-  unicode_utils (1.4.0)
+  simpleidn (0.3.0) sha256=12ca730bed2f3db04d11e9bfd1bca3e11fb37f55b21eb2e9793fb5814bf54d03
+  sqlite3 (2.9.0-arm64-darwin) sha256=a917bd9b84285766ff3300b7d79cd583f5a067594c8c1263e6441618c04a6ed3
+  strings (0.2.1) sha256=933293b3c95cf85b81eb44b3cf673e3087661ba739bbadfeadf442083158d6fb
+  strings-ansi (0.2.0) sha256=90262d760ea4a94cc2ae8d58205277a343409c288cbe7c29416b1826bd511c88
+  thor (1.4.0) sha256=8763e822ccb0f1d7bee88cde131b19a65606657b847cc7b7b4b82e772bcd8a3d
+  trak_flow (0.1.4)
+  tty-color (0.6.0) sha256=6f9c37ca3a4e2367fb2e6d09722762647d6f455c111f05b59f35730eeb24332a
+  tty-cursor (0.7.1) sha256=79534185e6a777888d88628b14b6a1fdf5154a603f285f80b1753e1908e0bf48
+  tty-screen (0.8.2) sha256=c090652115beae764336c28802d633f204fb84da93c6a968aa5d8e319e819b50
+  tty-spinner (0.9.3) sha256=0e036f047b4ffb61f2aa45f5a770ec00b4d04130531558a94bfc5b192b570542
+  tty-table (0.12.0) sha256=fdc27a4750835c1a16efe19a0b857e3ced3652cc7aceafe6dca94908965b9939
+  unicode-display_width (2.6.0) sha256=12279874bba6d5e4d2728cef814b19197dbb10d7a7837a869bab65da943b7f5a
+  unicode_utils (1.4.0) sha256=b922d0cf2313b6b7136ada6645ce7154ffc86418ca07d53b058efe9eb72f2a40
+  uri (1.1.1) sha256=379fa58d27ffb1387eaada68c749d1426738bd0f654d812fcc07e7568f5c57c6
   zeitwerk (2.7.4) sha256=2bef90f356bdafe9a6c2bd32bcd804f83a4f9b8bc27f3600fff051eb3edcec8b
 
 BUNDLED WITH

data/lib/trak_flow/cli/admin_commands.rb

@@ -13,33 +13,21 @@ module TrakFlow
       option :cascade, type: :boolean, default: false, desc: "Also delete children"
       def cleanup
         with_database do |db|
-          cutoff = Time.now.utc - (options[:older_than] * 24 * 60 * 60)
-          candidates = db.list_tasks(status: "closed", include_tombstones: true)
-                         .select { |i| i.closed_at && i.closed_at < cutoff }
+          candidates = cleanup_candidates(db)
+          count = candidates.size
 
           if candidates.empty?
             puts "No tasks to clean up"
             return
           end
 
-          if options[:dry_run]
-            puts "Would delete #{candidates.size} task(s):"
-            candidates.each { |i| puts "  #{i.id}: #{i.title}" }
-            return
-          end
+          return print_cleanup_dry_run(candidates) if options[:dry_run]
+          return unless options[:force] || confirm_cleanup?(count)
 
-          unless options[:force]
-            puts "About to delete #{candidates.size} task(s). Continue? (y/n)"
-            return unless $stdin.gets.strip.downcase == "y"
-          end
-
-          candidates.each do |task|
-            db.child_tasks(task.id).each { |c| db.delete_task(c.id) } if options[:cascade]
-            db.delete_task(task.id)
-          end
+          delete_candidates(db, candidates)
 
-          output({ deleted: candidates.size }) do
-            puts "Deleted #{candidates.size} task(s)"
+          output({ deleted: count }) do
+            puts "Deleted #{count} task(s)"
           end
         end
       end
@@ -49,28 +37,13 @@ module TrakFlow
       option :apply, type: :boolean, default: false, desc: "Apply compaction"
       def compact
         with_database do |db|
-          stats = {
-            total_tasks: db.all_task_ids.size,
-            closed_tasks: db.list_tasks(status: "closed", include_tombstones: true).size,
-            ephemeral: db.find_ephemeral_workflows.size,
-            plans: db.find_plans.size,
-            workflows: db.find_workflows.size
-          }
-
           if options[:analyze]
+            stats = compaction_stats(db)
             output(stats) do
               stats.each { |k, v| puts "#{k}: #{v}" }
             end
-            return
-          end
-
-          if options[:apply]
-            db.list_tasks(status: "closed").each do |task|
-              next unless task.closed_at && task.closed_at < (Time.now.utc - 30 * 24 * 60 * 60)
-
-              task.status = "tombstone"
-              db.update_task(task)
-            end
+          elsif options[:apply]
+            tombstone_old_closed_tasks(db)
             puts "Compaction complete"
           else
             puts "Use --analyze to see stats or --apply to compact"
@@ -87,13 +60,13 @@ module TrakFlow
           dep_graph = Graph::DependencyGraph.new(db)
 
           graph_output = case options[:format]
-            when "svg" then dep_graph.to_svg(include_closed: options[:include_closed])
-            else dep_graph.to_dot(include_closed: options[:include_closed])
-            end
+                         when "svg" then dep_graph.to_svg(include_closed: options[:include_closed])
+                         else dep_graph.to_dot(include_closed: options[:include_closed])
+                         end
 
-          if options[:output]
-            File.write(options[:output], graph_output)
-            puts "Graph written to #{options[:output]}"
+          if (output_path = options[:output])
+            File.write(output_path, graph_output)
+            puts "Graph written to #{output_path}"
           else
             puts graph_output
           end
@@ -103,32 +76,77 @@ module TrakFlow
       desc "analyze", "Analyze the task graph"
       def analyze
         with_database do |db|
-          dep_graph = Graph::DependencyGraph.new(db)
-          analysis = dep_graph.analyze
-
-          output(analysis) do
-            analysis.each do |k, v|
-              if v.is_a?(Array)
-                puts "#{k}:"
-                v.each { |item| puts "  - #{item}" }
-              else
-                puts "#{k}: #{v}"
-              end
-            end
-          end
+          analysis = Graph::DependencyGraph.new(db).analyze
+          output(analysis) { print_analysis(analysis) }
         end
       end
 
       private
 
+      def print_analysis(analysis)
+        analysis.each do |k, v|
+          if v.is_a?(Array)
+            puts "#{k}:"
+            v.each { |item| puts "  - #{item}" }
+          else
+            puts "#{k}: #{v}"
+          end
+        end
+      end
+
+      # Closed tasks (tombstones included) whose closed_at is older than --older-than days.
+      def cleanup_candidates(db)
+        cutoff = Time.now.utc - (options[:older_than] * 24 * 60 * 60)
+        db.list_tasks(status: "closed", include_tombstones: true)
+          .select { |i| i.closed_at && i.closed_at < cutoff }
+      end
+
+      def print_cleanup_dry_run(candidates)
+        puts "Would delete #{candidates.size} task(s):"
+        candidates.each { |i| puts "  #{i.id}: #{i.title}" }
+      end
+
+      def confirm_cleanup?(count)
+        puts "About to delete #{count} task(s). Continue? (y/n)"
+        $stdin.gets.strip.downcase == "y"
+      end
+
+      def delete_candidates(db, candidates)
+        candidates.each do |task|
+          db.child_tasks(task.id).each { |c| db.delete_task(c.id) } if options[:cascade]
+          db.delete_task(task.id)
+        end
+      end
+
+      def compaction_stats(db)
+        {
+          total_tasks: db.all_task_ids.size,
+          closed_tasks: db.list_tasks(status: "closed", include_tombstones: true).size,
+          ephemeral: db.find_ephemeral_workflows.size,
+          plans: db.find_plans.size,
+          workflows: db.find_workflows.size
+        }
+      end
+
+      # Marks closed tasks older than 30 days as tombstones.
+      def tombstone_old_closed_tasks(db)
+        cutoff = Time.now.utc - (30 * 24 * 60 * 60)
+        db.list_tasks(status: "closed").each do |task|
+          next unless task.closed_at && task.closed_at < cutoff
+
+          task.status = "tombstone"
+          db.update_task(task)
+        end
+      end
+
       # Delegate helper methods to parent CLI
-      def with_database(&block) = CLI.new.with_database(&block)
+      def with_database(&) = CLI.new.with_database(&)
 
-      def output(json_data, &human_block)
+      def output(json_data)
         if options[:json]
           puts Oj.dump(json_data, mode: :compat, indent: 2)
         else
-          human_block.call
+          yield
         end
       end
     end

data/lib/trak_flow/cli/config_commands.rb

@@ -103,7 +103,7 @@ module TrakFlow
 
         # Load existing config or create new
         config_data = if File.exist?(config_path)
-                        YAML.safe_load(File.read(config_path), permitted_classes: [Symbol], symbolize_names: true) || {}
+                        YAML.safe_load_file(config_path, permitted_classes: [Symbol], symbolize_names: true) || {}
                       else
                         {}
                       end
@@ -161,20 +161,18 @@ module TrakFlow
         @pastel ||= Pastel.new
       end
 
-      def output(json_data, &human_block)
+      def output(json_data)
         if options[:json]
           puts Oj.dump(json_data, mode: :compat, indent: 2)
         else
-          human_block.call
+          yield
         end
       end
 
       def determine_config_path(global)
-        if global
-          XDG_CONFIG_PATH
-        elsif File.exist?(PROJECT_CONFIG_PATH)
-          File.expand_path(PROJECT_CONFIG_PATH)
-        elsif File.directory?(".trak_flow")
+        return XDG_CONFIG_PATH if global
+
+        if File.exist?(PROJECT_CONFIG_PATH) || File.directory?(".trak_flow")
           File.expand_path(PROJECT_CONFIG_PATH)
         else
           XDG_CONFIG_PATH
@@ -235,12 +233,9 @@ module TrakFlow
         when "false" then false
         when "nil", "null" then nil
         else
-          # Try integer
-          if value.match?(/\A-?\d+\z/)
-            value.to_i
-          # Try float
-          elsif value.match?(/\A-?\d+\.\d+\z/)
-            value.to_f
+          case value
+          when /\A-?\d+\z/ then value.to_i
+          when /\A-?\d+\.\d+\z/ then value.to_f
           else
             # Keep as string, expand ~ for paths
             value.start_with?("~") ? File.expand_path(value) : value

data/lib/trak_flow/cli/dep_commands.rb

@@ -56,14 +56,14 @@ module TrakFlow
       end
 
       # Delegate helper methods to parent CLI
-      def with_database(&block) = CLI.new.with_database(&block)
+      def with_database(&) = CLI.new.with_database(&)
       def status_icon(status) = CLI.new.status_icon(status)
 
-      def output(json_data, &human_block)
+      def output(json_data)
         if options[:json]
           puts Oj.dump(json_data, mode: :compat, indent: 2)
         else
-          human_block.call
+          yield
         end
       end
     end

data/lib/trak_flow/cli/label_commands.rb

@@ -62,13 +62,13 @@ module TrakFlow
       private
 
       # Delegate helper methods to parent CLI
-      def with_database(&block) = CLI.new.with_database(&block)
+      def with_database(&) = CLI.new.with_database(&)
 
-      def output(json_data, &human_block)
+      def output(json_data)
         if options[:json]
           puts Oj.dump(json_data, mode: :compat, indent: 2)
         else
-          human_block.call
+          yield
         end
       end
     end